nixops -- Nix for Ops: a zero-to-fleet tutorial
This is a guided course for operations engineers who have never touched
Nix, NixOS, or flakes before, but want to actually run a fleet of NixOS
machines with nixops at the end of it. It does not assume any prior
functional programming, and it does not pretend that Nix is a small
tool – but it does insist on a linear reading order so you never hit
a chapter that needs a concept you have not seen yet.
You will finish able to:
- explain what Nix, NixOS, flakes, and modules are, in your own words;
- read (and edit) the
flake.nix/hosts.nix/.sops.yamltriple that this repo scaffolds; - install a fresh Linux server from your laptop with one command
(
install-host), including its secrets; - deploy configuration changes across the whole fleet with one command
(
deploy), safely, with automatic rollback if the new config breaks; - know where in the official manuals to go next.
Who this is for
- Ops folks who already run servers with Ansible, Terraform, Kubernetes manifests, plain SSH + shell scripts, or whatever else. The comparisons in What Nix is and why it matters are aimed at you.
- First-time Nix users. No prior functional-programming or package-manager exposure is assumed. If you have used Nix before, the Foundations chapters will feel slow; skim them and start at NixOS and the module system.
What you need before installing Nix
- A workstation running Linux, macOS, or WSL2. Nix works on all three; NixOS itself only runs on Linux, but you can build and deploy NixOS configurations from any workstation Nix supports.
- Root SSH access to at least one Linux target you are willing to reinstall (a cheap VPS is fine). Remote install with nixos-anywhere and Your first fleet need this.
- Comfort with a Unix shell,
ssh, and reading YAML/JSON. You do not need to know any functional programming.
Reading order
The chapters build on each other; skipping ahead will hurt. If you only have 30 minutes, read What Nix is and why it matters, Your first fleet, and Day-two operations – you will not understand the internals, but you will be able to operate a fleet someone else set up.
Foundations
| Chapter | Purpose |
|---|---|
| What Nix is and why it matters | Mental model + comparisons to apt/Ansible/Docker |
| Install Nix and enable flakes | Get a working Nix on your workstation |
| The Nix language | Just enough to read this repo |
| Flakes | Inputs, outputs, lock file, the nix CLI |
| NixOS and the module system | Declarative machines; options and config |
Deploying
| Chapter | Purpose |
|---|---|
| Secrets with sops-nix | age keys, .sops.yaml, sops.secrets.* |
| Remote install with nixos-anywhere | Install NixOS on any Linux target |
| Deploying with deploy-rs | Activation, rollback, checks |
| Your first fleet | End-to-end walkthrough |
| Anatomy of an instance repo | Every file the wizard produces |
Operating
| Chapter | Purpose |
|---|---|
| Operating from an ephemeral workstation VM | One-command NixOS workstation with the full toolchain |
| Day-two operations | The routine ops loop |
| Writing host-specific modules | Adding services, disks, firewall holes |
| Troubleshooting | Failure modes and how to diagnose |
| Further reading | Curated links into the official docs |
Conventions
- ASCII only. No em-dashes, curly quotes, or ellipses.
--means literally two hyphens. Copy-paste-friendly. - Shell blocks are prefixed with
$when they run on your workstation and#when they run as root on a target host. Blocks without a prefix are file contents. - Links into official docs are named inline. When a chapter refers to a canonical manual (Nix Reference, NixOS Manual, Nixpkgs Manual), you will find the full URL and section number in the paragraph.
- This repo’s own code is referenced with file paths relative to
the nixops repo root, for example
modules/ssh.nixorlib/mkDevShell.nix. Open those in a second window while you read.
The one link you should bookmark now
nix.dev – the official modern documentation site, maintained by the NixOS Foundation. Every time this tutorial sends you elsewhere, it is usually there. Bookmark it before starting What Nix is and why it matters.