Docker

Prerequisites

This section provides all required dependencies to install and start the worker with Docker.

Dependency 1: Docker

Docker will be used for downloading the worker and managing the lifecycle of the application.

You can refer to Docker’s official documentation on installing and configuring the service.

Dependency 2: Redis

Redis will be used for storing workloads, created by the server, that will be run by a worker.

You can refer to Redis’s official documentation on installing and configuring the service.

Installation

This section provides an example of installing the worker with Docker.

This example only shows a subset of all possible configuration options.

Step 1: Download the Image

Download the Docker image for the Vela worker from DockerHub.

You can use the docker pull command to download the image:

$ docker pull target/vela-worker:latest

Step 2: Determine Worker Authentication and Start Worker

Currently, Vela supports two methods of maintaining authentication between the worker and the server.

Take care to read through both options to determine which setup makes the most sense for your installation:

Worker-Server Trusted Symmetric Token

This authentication method involves using the same secret generated as the VELA_SECRET during the server installation as the bearer token for all API requests related to check-in and build tokens from the worker to the server.

The token is non-expiring and exists within the container environment. Once the server is running, all that is necessary for a worker to connect to the server and pull builds from the queue is simply starting the worker container:

$ docker run \
  --detach=true \
  --env=VELA_QUEUE_DRIVER=redis \
  --env=VELA_SERVER_ADDR=https://vela-server.example.com \
  --env=VELA_SERVER_SECRET=<shared-secret> \
  --env=VELA_WORKER_ADDR=https://vela-worker.example.com \
  --name=worker \
  --publish=80:80 \
  --publish=443:443 \
  --restart=always \
  --volume=/var/run/docker.sock:/var/run/docker.sock \
  target/vela-worker:latest

The worker must still pass its check-in with the server in order to pull builds from the queue.

Worker Registration and Auth Refresh

This authentication method is the more secure of the two options. Rather than using a non-expiring token in the container environment, platform administrators can register workers using their credentials via the Vela CLI. In order to leverage this method, simply do NOT supply the VELA_SECRET to the server and do NOT supply the VELA_SERVER_SECRET to the worker.

To start, launch the worker container:

$ docker run \
  --detach=true \
  --env=VELA_QUEUE_DRIVER=redis \
  --env=VELA_SERVER_ADDR=https://vela-server.example.com \
  --env=VELA_WORKER_ADDR=https://vela-worker.example.com \
  --name=worker \
  --publish=80:80 \
  --publish=443:443 \
  --restart=always \
  --volume=/var/run/docker.sock:/var/run/docker.sock \
  target/vela-worker:latest

Once the worker has started, it will be in a paused state until a platform admin registers the worker:

$ vela login --api.addr https://vela-server.example.com

$ vela add worker --worker.hostname vela-worker --worker.address https://vela-worker.example.com

worker registered successfully

This process involves the generation of a registration token, which can only be done by platform admins. The quickly expiring registration token is then passed to the worker using an http request to the worker’s /register endpoint. The worker exchanges this registration token with the server for an auth token.

Once registered, the worker will continue refreshing its authentication token at the specified check in interval. Workers that lose their connection to the server for long enough for their existing auth token to expire will need to be re-registered.

Step 3: Verify the Worker Logs

Ensure the worker started up successfully and is running as expected by inspecting the logs.

You can use the docker logs command to verify the logs:

$ docker logs worker