Multi-Server
Add execution workers on separate servers to your self-hosted installationEdit
Add execution workers on separate Linux servers to an existing Self-Hosted installation. This guide is for infrastructure you manage; it does not describe Supercheck Cloud availability.
Architecture
Scroll horizontally to view the full diagram.
Worker Setup
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 minimum (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) |
| Versions | App, workers, Compose files, and scripts from the same release. Examples use 1.3.7-canary.16 |
Never expose PostgreSQL, Redis, or S3 publicly. Allow only worker hosts. macOS, Windows, WSL2, and Docker Desktop are not supported for workers.
Set up
Configure the main server
In Super Admin, add and enable one execution entry per worker, such as worker-main and worker-extra. Each worker's WORKER_LOCATION must match its entry's code.
Set the main server's .env. RUNNING_CAPACITY is the total number of workers across all servers (2 in this example); the app admits at most that many concurrent runs:
WORKER_LOCATION=worker-main
RUNNING_CAPACITY=2In docker-compose.yml, replace the 127.0.0.1 PostgreSQL, Redis, and RustFS port bindings with the server's private VPN address:
services:
postgres:
ports:
- "10.0.0.10:5432:5432"
redis:
ports:
- "10.0.0.10:6379:6379"
rustfs:
ports:
- "10.0.0.10:9000:9000"From deploy/docker, apply the change (keep any custom -f option):
sudo env KUBECONFIG_FILE=/etc/rancher/k3s/supercheck-worker.kubeconfig 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.3.7-canary.16/deploy/docker/setup-k3s.sh
curl -fsSL -o docker-compose-worker.yml https://raw.githubusercontent.com/supercheck-io/supercheck/v1.3.7-canary.16/deploy/docker/docker-compose-worker.yml
sudo bash setup-k3s.shStart the worker
Create .env in the same directory. Use the main server's private address, the same database and storage, and the credentials from the main server's .env (DB_PASSWORD, REDIS_PASSWORD, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY):
WORKER_LOCATION=worker-extra
SELF_HOSTED=true
SUPERCHECK_VERSION=1.3.7-canary.16
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
AWS_ACCESS_KEY_ID=YOUR_S3_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_S3_SECRET_KEYchmod 600 .env
sudo env KUBECONFIG_FILE=/etc/rancher/k3s/supercheck-worker.kubeconfig docker compose -f docker-compose-worker.yml up -d --wait --wait-timeout 300Verify execution
Confirm the execution entry shows Active, then run a monitor or k6 test against that entry and inspect the result. A heartbeat alone does not prove the database, Redis, and storage connections work.
Playwright uses a shared queue, so adding a worker does not pin browser tests to a particular server. Keep local for the default single-server setup; register distinct codes only for additional execution targets.
Choosing what each worker runs
By default a worker consumes every queue, which suits most setups. To make a server lightweight (for example, monitoring only), set WORKER_QUEUES in that worker's .env:
| Token | Queue consumed |
|---|---|
monitor | Regional monitor queue (HTTP, SSL, ping, port, and synthetic monitors) |
k6 | Regional k6 queue, only when the location has Performance tests on |
global-playwright | Shared Playwright queue (tests and CI jobs) |
global-k6 | Shared k6 queue |
WORKER_QUEUES=monitorAn unknown token stops the worker at startup. Which workloads users may run in a location is set separately in Super Admin (Workload Capabilities).
CANCELLED_QUEUED_RECOVERY_ENABLED (default false) ends runs that were cancelled before they started and never picked up. Set it to true on every worker, only after all of them run the current version.
For custom connection, bucket, or TLS settings, match the worker Compose file.
Missing-region detection
With workers in several locations, a silent region holds up a monitor result by default. This option closes each run at a deadline and counts silent regions as failed.