Deploy with NixOps

1. Bootstrap

Create a folder called mycompany-agents with a file:

network.nix
let
  hercules-ci-agent =
      builtins.fetchTarball "https://github.com/hercules-ci/hercules-ci-agent/archive/stable.tar.gz";
in
{
  network.description = "Hercules CI agents";

  agent = {
    imports = [
      (hercules-ci-agent + "/module.nix")
    ];

    services.hercules-ci-agent.enable = true;
    services.hercules-ci-agent.concurrentTasks = 4; # Number of jobs to run
    services.hercules-ci-agent.binaryCachesFile = ./binary-caches.json;
    deployment.keys."cluster-join-token.key".keyFile = ./cluster-join-token.key;
  };
}

2. Pick provisioning target

Choose between backends. NixOps can deploy to:

An example physical specification:

hercules-ci-agents-target.nix
{
  agent = {
    deployment.targetHost = "10.0.0.42"; # Your agent's IP address running NixOS
  };
}

3. Get a cluster join token.

  1. In the dashboard, find the account for which you would like to deploy the agent,

  2. Click the "Agents" button and the button in "Generate token" tab. This produces a private token that should be protected like a password.

  3. Copy the token into a plain text file /var/lib/hercules-ci-agent/secrets/cluster-join-token.key.

4. Configure a binary cache

Write a file binary-caches.json in the same directory as hercules-ci-agents.nix.

If you’re using more than one agent or would like to share resulting binaries outside the build farm you’ll need a binary cache.

On Cachix you can create a binary cache. After you complete the process, gather the keys into a binary-caches.json file, replacing all placeholders:

binary-caches.json
{ "mycache": (1)
    { "kind": "CachixCache"
    , "authToken": "eyJhaf23GH53a.bc23BUSI.9q3048hWHh" (2)
    , "publicKeys": ["mycache.cachix.org-1:EjBSHzF6VmDnzqlldGXbi0RM3HdjfTU3yDRi9Pd0jTY="] (3)
    , "signingKeys": ["uAhqM3jG..."] (4)
    }
}
1 The name of the Cachix cache; for example the mycache part from mycache.cachix.org.
2 Optional; only required for private binary caches. You may retrieve this from the Cachix Getting started instructions, step 3.
3 The public part of the signing key. Look for "Public Key" on your cache page (example page: https://mycache.cachix.org).
4 A cache-specific secret key to sign store paths. You can find it in ~/.config/cachix/cachix.dhall or your key backup after following the setup instructions on cachix.org. Make sure you copy the right key if you have multiple in your cachix.dhall.
For more detail, see The binary-caches.json format in the Reference.

5. Deploy

To avoid compiling the agent you can use binary cache to speed it up:

$ nix-env -iA cachix -f https://cachix.org/api/v1/install
$ cachix use hercules-ci

Deploy using:

$ nix-shell -p nixops -I nixpkgs=http://nixos.org/channels/nixos-19.03/nixexprs.tar.xz
$ nixops create -d my-agent ./hercules-ci-agents.nix ./hercules-ci-agents-target.nix
$ nixops deploy -d my-agent

The agent will start working as soon as the deployment has succeeded and builds are queued.

Troubleshooting

To inspect the agent’s local log, run nixops ssh agent journalctl -u hercules-ci-agent -n 100 to see the last 100 lines.