Supercheck LogoSupercheck

Multi-server deployment

Add execution workers on separate servers to a self-hosted installationEdit

Add execution workers on separate Linux servers to an existing self-hosted installation.

Architecture

Scroll horizontally to view the full diagram.

Loading diagram...

Prerequisites

RequirementDetails
Main serverA running self-hosted instance and Super Admin access
Each worker serverUbuntu 22.04+ or Debian 12+ (x86_64 or arm64), 2 vCPU, 4 GB RAM, 10 GB free disk (15 GB recommended), sudo, curl, bzip2 and Docker Engine with Compose v2.24.4+
NetworkVPN or other encrypted private link from workers to the main server's PostgreSQL (5432), Redis (6379) and S3 (9000), or your DB_HOST_PORT, REDIS_HOST_PORT and RUSTFS_HOST_PORT if moved
VersionsApp, workers, Compose files and scripts from the same release. Examples use 1.6.0

Never expose PostgreSQL, Redis or S3 publicly. Docker-published ports bypass ufw, so bind them to the private address (below) and restrict 5432, 6379 and 9000 (or your moved ports) to the worker IPs in your cloud firewall or the DOCKER-USER iptables chain. Keep the k3s API (6443) closed to the internet; each worker uses its own local k3s, and the main server's worker container reaches 6443 over the local Docker network. macOS, Windows, WSL2 and Docker Desktop are not supported for workers.

Set up

Loading diagram...

Configure the main server

In Super Admin, add and enable one entry per worker, such as worker-main and worker-extra. Each worker's WORKER_LOCATION must match its entry's code.

In the main server's .env, set RUNNING_CAPACITY to the total number of workers across all servers (2 here); the app admits at most that many concurrent runs:

WORKER_LOCATION=worker-main
RUNNING_CAPACITY=2

In the same .env, publish PostgreSQL, Redis and RustFS on the server's private VPN address instead of 127.0.0.1. Do not edit docker-compose.yml; upgrades replace it.

DB_BIND_ADDR=10.0.0.10
REDIS_BIND_ADDR=10.0.0.10
RUSTFS_BIND_ADDR=10.0.0.10

From deploy/docker, apply the change:

sudo docker compose up -d

Prepare each worker server

mkdir -p ~/supercheck-worker
cd ~/supercheck-worker
curl -fsSL -o setup-k3s.sh https://raw.githubusercontent.com/supercheck-io/supercheck/v1.6.0/deploy/docker/setup-k3s.sh
curl -fsSL -o docker-compose-worker.yml https://raw.githubusercontent.com/supercheck-io/supercheck/v1.6.0/deploy/docker/docker-compose-worker.yml
sudo bash setup-k3s.sh

Start the worker

Create .env in the same directory with the main server's private address and the credentials from its .env (DB_PASSWORD, REDIS_PASSWORD, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY):

WORKER_LOCATION=worker-extra
SELF_HOSTED=true
SUPERCHECK_VERSION=1.6.0
DATABASE_URL=postgresql://postgres:[email protected]:5432/supercheck
REDIS_HOST=10.0.0.10
REDIS_PORT=6379
REDIS_PASSWORD=YOUR_REDIS_PASSWORD
S3_ENDPOINT=http://10.0.0.10:9000
# If the main server moved DB_HOST_PORT, REDIS_HOST_PORT or RUSTFS_HOST_PORT, use those ports above.
AWS_ACCESS_KEY_ID=YOUR_S3_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_S3_SECRET_KEY
chmod 600 .env
sudo docker compose -f docker-compose-worker.yml pull
# Load the worker image into the sandbox so the first run does not time out downloading it.
# The image tag Compose resolved (honours SUPERCHECK_VERSION in .env).
WORKER_IMAGE=$(sudo docker compose -f docker-compose-worker.yml config --images | grep '/worker:' | head -n1)
sudo docker save --platform "linux/$(dpkg --print-architecture)" "$WORKER_IMAGE" | sudo k3s ctr -n k8s.io images import -
sudo docker compose -f docker-compose-worker.yml up -d --wait --wait-timeout 300

Verify execution

Confirm the entry shows Active, then run a monitor or k6 test against it. Playwright tests use a shared queue and run on any worker.

Optional worker settings

Upgrade workers

After upgrading the main server, upgrade each worker to the same release. In ~/supercheck-worker, download that release's setup-k3s.sh and docker-compose-worker.yml as in Prepare each worker server, set SUPERCHECK_VERSION in .env, then:

sudo bash setup-k3s.sh
sudo docker compose -f docker-compose-worker.yml pull
# The image tag Compose resolved (honours SUPERCHECK_VERSION in .env).
WORKER_IMAGE=$(sudo docker compose -f docker-compose-worker.yml config --images | grep '/worker:' | head -n1)
sudo docker save --platform "linux/$(dpkg --print-architecture)" "$WORKER_IMAGE" | sudo k3s ctr -n k8s.io images import -
sudo docker compose -f docker-compose-worker.yml up -d --wait --wait-timeout 300

Workers keep no data, so they need no backup; keep their .env private.

On this page