nixos/docs/nix-cache.md

nix-cache architecture

This repository configures nix-cache as a binary cache server and a remote builder for other hosts.

Important design notes

• This is not a shared /nix/store setup.
• Every machine still keeps and uses its own local /nix/store.
• Clients prefer http://nix-cache for substitutes and keep https://cache.nixos.org/ as fallback.
• Clients can offload builds to nix-cache through SSH (nix.distributedBuilds).
• Client hosts import modules/nix/cache-client.nix and, when remote building is enabled, modules/nix/remote-builder-client.nix.
• The nix-cache host imports modules/nix/cache-server.nix.

Binary cache signing keys (on nix-cache)

sudo install -d -m 0700 /etc/nix
sudo nix-store --generate-binary-cache-key nix-cache-1   /etc/nix/cache-priv.pem   /etc/nix/cache-pub.pem
sudo chmod 0600 /etc/nix/cache-priv.pem
sudo chmod 0644 /etc/nix/cache-pub.pem
cat /etc/nix/cache-pub.pem

Do not commit private keys. Do not commit new password hashes or live credentials. Existing committed hashes should be rotated and moved to host-local secret management.

Remote builder SSH keys

On each client, install the private key used to authenticate as nixremote:

sudo install -d -m 0700 /root/.ssh
sudo install -m 0600 ./nixremote /root/.ssh/nixremote
sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version

On nix-cache, install the matching public key used by nixremote authorized keys.

The committed nixremote authorized keys are public SSH keys only. Keep the matching private keys on client hosts and out of the repository.

Manual verification

After deployment:

curl http://nix-cache/nix-cache-info
nix store ping --store http://nix-cache
nix show-config | grep -E 'substituters|trusted-public-keys|builders-use-substitutes'
sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version
nix build nixpkgs#hello --builders 'ssh://nixremote@nix-cache x86_64-linux /root/.ssh/nixremote 4 2 big-parallel,kvm,nixos-test,benchmark' -L
nix path-info -r nixpkgs#hello
curl -I "http://nix-cache/$(basename "$(nix path-info nixpkgs#hello)").narinfo"