nixos-example-setup

A small, complete, working NixOS fleet built on nixos-common. Copy it, rename it, fill it in.

git config core.hooksPath .githooks   # do this first
nix flake check                        # both hosts evaluate, both tests run
nix run .#vm-example-server            # boot a host in QEMU, install nothing

Why it exists

nixos-common is mechanism only — no hostname, IP, sops path or organisation name anywhere in it. That makes it reusable and it means a consumer has to supply every piece of policy. A working fleet does that, but a working fleet is large and full of real secrets, so it cannot be handed to someone as a starting point.

This is the missing starting point. It is small enough to read in one sitting and complete enough to deploy.

What is in it

Two hosts. example-server runs Homepage, Gatus, ntfy, Vaultwarden and Beszel behind Caddy. example-desktop is a workstation — KDE Plasma behind SDDM, see docs/desktop.md.

Boot either one as a VM. nix run .#vm-<host> runs the real host configuration with a thin layer over it, not a cut-down copy — so what you are looking at is what would deploy.

Tests that boot the real thing. nix flake check builds both hosts and runs integration tests over the exact module list that deploys, via mkHost's _modules.

Deploy either way. nixos-rebuild for the workstation, colmena for the servers, both from the same definitions.

You do not need a NixOS machine

Nix runs on Ubuntu, and building both hosts, booting them as VMs and running the tests all work from there. The only thing that genuinely needs NixOS is running one of these configurations as your own machine. docs/without-nixos.md has the install and the caveats.

Where to look

Start with docs/getting-started.md, or docs/without-nixos.md if you are not on NixOS yet. Everything else is indexed in docs/README.md.

Two things that will bite you first

The pre-commit gate does nothing until you switch it on. core.hooksPath is local git config and is never cloned, so a fresh clone commits ungated and the PII and secret scans silently do not run.

git config core.hooksPath .githooks
git config --get core.hooksPath      # must print .githooks

Every build warns about missing secrets, and that is correct. The repo ships none — they would be encrypted to a key only their owner holds. Hosts build and VMs boot regardless; what you do not get is SSH access to a real host. docs/secrets.md is the fifteen minutes that fixes it.

Licence

MIT-0: copy it, keep it private, use it commercially, no attribution. The nixos-common library it builds on is MPL-2.0. Why the two differ: docs/licensing.md.