Deploy with NixOS

1. Bootstrap

Add this configuration to /etc/nixos/configuration.nix:

  services.hercules-ci-agent.enable = true;

2. Get a cluster join token.

In the dashboard, find the account for which you would like to deploy the agent,
Select your deployment method, select the Generate a token tab and use the button.
Copy the token into a plain text file /var/lib/hercules-ci-agent/secrets/cluster-join-token.key.

Although a single agent works with empty {} binary cache configuration, we highly recommend setting up a cache from the start. Running without a cache will break some features and will cause unexpectedly long build times due to eventual garbage collection.

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	Omit if you use a local signing key. Required if you use a Write token. You can retrieve one from cachix, click a cache, click per cache auth token. Select Write permission and generate a key. If you can only select Read permission, you have to ask a cache admin for a Write token or, if applicable, for the signing key.
3	The public part of the signing key. Look for "Public Key" on your cache page (example page: `https://mycache.cachix.org`).
4	Omit if you use a Write token. Otherwise, this is the 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.

Copy or move the binary-caches.json file into /var/lib/hercules-ci-agent/secrets/.

Make sure that /var/lib/hercules-ci-agent/secrets and its contents can only be read by hercules-ci-agent.

4. Activation

Active your configuration with

[root@my-agent-host]# nixos-rebuild switch

This creates the hercules-ci-agent user. If you haven’t set the file permissions yet:

[root@my-agent-host]# chown -R hercules-ci-agent /var/lib/hercules-ci-agent
[root@my-agent-host]# chmod o-rwx /var/lib/hercules-ci-agent/secrets

The log should indicate Agent online.

[root@my-agent-host]# journalctl -u hercules-ci-agent.service
[...]
Nov 06 22:35:36 my-agent-host hercules-ci-agent[1305]: [2019-11-06 22:35:36][][Info][agent-machine-1][PID 1305][ThreadId 22][agent-version:0.6.1][main:Hercules.Agent hercules-ci-agent/Hercules/Agent.hs:73:8] Agent online.

If you are deploying to a remote machine, you might want to script the deployment.

5. Repository Setup

The goal of this step is to make sure everything is set up correctly.

If you are familiar with Nix, set up your own git repository
Otherwise verify your agent setup with a minimal git repository

Troubleshooting

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