Multi-Location Workers

Enable true multi-location monitoring and performance testing by deploying workers in different geographic regions.

How It Works

Loading diagram...

Key Insight: Each worker only processes jobs for its designated region. A US worker only handles us-east jobs, an EU worker only handles eu-central jobs.

Architecture Overview

`WORKER_LOCATION`	Queues Processed	Use Case
`local`	All queues (regional + global)	Local development, single-server
`us-east`	`playwright-global`, `k6-us-east`, `k6-global`, `monitor-us-east`	US East regional worker
`eu-central`	`playwright-global`, `k6-eu-central`, `k6-global`, `monitor-eu-central`	EU Central regional worker
`asia-pacific`	`playwright-global`, `k6-asia-pacific`, `k6-global`, `monitor-asia-pacific`	Asia Pacific regional worker

Setup

For true geographic distribution, deploy workers in each region.

Configure Main Server Location

Update your main server's .env to set a specific region:

# Set to your main server's actual location
WORKER_LOCATION=eu-central

Restart:

docker compose down && docker compose up -d

Expose Services

Update your Docker Compose to expose database services for remote workers:

If you are using docker-compose-secure.yml (recommended), you need to expose the ports in that file.

Security Notice: See the Security Notice section below before exposing these ports.

Edit docker-compose-secure.yml:

services:
  postgres:
    ports:
      - "5432:5432"
  
  redis:
    ports:
      - "6379:6379"
  
  minio:
    ports:
      - "9000:9000"

For local testing or internal networks docker-compose.yml:

services:
  postgres:
    ports:
      - "5432:5432"
  
  redis:
    ports:
      - "6379:6379"
  
  minio:
    ports:
      - "9000:9000"

Deploy Remote Workers

On each remote VPS:

1. Install Docker:

Skip this step if Docker is already installed on the remote VPS.

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Download Docker Desktop for Mac.

Download Docker Desktop for Windows.

2. Download Worker Compose:

mkdir -p ~/supercheck-worker && cd ~/supercheck-worker
curl -o docker-compose.yml https://raw.githubusercontent.com/supercheck-io/supercheck/main/deploy/docker/docker-compose-worker.yml

3. Create .env:

Create a .env file with the following configuration. Replace the placeholder values with your actual credentials from the main server:

# ─────────────────────────────────────────────────────────────────
# Remote Worker Configuration
# ─────────────────────────────────────────────────────────────────

# Database connection (get password from main server's .env file)
DATABASE_URL=postgresql://postgres:YOUR_DB_PASSWORD@MAIN_SERVER_IP:5432/supercheck

# Redis connection (get password from main server's .env file)
REDIS_URL=redis://:YOUR_REDIS_PASSWORD@MAIN_SERVER_IP:6379

# S3/MinIO connection (use main server's MinIO credentials)
S3_ENDPOINT=http://MAIN_SERVER_IP:9000
AWS_ACCESS_KEY_ID=YOUR_MINIO_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_MINIO_SECRET_KEY

# ─────────────────────────────────────────────────────────────────
# Worker Location (choose one: us-east, eu-central, asia-pacific)
# ─────────────────────────────────────────────────────────────────
WORKER_LOCATION=us-east

Find your main server credentials in the .env file at supercheck/deploy/docker/.env.

4. Start Worker:

docker compose up -d
docker compose logs -f  # Verify connection

Complete 3-Region Example

Server	Region	`WORKER_LOCATION`	Queues Processed
Main Server	Europe	`eu-central`	EU Central only
Remote VPS 1	US	`us-east`	US East only
Remote VPS 2	Asia	`asia-pacific`	Asia Pacific only

Main Server `.env`:

WORKER_LOCATION=eu-central

US VPS `.env`:

# Worker location
WORKER_LOCATION=us-east

# Connection to main server (replace with your values)
DATABASE_URL=postgresql://postgres:YOUR_DB_PASSWORD@YOUR_MAIN_SERVER_IP:5432/supercheck
REDIS_URL=redis://:YOUR_REDIS_PASSWORD@YOUR_MAIN_SERVER_IP:6379
S3_ENDPOINT=http://YOUR_MAIN_SERVER_IP:9000
AWS_ACCESS_KEY_ID=YOUR_MINIO_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_MINIO_SECRET_KEY

APAC VPS `.env`:

# Worker location
WORKER_LOCATION=asia-pacific

# Connection to main server (replace with your values)
DATABASE_URL=postgresql://postgres:YOUR_DB_PASSWORD@YOUR_MAIN_SERVER_IP:5432/supercheck
REDIS_URL=redis://:YOUR_REDIS_PASSWORD@YOUR_MAIN_SERVER_IP:6379
S3_ENDPOINT=http://YOUR_MAIN_SERVER_IP:9000
AWS_ACCESS_KEY_ID=YOUR_MINIO_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_MINIO_SECRET_KEY

Scaling Workers

# Scale to 2 workers per location
WORKER_REPLICAS=2 docker compose up -d

Important: Multi-location deployments require exposing database ports (PostgreSQL, Redis, MinIO) over the network. You are responsible for securing these connections using appropriate measures such as:

VPN (WireGuard, Tailscale)
Firewall rules (UFW, iptables, Cloud Security Groups)
Encrypted tunnels

Detailed network security configuration is beyond the scope of this documentation. Please consult your infrastructure provider's security best practices.

Troubleshooting

Worker can't connect to database:

docker run --rm -it postgres:18 psql "$DATABASE_URL" -c "SELECT 1"

Worker can't connect to Redis:

docker run --rm -it redis:8 redis-cli -u "$REDIS_URL" ping

Verify worker location:

docker compose logs worker | grep "WORKER_LOCATION"

On this page