Docker Provider

Self-hosted Docker Runner Pools enable you to dynamically provision Runners to run pipelines on any Docker Engine, including hosts running Windows or Linux. The Runner Pool is packaged as an executable that is deployed in a container. The Runner Pool orchestrates the provisioning and deprovisioning of runner containers on the same Docker Engine.

Docker Provider Configuration

Below are the configuration options specific to the Docker Provider with the default values shown.

{
    "RUNNER_LOCAL_DOCKER_IMAGE_REGISTRY": "docker.io",
    "RUNNER_LOCAL_DOCKER_IMAGE_REPOSITORY": "refactr/runner",
    "RUNNER_LOCAL_DOCKER_IMAGE_TAG": "latest"
}

• RUNNER_LOCAL_DOCKER_IMAGE_REGISTRY: The name of the image registry hosting the runner images.
• RUNNER_LOCAL_DOCKER_IMAGE_REPOSITORY: The name of the image repository hosting the runner images.
• RUNNER_LOCAL_DOCKER_IMAGE_TAG: The specific version of the image to pull.

Install Docker Engine

Below is an example of the commands needed to Install Docker Engine on CentOS. See Install Docker Engine for other operating systems. If you already have Docker Engine installed, proceed to Setup Runner Manager.

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo groupadd docker
sudo usermod -aG docker $USER
sudo systemctl enable docker.service
sudo systemctl enable containerd.service
sudo chmod 777 '/var/run/docker.sock'
sudo systemctl start docker
docker run hello-world

Create an Agent Configuration File

Create a single file on the Docker host that contains the Runner Configuration. This file will be mounted to each runner when provisioned.

cat > runner_agent.json << EOF
{
  "LOG_PATH": "/var/log/runner-agent",
  "LOG_LEVEL": "info"
}
EOF

Start the Runner Pool Container

The following docker run command is an example of how to start the runner-pool container.

docker run --rm --interactive --tty \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume $(pwd)/runner_agent.json:/etc/runner_agent.json \
--name runner-pool \
--env ENVIRONMENT=prod \
--env RUNNER_MANAGER_ID=<YourRunnerManagerIdHere> \
--env RUNNER_MANAGER_KEY=<YourRunnerManagerKeyHere> \
--env CONFIG_PATH=/etc/runner_agent.json \
--env LOG_LEVEL=debug \
--env RUNNER_LOCAL_DOCKER_IMAGE_REGISTRY=docker.io \
--env RUNNER_LOCAL_DOCKER_IMAGE_REPOSITORY=refactr/runner \
--env RUNNER_LOCAL_DOCKER_IMAGE_TAG=latest \
refactr/runner-pool

NOTE See Self Hosted Runner Authentication to help locate the RUNNER_MANAGER_ID and RUNNER_MANAGER_KEY

Here is an explanation of each component of the command.

• --rm: Automatically remove the container when it exits.
• --interactive: Keep STDIN open even if not attached.
• --tty: Allocate a pseudo-TTY
• --volume /var/run/docker.sock:/var/run/docker.sock:
  • The runner-pool container needs access to docker.sock to orchestrate the provisioning and deprovisioning of runner containers. ¹
• --volume $(pwd)/runner_agent.json:/etc/runner_agent.json:
  • Mounts the runner agent configuration file referenced earlier. Ensure the path is correct.
• --name runner-pool:
  • The name to assign to the container. In this case, runner-pool.
• ENVIRONMENT: See Configuring Runner Pool.
• RUNNER_MANAGER_ID: See Configuring Runner Pool.
• RUNNER_MANAGER_KEY: See Configuring Runner Pool.
• CONFIG_PATH: See Runner Configuration.
• LOG_LEVEL: See Runner Configuration.
• RUNNER_LOCAL_DOCKER_IMAGE_REGISTRY: See Docker Provider Configuration.
• RUNNER_LOCAL_DOCKER_IMAGE_REPOSITORY: See Docker Provider Configuration.
• RUNNER_LOCAL_DOCKER_IMAGE_TAG: See Docker Provider Configuration.
• refactr/runner-pool
  • The source image to use for this container, in this case refactr/runner-pool.

Runner Pool Console Output

Once you have executed the docker run command, you will see console output similar to the output below:

2023-07-19 20:39:14 debug: --- --- --- --- ---
2023-07-19 20:39:14 info: --- Processing Tick #1 ---
2023-07-19 20:39:14 debug: Processing RM State bootup
2023-07-19 20:39:14 debug: Bootup! Attempting to register as leader
2023-07-19 20:39:14 debug: undefined
2023-07-19 20:39:14 warn: Missing instanceID!!!
2023-07-19 20:39:14 debug: Register completed!
2023-07-19 20:39:14 debug: Initializing Provider!
2023-07-19 20:39:14 debug: Provisioning Runner: local_docker
2023-07-19 20:39:14 debug: handleBootup() Success
2023-07-19 20:39:14 debug: {
  current: 'inactive',
  tickCount: 1,
  lastTick: 2023-07-19T20:39:14.658Z,
  running: true,
  instance: {
    _id: '64b849f23b616134fbdc2fc0',
    status: 'inactive',
    statusDate: '2023-07-19T20:39:14.742Z',
    started: '2023-07-19T20:39:14.742Z',
    heartbeat: '2023-07-19T20:39:14.742Z',
    errorCount: 0
  },
  bootupDate: 2023-07-19T20:39:14.754Z
}
2023-07-19 20:39:14 info: --- Tick #1 Completed ---