Installation and Updates

This page shows how to install QiTech OS on a panel PC, what starts on first boot, and how to update or roll back.

What runs on a panel

QiTech OS is a NixOS system built from the nixos/ folder of the control repository (NixOS explains the files). It boots into a GNOME desktop, logs in the qitech user automatically and opens the QiTech Control app full screen. The backend runs as the systemd service qitech-control-server.

flowchart LR
  subgraph PANEL["Panel PC with QiTech OS"]
    UI["<a href='https://github.com/qitechgmbh/control/blob/jse-control-v2/nixos/os/home.nix'>QiTech Control app</a><br/>Electron kiosk"]:::frontend
    SRV["<a href='https://github.com/qitechgmbh/control/blob/jse-control-v2/nixos/modules/qitech.nix'>qitech-control-server</a><br/>systemd service"]:::control
    NIC["EtherCAT port<br/>dedicated NIC"]:::hardware
    USB["USB port"]:::hardware
  end
  UI -->|"REST and Socket.IO<br/>localhost:3001"| SRV
  SRV --> NIC
  SRV --> USB
  NIC -->|"Ethernet cable"| EK["EK1100 coupler<br/>and terminals"]:::hardware
  USB -->|"USB-RS485"| LASER["Laser"]:::hardware

  classDef frontend fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  classDef control fill:#dcfce7,stroke:#15803d,color:#14532d
  classDef framework fill:#fef3c7,stroke:#b45309,color:#78350f
  classDef lib fill:#ede9fe,stroke:#6d28d9,color:#4c1d95
  classDef hardware fill:#f1f5f9,stroke:#475569,color:#0f172a

Loading

Install from the ISO

You need the panel PC, a keyboard, a USB drive of at least 4 GB and Wi-Fi with internet access. The installer erases the target drive.

1. Get the ISO. The GitHub Actions workflow Nix ISO (.github/workflows/iso.yml) builds it on every push to master, every Monday and on demand. Download the .iso from the artifacts of the latest successful run (GitHub login required), or build it yourself on an x86_64 Linux machine with Nix:

./nixos/nixos-build-iso.sh   # result/iso/*.iso

2. Flash the USB drive. Open Balena Etcher, click Flash from file, select the ISO (unzip it first if you downloaded a .zip), select the USB drive and click Flash.

3. Boot from USB. Plug in the USB drive and the keyboard, switch the panel on and open the boot menu (F7 on our mini PCs; other boards use F8, F11, F12 or Esc). Select the USB drive and press Enter.

4. Connect to the internet. The live system boots into the same desktop as an installed panel. Open the quick settings in the top-right corner and connect to Wi-Fi. Wired ports are left to EtherCAT (NetworkManager ignores all Ethernet devices), so Wi-Fi is the way in.

5. Run the installer. The dock shows two QiTech icons: the app and, on the right, Install QiTech Control. Click the right one. A terminal opens and runs nixos/nixos-setup.sh:

1. It lists the drives. Type the number of the target drive and confirm with y.
2. It partitions the drive (512 MiB EFI partition, the rest ext4) and generates the hardware configuration.
3. It clones the master branch of https://github.com/qitechgmbh/control and installs that system with nixos-install. This takes a while.
4. When it prints Installation complete!, remove the USB drive and reboot.

The installer installs the current master, not the version the ISO was built from. To run a specific release, update to its tag afterwards (see below).

Install on an existing NixOS

On a machine that already runs NixOS (with /etc/nixos/hardware-configuration.nix), install from a clone. Don't do this on your everyday computer: it replaces the whole system configuration.

nix-shell -p git
git clone https://github.com/qitechgmbh/control.git
cd control
git checkout <tag>        # optional: the version to install
./nixos-install.sh

nixos-install.sh records the git version, runs sudo nixos-rebuild boot --flake .#nixos --impure and reboots into the new system.

First boot

What	Details
Login	The qitech user logs in automatically. It may use sudo without a password.
UI	The QiTech Control app starts automatically and runs full screen. The dock holds the app and GNOME Settings.
Backend	qitech-control-server starts at boot and restarts 10 s after it exits. State (for example Modbus assignments) lives in /var/lib/qitech.
Panel behaviour	On-screen keyboard on; no screen lock, blanking or suspend.
Remote access	Caddy serves the backend over HTTPS on port 443, see Networking and remote access.

Next step: assign the machine's terminals (Identification).

Update

Updates run from the UI and need internet access.

1. Open Setup → Update. Current Version shows what is installed.
2. Update source is qitechgmbh/control by default. For a private fork, change the source and add a GitHub token (typed in, or loaded from a .txt file on a USB drive).
3. Under Choose a Version, pick one of the latest tags, Show … more versions, a branch (searchable) or a master commit. Versions older than the installed one are marked.
4. Read the changelog and start the update.

What happens then (update-listeners.ts):

1. The app clones the chosen version into ~/control (/home/qitech/control), or fetches it into the existing clone.
2. It runs ./nixos-install.sh there, which builds the complete system (backend, app and OS) with nixos-rebuild boot. The panel compiles everything itself, so this takes a while.
3. If the build succeeds, the new version becomes the boot default and the panel reboots. If it fails, the log shows the error and the installed system stays as it was.

Each stable release has a git tag. Prefer tags over branches on production machines.

Roll back

Every update adds a NixOS generation next to the old ones, so older versions stay bootable.

• In the UI: Setup → Update → Installed Versions lists the generations. Select makes one the boot default and reboots. Delete removes one; the button below the list deletes all old generations (after that there is nothing to roll back to).

• At boot: the boot menu lists all generations, labelled <tag or branch>_<commit>. Pick an older one with the arrow keys. This boots it once without changing the default.

• In a terminal:

  sudo nixos-rebuild boot --rollback && sudo reboot

Check the installed version

The system sets QITECH_OS_* environment variables at build time (the full list is on the NixOS page):

env | grep QITECH_OS