NixOS

NixOS is a Linux distro tightly integrated with the Nix package manager. It is known for its declarative configuration, reproducibility, and powerful package management capabilities. It allows us to specify the operating system and the configuration of installed services and dependencies within this repository.

Why NixOS

The key features NixOS provides to us include:

• Ship the exact same software to our own, and to costumer's machines.
• Handles the entire OS configuration, from kernel parameters to the wallpaper installed.
• If things break, simple roll back to any other installed version and your ready to go again.
• Well defined update process, that cannot fail.
• We can boot any version without much hassle. Makes it easy to boot into unfinished work; test things and then go back.

The most important NixOS features in more detail.

Declarative and Reproducible Configuration

NixOS is build with the Nix package manager. The desired operating systems' state is defined inside a configuration.nix file in a purely declarative way. Thus NixOS can guaranty that the same configuration will result in the exact same system. Importantly, it does not depend on when QiTech Control is installed or what was previously installed on the computer, NixOS or not.

Next to the front- end back-end code, we also manager the Nix configuration inside this repository. Thus, system configuration, installed programs, program defaults and of course QiTech Control will always be the same for each version. Conflicting software versions or a system misconfigured are therefore, in a sense, impossible.

Atomic Updates and Rollbacks

Every commit in this repository can be understood as a separate Nix configuration that one can boot into. We use release tags to mark commits as stable versions. If we, or our costumers, want to use a specific version of QiTech Control, they simply have to specify the commit hash and let the NixOS take care of the update.

However, the Nix package manager does not simply overwrite the current system during an update. Instead, the new version is build and stored next to the current (and potentially also older) versions. Only when a version was built successfully, is it marked as bootable and can be selected during system startup. Doing so means that updates cannot break the system. Additionally to the new version showing up at boot, older versions can also be booted into. If the user decides that they are not satisfied with the newest version, they can easily rollback into an older version and use that.

By letting NixOS boot our feature branches, we can test each new feature in isolation on our hardware before merging it into the master branch. This creates development-test cycle where we can swiftly switch back and forth between different things we want to test. At no point do we have to manually revert our changes to get our production lines back into a ready-to-use state.

Development Workflow

To build Nix packages locally, you need to Nix package manager installed. Either

• Install QiTech Control's development branch on a computer or a virtual machine (recommended, see below)
• Install NixOS on a computer or a virtual machine
• Install the Nix package manager with your distro's package manager
• Install the Nix package manager manually
• Develop in a Nix docker container

Much more information and relevant links can be found at the NixOS downloads page and the installation guide. Also make sure you have Nix flakes enabled.

Most relevant commands assuming your not already familiar with building Nix flakes

Nix can be used to install relevant build dependencies and develop locally. To add the Rust Toolchain and Node package management to your current shell, run

nix develop

Run the QiTech Control server with

cargo run

Run the electron front end in dev mode with

cd electron
npm run dev

Building Packages

Packages can be build without installation via

nix flake check

Or to build just the server

nix build .#server

Or to build just the front end

nix build .#electron

Each build stores the resulting binaries (wrapper scripts) in the result directory. They can be run as is via

./result/bin/qitech-control-server

or

./result/bin/qitech-control-electron

Thanks to Nix's declarative nature, it can be expected that the packages will behave likewise when run in QiTech Control.

Installing QiTech Control

QiTech Control can be installed on top of NixOS as a standalone operating system. The following assumes you already have a working NixOS installation. If not, please refer to the NixOS installation guide.

Warning: while you can always go back to your own last generation, keep in mind that QiTech Control is not designed as a daily driver - so you most likely don't want to install it on your main laptop or PC.

1. Install git

nixos-env -i git

2. Clone QiTech Contol

git clone https://github.com/qitechgmbh/control
cd control

3. Run the Install Script (as root)

./nixos-install.sh

Note: If you install Qitech Control to develop on QiTech itself, you might want to use the dev-on-nixos branch. It is more focused on running QiTech Control manually, maybe even after change the code.

git checkout dev-on-nixos

4. Wait for the install to finish. The script will automatically boot into the newly created Nix generation featuring QiTech Control.

Updating

Updates can be installed in two different ways.

• In the QiTech Control UI, go to Setup > Update and select the version you want to install.
• By following the installation guide above - with the caveat of checking out a specific commit one wishes to install before running the installation script.

Each stable version comes with a release tag. To make sure your installation of QiTech Control is up to date, always update to the latest release tag.

To see the installed version, you can always take a look at the environment variables prefixed with QITECH_OS.

All QiTech related environment variables

• QITECH_OS: Set to true to identify NixOS deployments
• QITECH_OS_GIT_TIMESTAMP: Contains an ISO timestamp of the commit the system was built from
• QITECH_OS_GIT_COMMIT: Contains the commit hash of the system build
• QITECH_OS_GIT_ABBREVIATION: Contains the branch/tag/commit of the system build
• QITECH_OS_GIT_URL: Contains the URL of the repository the system was built from

The update process step by step

1. The user selects a version (commit/branch/tag) of the software they want to install
2. The repo is cloned to the local machine
3. Information like the commit hash, branch, tag, timestamp etc. is passed to the nix build process as environment variables QITECH_OS...
4. The nixos-switch command is run. After rebuilding & compiling the software the system reboots.
   • The nixos-switch command does the following:
   1. The system is built with the new configuration
   2. The system is switched to the new configuration
   3. The system is marked as "installed" with the new version
   4. The system is set to boot into the new version
5. The computer automatically reboots into the new version of the OS + software.

Rollback

If a version of QiTech Control breaks, you can always go back to the previous generation by running (as root)

nixos-rebuild switch --flake .#nixos --rollback

Or you can select a previous generation during boot.

Troubleshooting

The QiTech Control Server is registered as a systemd unit and can be managed as such

# View service logs
journalctl -u qitech-control-server

# Real-time log viewing
journalctl -u qitech-control-server -f

# Check service status
systemctl status qitech-control-server

# Restart service
sudo systemctl restart qitech-control-server

Run the front end from the terminal to see electron logs

# Manually start QiTech electron app
qitech-control-electron

# Kill running instances
pkill -f qitech-control-electron

The Nix-Files involved

As highlighted by a previous section, we manage the operating system configuration within this repository. The following provides an overview of the Nix-specific files contained in this repository.

• ./flake.nix- This file tells the Nix package manager that QiTech Control can be understood as a Nix flake. It tells NixOS about the two packages contained (server and electron) and that a configuration.nix can be derived from this flake.
• ./nixos/gitInfo.nix- With this file, the Nix package manager can use information about this repository during the build process. Doing so allows us to show the installed version to the user, among other things.
• ./nixos/packages/electron.nix- This file defines how our front-end package should be built.
• ./nixos/packages/server.nix- Similarly, in this file, we build our back-end, the control server.
• ./nixos/os/ci-hardware-configuration.nix- This file contains made up hardware information, only used in CI builds.
• ./nixos/os/configuration.nix- This is the main configuration file. Here we specify what QiTech Control actually looks like as an operating system.
• ./nixos/os/home.nix- In addition to the previous file, this file contains user specific configuration. It mainly configures the desktop environment and how our front-end is integrated into it.
• ./nixos/modules/qitech.nix- This file defined additional options, that can be set to adjust QiTech Control during installation.
• ./nixos/default.nix- In this file, we list the defaults that should be used when developing QiTech Control on NixOS. It lists the packages described above and standard development shell.

The Nix files in depth.

./flake.nix

The flake.nix file defines the main entry point for the Nix flake system, providing:

• Package outputs for both the server and electron frontend
• Use of the Rust beta channel with specific extensions and targets
• NixOS module export for system-wide integration

This file defines the Nix flake structure and imports for the QiTech Control system:

• Inputs:

  • nixpkgs - The NixOS package repository
  • home-manager - For managing user environment configuration
  • qitech-control - The QiTech Control software repository
  • rust-overlay - For Rust toolchain management

• Overlays:

  • Makes Rust toolchain available system-wide
  • Brings QiTech packages into the system package set

• System Configuration:

  • Creates a complete NixOS system named "nixos"
  • Incorporates QiTech modules and Home Manager
  • Applies overlays to make packages available

./nixos/packages/electron.nix

This defines how to build the Electron frontend:

• Builds and packages the Electron application with npm
• Configures desktop integration (icons, application menu entries)
• Handles proper security and sandbox settings
• Creates a wrapper script for launching the application

./nixos/packages/server.nix

This defines how to build the server component:

• Uses Rust beta toolchain
• Requires libpcap and libudev for hardware access
• Includes memory optimization for constrained build environments
• Creates dynamically linked binary with runtime dependencies

./nixos/os/configuration.nix

The main NixOS system configuration file:

• System Basics:

  • Uses systemd-boot and EFI
  • Configures the latest Linux kernel
  • Enables flakes support

• User and Group Management:

  • Creates a realtime group for low-latency operations
  • Configures the qitech user with appropriate permissions
  • Sets up the qitech-service user/group for the service

• Real-time Configuration:

  • Sets process priority, memory locking, and nice levels for real-time users
  • Disables sleep/suspend/hibernate

• Desktop Environment:

  • Configures GNOME desktop with automatic login
  • Removes unnecessary GNOME applications
  • Adds required extensions and tools

• QiTech Control Integration:

  • Enables the QiTech service
  • Configures firewall and networking
  • Sets the service to run on port 3001

• Package Management:

  • Installs the QiTech electron app system-wide
  • Adds required tools like git and GNOME extensions

./nixos/os/home.nix

The Home Manager configuration for the qitech user:

• Autostart Configuration:

  • Adds an autostart entry for the QiTech electron app

• GNOME Desktop Customization:

  • Sets custom QiTech wallpaper
  • Enables on-screen keyboard
  • Disables screen blanking, timeout, and locking
  • Configures power settings to prevent sleep

• Dock Configuration:

  • Configures the GNOME dash-to-dock extension
  • Sets the dock to be visible on all monitors
  • Pins the QiTech application to the dock

• Workspace Settings:

  • Configures display and workspace behavior
  • Sets favorite applications

./nixos/modules/qitech.nix

NixOS module for system-wide integration:

• Configures the systemd service for the server
• Sets up a dedicated user/group with appropriate permissions
• Configures udev rules for hardware access
• Sets up real-time privileges for low-latency operation
• Provides firewall configuration options
• Installs desktop integration for the Electron app

./nixos/default.nix

This file provides a non-flake way to use the packages and defines a development shell:

## Start development shell without using flakes
nix-shell ./nixos

## Build server without flakes
nix-build ./nixos -A server

## Build electron without flakes
nix-build ./nixos -A electron