Getting Started

Every machine we run is described by a single host configuration — its disks, users, roles and secrets. Bringing up a new one takes two steps: we add its configuration, then run just install.

Installing a machine

To fully automate disk partitioning and the installation of NixOS, we use nixos-anywhere. It installs a configured host onto a target machine over SSH, carrying the new host’s SSH key and each owner’s disk passphrase along.

On the target machine

Start by booting the target from a Minimal ISO image (e.g. on a Ventoy-based USB stick), then, on the target, authorise your SSH key for its root account so the installer can log in — your public keys on GitHub (or GitLab) are a convenient source:

curl -fsSL https://github.com/<your-user>.keys | sudo tee /root/.ssh/authorized_keys

While on the target, note the IP address you will reach it at:

$ ip -4 -br addr
lo               UNKNOWN        127.0.0.1/8
enp1s0           UP             192.168.1.42/24

On the installing machine

Then, from your workstation, run the installation:

just install example root@192.168.1.42

Note

Replace example with your target host name, and root@192.168.1.42 with the target’s address.

It generates an SSH key for the new host and grants it access to the shared secrets, then partitions, encrypts, and installs the system over SSH — seeding each owner’s disk passphrase so the machine can unlock its disk and decrypt its secrets at boot. The individual steps can also be run on their own when needed. See Disk encryption for how the passphrases it seeds are managed.

The install command adds a commit to your local nixos-config repository that makes the new host a reader of the shared secrets before running nixos-anywhere. Upon completion of the setup process the freshly installed machine is rebooted automatically.

After successful installation

If you keep a remote copy of your repository, push that commit as soon as the installation is complete! — Without it, the remote does not list the host as a reader, so a rebuild will fail at activation time when Sops cannot decrypt the secrets it tries to read. You won’t be locked out, not even if you configured managed passwords, but your updates will be incomplete, affecting all your managed secrets, such as WiFi connection changes.

Manual and automatic updates

To manually update an already installed host run nixos-rebuild, e.g.

nixos-rebuild switch --sudo --flake gitlab:<example>/nixos-config

Auto-upgrade can run this command automatically once a day when the repository configures an upgrade source. When it is configured, you can check the last run and the next scheduled time with:

systemctl status nixos-upgrade.service

systemctl status nixos-upgrade.timer

Development

See CONTRIBUTING for instructions on development and testing.