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.

The Nix-Files involved

As highlighted in the 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

How we do updates

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.

More Docs

• Implementation Details
• Fresh Installation Quick Start guide