Deploy manually with a configuration file

If the other deployment methods do not suit your needs, you may choose to run or deploy the agent manually.

Send us an e-mail at [email protected]. We can give you advice and we are interested in expanding our officially supported deployment methods.

1. Configure the agent

Write an agent.toml file. Most of the entries are optional. A small example:

baseDirectory = "/var/lib/hercules-ci-agent"
concurrentTasks = 4

This guide will assume that the baseDirectory remains set to /var/lib/hercules-ci-agent.

2. 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.

3. Configure binary caches

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.

Install the file in /var/lib/hercules-ci-agent/secrets/binary-caches.json.

Configure the system to use the caches and accept their public keys. When using a private cache, you will also need to install an appropriate netrc file in /etc/nix/daemon-netrc.

5. Start the agent

Run hercules-agent --config agent.toml, preferably via some process supervision system.