Nix: From Zero to Hero — Ein praxisnaher Weg zu reproduzierbaren Systemen

The Nix Adoption Ladder: Six Levels of Reproducible Infrastructure

Nix is not all-or-nothing. From a pinned devShell to immutable A/B-OTA appliances — six levels of adopting the Nix spirit, with real experience from K3s clusters, air-gapped registries, and Nix-built mail server containers.

Warum es dieses Tutorial gibt

Nix hat den Ruf, schwierig zu sein. Dieser Ruf rührt von einem falschen Ausgangspunkt her: Die meisten Tutorials beginnen mit der Nix-Expressionssprache oder mit NixOS, während die nützliche Reise eigentlich mit einem einzigen Befehl in einer Shell beginnt und das Betriebssystem erst erreicht, nachdem man die Vorteile der Reproduzierbarkeit dreimal selbst erlebt hat.

Dies ist der praxisorientierte Begleiter zur Nix Adoption Ladder — während jener Artikel die Ebenen der Adaption des Nix-Geistes erklärt, ist dies der konkrete Pfad: Installation, Shells, Flakes, Packaging, Container, NixOS und die Produktionsmuster, die eine gesamte Flotte reproduzierbar machen. Jedes Beispiel stammt aus Mustern, die in echten Deployments laufen: eine in einem Flake fixierte Admin-Toolchain, Container-Images für einen Mail-Stack und ein Air-Gapped-Cluster, der Daten aus einem selbst gehosteten Cache bezieht.

Teil 1 — Null: Installation und der erste Befehl

1.1 Installation

Der Standard-Multi-User-Installer ist der richtige Standard für Linux und macOS:

sh <(curl -L https://nixos.org/nix/install) --daemon

Der Installer von Determinate Systems (nix-installer) ist die ergonomische Alternative: idempotent, bessere Deinstallation, funktioniert auf mehr Plattformen. In einem Container bietet docker run -it nixos/nix in Sekundenschnelle einen ephemeren Spielplatz — perfekt, um dieses Tutorial zu begleiten.

1.2 Die erste Superkraft: nix-shell -p

nix-shell -p versetzt Sie in eine temporäre Shell mit hinzugefügten Paketen — ohne dass systemweit etwas installiert wird:

nix-shell -p git jq          # shell with git and jq on PATH
nix-shell -p git --run "git --version"   # run one command, exit
nix-shell -p git --pure      # isolated: no inherited PATH

Halten Sie kurz inne und realisieren Sie, was gerade passiert ist: zwei Tools, fixiert auf eine spezifische nixpkgs-Revision, sofort verfügbar und weg, sobald Sie die Shell verlassen. Kein apt install, kein „welche Version ist auf diesem Rechner installiert?“, keine Systemverschmutzung. Dieser eine Befehl ist das gesamte Nix-Konzept im Miniaturformat.

Teil 2 — Deklarative Shells

Ad-hoc -p ist für die Exploration gedacht. Sobald ein Projekt eine reproduzierbare Toolchain benötigt, halten Sie diese schriftlich fest:

# shell.nix
{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShellNoCC {
  packages = [ pkgs.git pkgs.jq ];
  GREETING = "Hello";
  shellHook = ''
    echo "$GREETING — $(git --version)"
  '';
}

nix-shell                # enter the environment

Für echte Projekte sollten Sie nixpkgs fixieren, damit „reproduzierbar“ Byte für Byte bedeutet und nicht „was auch immer mein Channel heute enthält“:

{ pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/<sha256>.tar.gz") {} }:
pkgs.mkShell { packages = [ pkgs.kubectl pkgs.kubernetes-helm ]; }

Kombinieren Sie dies mit direnv, und die Umgebung lädt sich selbst, sobald Sie cd in das Projekt wechseln — die Toolchain ist nun eine Eigenschaft des Verzeichnisses, nicht der Person.

Teil 3 — Flakes: Die moderne Schnittstelle

Flakes sind der aktuelle Standard: Eine flake.nix im Root des Repos deklariert Inputs (Abhängigkeiten, fixiert per Content-Hash in flake.lock) und Outputs (devShells, Pakete, Checks, NixOS-Konfigurationen). Eine Datei, eine Lockfile, ein Befehl für alles.

# flake.nix
{
  description = "My project";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = [ pkgs.git pkgs.jq ];
        };

        packages.default = pkgs.hello;   # nix build
        checks.default = pkgs.hello;     # nix flake check
        formatter = pkgs.nixfmt;         # nix fmt
      });
}

Der Workflow:

nix develop        # enter the devShell (replaces nix-shell)
nix build          # build packages.default → result/
nix run            # run it
nix flake check    # evaluate AND build every check
nix flake update   # bump inputs, rewrite flake.lock

Flake-Best-Practices, die Ihnen echte Debugging-Zeit ersparen werden:

Teil 4 — Packaging: stdenv.mkDerivation

Beim Packaging hört Nix auf, ein Tool-Manager zu sein, und wird zu einem Build-System. Der Kern ist stdenv.mkDerivation — eine Funktion, die Quellcode + Build-Schritte in einen Store-Pfad verwandelt, dessen Hash jeden Input abdeckt:

{ stdenv, fetchFromGitHub, cmake }:

stdenv.mkDerivation {
  pname = "myapp";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "me";
    repo = "myapp";
    rev = "v1.0.0";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  nativeBuildInputs = [ cmake ];   # build-time tools
  buildInputs = [ ];               # runtime libraries

  installPhase = ''
    mkdir -p $out/bin
    install -m755 myapp $out/bin/
  '';
}

Zwei Eigenschaften machen dies fundamental anders als ein Makefile:

• Der Store-Pfad ist durch alles Inhaltsadressiert: Ändern Sie den Source-Hash, einen Build-Input oder sogar die nixpkgs-Revision, und der Output-Pfad ändert sich. Zwei Builds mit denselben Inputs erzeugen denselben Pfad — und dieselben Bytes.
• Kein versteckter Zustand: kein ~/.cache, keine System-Libraries, kein „auf meinem Rechner hat es funktioniert“. Alles, was der Build sehen kann, ist deklariert.

Einmal verpackt, lässt sich dieselbe Derivation überall zusammensetzen: als devShell-Paket, innerhalb eines Container-Images, auf einer NixOS-Maschine oder als Remote-Build via nix.buildMachines.

Teil 5 — Container aus Nix: dockerTools

Wenn Ihr Deployment Container nutzt, ersetzt Nix Ihre Dockerfiles:

# buildLayeredImage — each package becomes its own layer
dockerTools.buildLayeredImage {
  name = "myapp";
  tag = "latest";
  contents = [ pkgs.bash pkgs.coreutils myapp ];
  config = {
    Cmd = [ "${myapp}/bin/myapp" ];
    Env = [ "SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt" ];
    ExposedPorts = { "8080/tcp" = {}; };
  };
  created = "now";   # or a fixed timestamp for full reproducibility
}

nix build .#container
docker load < result

Was Sie anstelle eines Dockerfiles erhalten:

• Reproduzierbare Images — dieselbe Flake-Revision erzeugt immer dasselbe Image, Layer für Layer.
• Layer, die Sinn ergeben — ein Layer pro Paket, sodass eine Änderung an Ihrer App nicht die nixpkgs-Layer invalidiert (via buildLayeredImage).
• Patches als Expressions — ein Groupware-Frontend, das Accessibility-Fixes benötigt, wird als Patch ausgeliefert, der während des Builds angewendet wird; die exakten Änderungen befinden sich in der Versionsverwaltung, nicht in einer sed-Kette eines Dockerfiles.
• Multi-Arch aus einer Expression — genAttrs über ["x86_64-linux" "aarch64-linux"] leitet beide Images ab; extendModules leitet Umgebungsvarianten aus einer Basis ab. Keine pro-Architektur-Dockerfiles, die auseinanderdriften.
• Das Image ist gleichzeitig ein Check — listen Sie die Derivation unter checks, und nix flake check baut sie in der CI, bevor irgendetwas eine Registry erreicht.

In einem Air-Gapped-Cluster rentiert sich dies sofort: Images werden einmal gebaut, in eine lokale Registry geladen, und die Nodes benötigen überhaupt kein Docker Hub. nix build → docker load → docker tag → push ist die gesamte Publish-Pipeline.

Teil 6 — NixOS: Das Betriebssystem als Code

NixOS ist dasselbe Modell, angewandt auf die gesamte Maschine: /etc wird aus einer deklarativen Konfiguration generiert, jede Änderung ist eine neue Generation, und ein Rollback ist ein Eintrag im Boot-Menü.

# configuration.nix (or a flake's nixosConfigurations)
{ config, pkgs, ... }: {
  boot.loader.systemd-boot.enable = true;

  networking.hostName = "web-01";

  services.nginx = {
    enable = true;
    virtualHosts."example.com" = {
      root = "/var/www";
      forceSSL = true;
      enableACME = true;
    };
  };

  users.users.admin = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };

  system.stateVersion = "24.11";
}

nixos-rebuild switch        # apply and activate
nixos-rebuild boot          # activate on next boot
nixos-rebuild switch --rollback   # back to the previous generation

Den operativen Unterschied kann man kaum überbewerten: „Gestern hat es noch funktioniert“ wird zur Auswahl im Boot-Menü, nicht zur Wiederherstellung aus einem Backup. Jedes nixos-rebuild switch erstellt eine neue Generation; der Bootloader behält die letzten N. Ein missglücktes Upgrade kostet einen Neustart.

Für Flotten deployt Colmena (oder comin für den GitOps-Ansatz) viele Maschinen aus einem Flake:

# hive.nix
{
  meta = { nixpkgs = import nixpkgs { system = "x86_64-linux"; }; };

  defaults = { pkgs, ... }: {
environment.systemPackages = [ pkgs.vim pkgs.wget ];
  };

  node-a = { name, ... }: {
    networking.hostName = name;
    deployment.targetHost = "node-a.example.com";
    deployment.buildOnTarget = false;   # lokal bauen, Closure kopieren
  };
}

colmena apply            # alle Knoten, parallel
colmena apply --on node-b   # Subset basierend auf Tags

Part 7 — Hero: Production Patterns

7.1 Binary caches — make the fleet fast

Every node building nixpkgs from source is a waste of the universe. A self-hosted cache serves pre-built store paths; post-build-hook uploads every new path automatically.

For the air-gapped reference cluster, Attic is the recommendation: its S3 backend can sit on the existing Ceph cluster (RGW), global dedup saves scarce bandwidth, and server-side signing means builders never hold the signing key. One services.atticd module on a cache node turns cluster rebuilds from a day into minutes.

7.2 Secrets — never in the store

The Nix store is world-readable. Secrets therefore never enter it:

• agenix — age-encrypted .age files committed to git, decrypted at activation. The simplicity winner.
• sops-nix — sops-encrypted files, GPG or age keys, atomic directory swaps.
• systemd LoadCredential= — the runtime complement: the unit receives the secret as a file under /run/credentials, no Nix involvement at all.

# agenix
age.secrets.database-password = {
  file = ./secrets/database-password.age;
  owner = "mariadb";
  mode = "0400";
};

7.3 Declarative disks — disko

disko declares partitions, filesystems, and LUKS in the same flake as the OS; nixos-anywhere installs a remote machine from it over SSH:

disko.devices.disk.main = {
  device = "/dev/sda";
  type = "disk";
  content = {
    type = "gpt";
    partitions = {
      ESP = { size = "500M"; type = "EF00"; content = { type = "filesystem"; format = "vfat"; mountpoint = "/boot"; }; };
      root = { size = "100%"; content = { type = "filesystem"; format = "ext4"; mountpoint = "/"; }; };
    };
  };
};

nixos-anywhere --flake .#node-a root@node-a   # Provisionierung, von Null auf NixOS

7.4 Impermanence — the machine forgets

impermanence wipes the root filesystem on every boot; only explicitly declared state survives:

fileSystems."/" = { device = "none"; fsType = "tmpfs"; options = [ "defaults" "size=25%" "mode=755" ]; };
fileSystems."/persistent" = { device = "/dev/vg/root"; neededForBoot = true; fsType = "btrfs"; options = [ "subvol=persistent" ]; };

A compromised or corrupted machine returns to its declared state by rebooting. Combined with lanzaboote (UEFI Secure Boot) and A/B OTA updates, the machine stops being a machine and becomes an appliance.

7.5 Tests before deployment — testers.runNixOSTest

The ultimate reproducibility payoff: integration tests boot the exact configuration you will deploy, in QEMU VMs, and assert service-to-service behavior:

checks.integration = pkgs.testers.runNixOSTest {
  nodes.machine = { ... };          # die zu testende NixOS-Konfiguration
  testScript = ''
    machine.wait_for_unit("nginx.service")
    machine.wait_for_open_port(80)
    machine.succeed("curl -f http://localhost/")
  '';
};

nix flake check führt dann aus: eval checks, Image-Builds und vollständige VM-Integrationstests — derselbe Ausdrucksbaum, den die CI testet, ist der Baum, der ausgeliefert wird.

Die Hero-Checkliste

1. devShells in jedem Repo — gepinnte Toolchain, committete flake.lock.
2. treefmt + nixfmt + statix + deadnix als formatter-Output — Formatierung ist ein Build-Schritt, kein Diskussionspunkt.
3. checks in jedem Flake — CI-Gates via nix flake check.
4. dockerTools-Images mit Patches als Ausdrücke, Multi-Arch via genAttrs.
5. Self-hosted Binary Cache (Attic auf dem bestehenden Storage) mit signierten Pfaden und post-build-hook.
6. agenix oder sops-nix für Secrets; LoadCredential= für Runtime-Secrets.
7. disko + nixos-anywhere für die Provisionierung; Colmena für Flotten.
8. Impermanence oder A/B OTA auf Knoten, die Sie nicht mit einer Tastatur erreichen können.
9. runNixOSTest für alles, was in der Produktion nicht kaputtgehen darf.

Starten Sie heute mit nix-shell -p git jq, committen Sie morgen Ihr erstes shell.nix, und lassen Sie die Store-Pfade ab dann die Diskussion über Reproduzierbarkeit führen.

Verwandte Artikel

• The Nix Adoption Ladder: Six Levels of Reproducible Infrastructure — wann welches Level eingeführt werden sollte und wo reale Deployments stehen
• SOGo + Stalwart + OpenLDAP: Dockerized Groupware Deployment — ein Mail-Stack, dessen Container-Images mit Nix gebaut wurden
• CephFS: From Zero to Hero — der RWX-Storage hinter dem gemeinsamen Nix-Builder
• GitOps Secrets Management in Production — wie Secret-Patterns mit agenix/sops-nix harmonieren
• SeaweedFS: Deep Dive! — der Object Store, der die restic-Backups dieses Stacks hält, gespiegelt außerhalb des Clusters