Colmena: building, transferring, and activating multiple nodes

Why Use Remote Deployment?#

When you have multiple NixOS nodes, such as a primary computer, a server, and a Raspberry Pi, running nixos-rebuild switch on each is cumbersome and makes version drift more likely. Colmena lets you push configuration to all nodes centrally from your primary computer.

Stage One: Configure Colmena#

The following is a traditional hive.nix example using the locally selected Nixpkgs; production projects should pin a Nixpkgs revision. When using a Flake, export colmena / colmenaHive as required by your Colmena version. Do not put an unbound inputs variable directly into a standalone file.

{
  meta = {
    nixpkgs = import <nixpkgs> {
      system = "x86_64-linux";
    };
  };

  server = { name, nodes, ... }: {
    deployment.targetHost = "server.example.com";
    deployment.targetUser = "root";

    imports = [ ./hosts/server/configuration.nix ];
    # 由节点硬件配置决定引导器和磁盘，不套用 /dev/sda
  };
}

Stage Two: Deployment Commands#

1. Check the configuration: colmena build
2. Preview changes: colmena apply dry-activate --on server
3. Push and activate: colmena apply switch --on server (omitting the node filter may deploy to multiple nodes)

Benefits of Remote Deployment#

1. Build locally, install remotely: after building, you can copy the system closure. Building an ARM system on x86_64 requires proper cross-compilation, emulation, or a remote builder; simply copying binaries is not enough. You can also use deployment.buildOnTarget to build on the target node.
2. Parallel deployment: upgrade 10 servers at once to exactly the same version.
3. Fault tolerance: older NixOS generations provide a recovery path, but Colmena does not guarantee automatic network recovery or rollback after every failure. Prepare SSH connectivity checks, a console channel, and manual recovery procedures before deployment.

Advice for Arch Users#

If you previously used Ansible to manage multiple Arch machines, think of Colmena as a tool that coordinates building, copying, and activation on top of NixOS's declarative system configuration. Mutable application state still needs separate management.

Summary#

• Hive: a collection of configurations.
• Apply: deploy and activate.
• Build: build without installing.

Boundaries Between Building, Previewing, and Activation

build normally only builds; with buildOnTarget enabled, the result resides on the target machine. dry-activate may first build, transfer the closure, and run the target's preview script, so it is not a purely local, read-only check. test activates immediately without making the configuration the boot default; boot changes the boot default without activating immediately; switch does both. The example hostnames are placeholders. Deploy only after confirming the target, authorized account, and hardware configuration.