NixBuild State Management

Managing an nxb-server-ec2 or nxb-nard-ec2 state volume

State management works identically on nxb-server-ec2 and nxb-nard-ec2. The only difference is that on nxb-nard-ec2 the nard state directory will be set up and used, but no other directories. This means that you can attach a copy of an nxb-server-ec2 state volume to an nxb-nard-ec2 instance, if you are migrating an existing deployment to a standalone nard server.

In the documentation below, "the EC2 instance" means either nxb-server-ec2 or nxb-nard-ec2.

The EC2 instance will automatically take advantage of an attached EBS volume if it contains a filesystem labeled nixbuild. If the server is booted with such a volume, the following things will happen:

1. The filesystem labeled nixbuild is mounted on /var/__nixbuild

2. The following directory structure will be set up in /var/__nixbuild (if not there already):

   lib/postgresql
   lib/nard
   lib/nixbuild-frontend
   cache/postgresql
   cache/nard
   cache/nixbuild-frontend
   

3. The following bind mounts will be set up:

   /var/__nixbuild/lib/postgresql          -> /var/lib/postgresql
   /var/__nixbuild/lib/nard                -> /var/lib/nard
   /var/__nixbuild/lib/nixbuild-frontend   -> /var/lib/nixbuild-frontend
   /var/__nixbuild/cache/postgresql        -> /var/cache/postgresql
   /var/__nixbuild/cache/nard              -> /var/cache/nard
   /var/__nixbuild/cache/nixbuild-frontend -> /var/cache/nixbuild-frontend
   

4. The postgresql daemon is started, using /var/lib/postgresql for storage.

5. The NixBuild services are started, including nard which will use /var/lib/nard for storage.

If no filesystem labeled nixbuild is found on startup, the steps 1-3 above are skipped, and the boot volume will be used for state instead, as long as the nixbuild.require-state-volume configuration options is not set to true. If require-state-volume is true, the above steps will be retried until a filesystem labeled nixbuild appears.

Manual preparation of a state volume

Skip to the next section for information on how to automatically prepare the state volume. If you want to do manual preparation, read on.

To prepare an initial state volume, you can simply boot the EC2 instance with an empty EBS volume attached to it and then create a filesystem like this:

$ mkfs.ext4 -L nixbuild /dev/nvme1n1

Please note that the device name may differ on your EC2 instance. If nixbuild.require-state-volume is true, the new filesystem will be mounted and used automatically. Otherwise, reboot the server or run this:

$ systemctl restart nixbuild-pre.target

Note that if you had run any builds before attaching the state volume, they will not be available anymore, instead they will be hidden by the bind mounts described above.

If you set the NixBuild setting nixbuild.require-state-volume to true, a state volume as described above is required. That is, the NixBuild services will refuse to start until a filesystem labeled nixbuild has been made available. Once such a filesystem appears on the server, the NixBuild services will start automatically.

Automatic preparation of a state volume

If you know the device name of the state volume, you can set it up in your configuration. Doing so will enable automatic creation of the nixbuild filesystem. For this to happen, require-state-volume must also be true. The following configuration snippet enables fully automatic state volume creation and activation:

nixbuild {
  require-state-volume = true
  state-volume-device = "/dev/nvme1n1"
}

You have to make sure the EC2 instance is provisioned with a volume that appears as the device you have configured.