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.
Prerequisites
| Requirement | Details |
|---|---|
| Main server | A running self-hosted instance and Super Admin access |
| Each worker server | Ubuntu 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+ |
| Network | VPN 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 |
| Versions | App, 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
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=2In 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.10From deploy/docker, apply the change:
sudo docker compose up -dPrepare 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.shStart 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_KEYchmod 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 300Verify 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 300Workers keep no data, so they need no backup; keep their .env private.