Nix: From Zero to Hero — A Hands-On Path to Reproducible Everything

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.

Why This Tutorial Exists

Nix has a reputation for being hard. That reputation comes from the wrong starting point: most tutorials begin with the Nix expression language or with NixOS, when the useful journey starts with a single command in a shell and only reaches the operating system after you have felt the reproducibility benefits three times.

This is the hands-on companion to the Nix Adoption Ladder — where that article explains levels of adopting the Nix spirit, this one is the concrete path: install, shells, flakes, packaging, containers, NixOS, and the production patterns that make a fleet reproducible. Every example is taken from patterns that run in real deployments: an admin toolchain pinned in a flake, container images for a mail stack, and an air-gapped cluster pulling from a self-hosted cache.

Part 1 — Zero: Install and the First Command

1.1 Install

The standard multi-user installer is the right default on Linux and macOS:

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

The Determinate Systems installer (nix-installer) is the ergonomic alternative: idempotent, better uninstall, works on more platforms. In a container, docker run -it nixos/nix gives you an ephemeral playground in seconds — perfect for following along.

1.2 The first superpower: nix-shell -p

nix-shell -p drops you into a temporary shell with packages added — without installing anything system-wide:

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

Stop and appreciate what just happened: two tools, pinned to a specific nixpkgs revision, available instantly, and gone when you exit. No apt install, no "which version does this box have?", no system pollution. This single command is the whole Nix pitch in miniature.

Part 2 — Declarative Shells

Ad-hoc -p is for exploration. The moment a project needs a reproducible toolchain, write it down:

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

nix-shell                # enter the environment

For real projects, pin nixpkgs so "reproducible" means byte-for-byte, not "whatever my channel has today":

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

Pair it with direnv and the environment loads itself the moment you cd into the project — the toolchain is now a property of the directory, not of the person.

Part 3 — Flakes: The Modern Interface

Flakes are the current standard: a flake.nix at the repo root declares inputs (dependencies, pinned by content hash in flake.lock) and outputs (devShells, packages, checks, NixOS configurations). One file, one lockfile, one command for everything.

# 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
      });
}

The 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 that will save you real debugging time:

Part 4 — Packaging: stdenv.mkDerivation

Packaging is where Nix stops being a tool manager and becomes a build system. The core is stdenv.mkDerivation — a function that turns source + build steps into a store path whose hash covers every input:

{ 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/
  '';
}

Two properties make this fundamentally different from a Makefile:

• The store path is content-addressed by everything: change the source hash, a build input, or even the nixpkgs revision, and the output path changes. Two builds with the same inputs produce the same path — and the same bytes.
• No hidden state: no ~/.cache, no system libraries, no "it worked on my machine". Everything the build can see is declared.

Once packaged, the same derivation composes everywhere: as a devShell package, inside a container image, on a NixOS machine, or as a remote build via nix.buildMachines.

Part 5 — Containers from Nix: dockerTools

If your deployment runs containers, Nix replaces your 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

What you get instead of a Dockerfile:

• Reproducible images — the same flake revision always produces the same image, layer-for-layer.
• Layers that make sense — one layer per package, so a change to your app doesn't invalidate the nixpkgs layers (via buildLayeredImage).
• Patches as expressions — a groupware frontend that needs accessibility fixes ships as a patch applied during the build; the exact changes are in version control, not in a Dockerfile's sed chain.
• Multi-arch from one expression — genAttrs over ["x86_64-linux" "aarch64-linux"] derives both images; extendModules derives environment variants from one base. No per-arch Dockerfiles drifting apart.
• The image is also a check — list the derivation under checks and nix flake check builds it in CI before anything reaches a registry.

In an air-gapped cluster this pays for itself immediately: images are built once, loaded into a local registry, and the nodes never need Docker Hub at all. nix build → docker load → docker tag → push is the whole publish pipeline.

Part 6 — NixOS: The Operating System as Code

NixOS is the same model applied to the whole machine: /etc is generated from a declarative configuration, every change is a new generation, and rollback is a boot-menu entry.

# 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

The operational difference is hard to overstate: "it worked yesterday" becomes a boot menu selection, not a restore from backup. Every nixos-rebuild switch creates a new generation; the bootloader keeps the last N. A botched upgrade costs one reboot.

For fleets, Colmena (or comin for the GitOps flavor) deploys many machines from one 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;   # build locally, copy the closure
  };
}

colmena apply            # all nodes, in parallel
colmena apply --on node-b   # tag-based subset

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   # provisioned, from zero to 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 = { ... };          # the NixOS config under test
  testScript = ''
    machine.wait_for_unit("nginx.service")
    machine.wait_for_open_port(80)
    machine.succeed("curl -f http://localhost/")
  '';
};

nix flake check then runs: eval checks, image builds, and full VM integration tests — the same expression tree that CI tests is the tree that ships.

The Hero Checklist

1. devShells in every repo — pinned toolchain, committed flake.lock.
2. treefmt + nixfmt + statix + deadnix as the formatter output — formatting is a build step, not an argument.
3. checks in every flake — CI gates via nix flake check.
4. dockerTools images with patches as expressions, multi-arch via genAttrs.
5. Self-hosted binary cache (Attic on the existing storage) with signed paths and post-build-hook.
6. agenix or sops-nix for secrets; LoadCredential= for runtime secrets.
7. disko + nixos-anywhere for provisioning; Colmena for fleets.
8. Impermanence or A/B OTA on nodes you cannot reach with a keyboard.
9. runNixOSTest for anything that must not break in production.

Start today with nix-shell -p git jq, commit your first shell.nix tomorrow, and let the store paths do the arguing about reproducibility from then on.

Related Articles

• The Nix Adoption Ladder: Six Levels of Reproducible Infrastructure — when to adopt which level, and where real deployments sit
• SOGo + Stalwart + OpenLDAP: Dockerized Groupware Deployment — a mail stack whose container images are Nix-built
• CephFS: From Zero to Hero — the RWX storage behind the shared Nix builder
• GitOps Secrets Management in Production — how secrets patterns pair with agenix/sops-nix
• SeaweedFS: Deep Dive! — the object store that holds this stack's restic backups, mirrored off-cluster