Heptapod Runner setup on Linux

This tutorial will guide you through the steps to setup Heptapod Runner on a Linux server, ready to perform with the Docker executor.

It is easy to adapt without the Docker parts if you're, e.g, interested in the Shell executor.

The examples are given as Debian commands, but readers are encouraged to translate them in the

Prerequisites

  • docker
  • systemd: we really don't need anything fancy. If you don't intend to use systemd, just adapt the service management to your needs.
  • Linux distribution not too old: Debian 10 is still largely ok

System user

We choose to run unprivileged, hence we need a heptapod-runner system user and allow it to control the Docker daemon by putting it in the docker group.

Debian example:

adduser --system heptapod-runner --group --home /srv/heptapod-runner
adduser heptapod-runner docker

Note: given that this is Docker, this means that the heptapod-runner user can easily gain root access. The dedicated user is therefore more about general safety (mitigating consequences of bugs) rather than security (resisting deliberate attacks from this system user).

Install runner

We download the latest version of the runner:

curl -L -O https://download.heptapod.net/runner/latest/binaries/heptapod-runner-linux-amd64

You may want to also download its signature and verify it (see our general signature checking instructions). For example:

curl -L -O https://download.heptapod.net/runner/latest/binaries/heptapod-runner-linux-amd64.asc
gpg --verify heptapod-runner-linux-amd64.asc

Install it to a directory on $PATH:

sudo install -o root heptapod-runner-linux-amd64 /usr/local/bin/heptapod-runner

Note

We create the service and the configuration file:

sudo heptapod-runner install \
    --user=heptapod-runner \
    --working-directory=/srv/heptapod-runner \
    --config=/etc/heptapod-runner/config.toml

As we choose to run unprivileged, we need to edit the heptapod-runner.service from /etc/systemd/system to add under [Service] section:

User=heptapod-runner

We need also to change the owner of /etc/heptapod-runner/config.toml with:

sudo chown -R heptapod-runner /etc/heptapod-runner

We can now start the service:

sudo heptapod-runner start

Register runner

Warning

if you are running Heptapod≥17.0, make sure that the legacy "runner registration token" are allowed (the current method is called "runner authentication token"). This is to be found in Admin Area / Settings / CI/CD / Runners.

The registration tokens for Instance, Group or Project Runners can then be found in the vertical dots menu next to the "New runner" button in the relevant page.

Now we have to register to the heptapod instance using the registration token from the CI/CD settings:

sudo -u heptapod-runner heptapod-runner register \
  --url https://foss.heptapod.net/ \
  --config /etc/heptapod-runner/config.toml \
  --registration-token <token>