SuperCheck Docker Compose Deployment

Deployment Variants

SuperCheck ships five Docker Compose files in deploy/docker/:

Decision Guide

• Single server, no TLS → docker-compose.yml
• Single server, HTTPS → docker-compose-secure.yml (requires DNS + port 80)
• Using Neon/Supabase/RDS + managed Redis/S3 → docker-compose-external.yml
• Add workers in other regions → docker-compose-worker.yml per remote server
• Local dev iteration → docker-compose-local.yml

Prerequisites

1. Linux host (Ubuntu 22.04+, Debian 12+) — amd64 or arm64
2. Docker Engine 24+ with Compose V2
3. K3s + gVisor for test execution sandbox:

   cd deploy/docker && sudo bash setup-k3s.sh
   

4. Secrets — generate .env:

   sudo bash init-secrets.sh
   

Version Management

All compose files use SUPERCHECK_VERSION with a fallback default:

image: ghcr.io/supercheck-io/supercheck/app:${SUPERCHECK_VERSION:-1.3.5}
image: ghcr.io/supercheck-io/supercheck/worker:${SUPERCHECK_VERSION:-1.3.5}

Upgrading

SUPERCHECK_VERSION=1.4.0 docker compose up -d
# Or persist: echo 'SUPERCHECK_VERSION=1.4.0' >> .env

Version Bump Checklist

When releasing a new version, update these files:

supercheck repo:

• app/package.json, worker/package.json — "version" field
• app/package-lock.json, worker/package-lock.json — root version entries (lines 3, 9)
• app/src/components/app-sidebar.tsx — badge: value
• deploy/docker/docker-compose.yml — 3 image refs
• deploy/docker/docker-compose-worker.yml — 2 image refs
• deploy/docker/docker-compose-secure.yml — 3 image refs
• deploy/docker/docker-compose-external.yml — 3 image refs
• CHANGELOG.md — release header

Do NOT change: docker-compose-local.yml (builds from source), coolify/supercheck.yaml (defaults to latest via ${SUPERCHECK_VERSION:-latest}), docs/package.json (separate versioning)

Environment Variables

Core — Required for All Deployments

Redis

App uses REDIS_URL=redis://:password@redis:6379

Remote worker (docker-compose-worker.yml) uses individual vars — NOT REDIS_URL:

REDIS_HOST=main-server.com
REDIS_PORT=6379
REDIS_PASSWORD=password

HTTPS (docker-compose-secure.yml)

Cloudflare users: SSL/TLS mode must be "Full (Strict)" to avoid redirect loops.

Capacity & Scaling

Rule: RUNNING_CAPACITY = total WORKER_REPLICAS across all locations. Each worker replica handles exactly 1 concurrent execution.

Execution

Optional Features

STATUS_PAGE_DOMAIN reserves the default status-page namespace ([uuid].STATUS_PAGE_DOMAIN) and is the CNAME target shown for custom-domain setup. CNAME verification accepts STATUS_PAGE_DOMAIN, cname.STATUS_PAGE_DOMAIN, and ingress.STATUS_PAGE_DOMAIN as valid targets. The HTTPS Compose variants also define a lower-priority catch-all Traefik router so verified custom domains outside that namespace route to the app without extra manual host entries. If Cloudflare fronts the custom hostname, leave it on DNS-only until the origin serves HTTPS for that hostname.

Service Architecture

Startup Order

PostgreSQL (healthy) ──┐
Redis (healthy) ───────┤──→ App (runs Drizzle migrations) ──→ Worker (K8s init)
MinIO (healthy) ───────┘

Health Checks

Resource Limits

Security Hardening

Worker Container (GVISOR-006)

• read_only: true — read-only root filesystem
• user: "1000:1000" — non-root (pwuser)
• cap_drop: [ALL] — no capabilities
• security_opt: [no-new-privileges:true]
• Writable tmpfs only: /tmp (2G), /home/pwuser/.cache (256M), /home/pwuser/.npm (256M)

gVisor Sandbox

Each test execution runs in a per-run K8s Job with runtimeClassName: gvisor:

• Kernel-level syscall interception
• supercheck-execution namespace with NetworkPolicy (deny all except DNS)
• LimitRange: max 1.5 CPU, 2GB per pod
• ResourceQuota: max 4 CPU, 16GB for namespace

Network Isolation

• PostgreSQL, Redis, MinIO bind to 127.0.0.1 only
• Only Traefik (secure variant) binds to 0.0.0.0

Scaling

Single-Server

WORKER_REPLICAS=4 RUNNING_CAPACITY=4 QUEUED_CAPACITY=20 docker compose up -d

Multi-Location

# Main server
WORKER_LOCATION=local WORKER_REPLICAS=2 docker compose up -d

# US-East remote (worker only)
WORKER_LOCATION=us-east WORKER_REPLICAS=2 docker compose -f docker-compose-worker.yml up -d

# EU-West remote (worker only)
WORKER_LOCATION=eu-west WORKER_REPLICAS=2 docker compose -f docker-compose-worker.yml up -d

# Main server: RUNNING_CAPACITY = 2+2+2 = 6

Demo Server (Docker Compose Production)

The Docker Compose production deployment runs on a dedicated Hetzner server as the demo site (demo.supercheck.dev).

Server Details

Deployment Commands

Always SSH into the demo server for Docker Compose deployments:

# Check current running versions
ssh root@88.198.125.135 "docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'"

# Update version (supports semver, canary, rc tags — e.g. 1.3.3, 1.3.3-canary.1, 1.4.0-rc.2)
ssh root@88.198.125.135 "sed -i 's/SUPERCHECK_VERSION=.*/SUPERCHECK_VERSION=<new_version>/' /root/supercheck/deploy/docker/.env"

# Pull new images and redeploy
ssh root@88.198.125.135 "cd /root/supercheck/deploy/docker && docker compose -f docker-compose-secure.yml pull app worker && docker compose -f docker-compose-secure.yml up -d app worker"

# Verify deployment
ssh root@88.198.125.135 "docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'"

# View logs (tail 30 lines of both services)
ssh root@88.198.125.135 "cd /root/supercheck/deploy/docker && docker compose -f docker-compose-secure.yml logs --tail=30 app worker"

Version Upgrade Procedure

1. Update .env on the server: SUPERCHECK_VERSION=<new_version> (supports stable, canary, rc tags)
2. Pull images: docker compose -f docker-compose-secure.yml pull app worker
3. Redeploy: docker compose -f docker-compose-secure.yml up -d app worker
4. Verify: docker ps — confirm all containers show new version and (healthy)
5. Check logs: docker compose -f docker-compose-secure.yml logs --tail=30 app worker — confirm no errors

Note on version tags: Canary and RC releases follow the pattern <version>-canary.<n> and <version>-rc.<n> (e.g. 1.3.3-canary.1). These are deployable like stable releases. When bumping compose file defaults locally, also update the ${SUPERCHECK_VERSION:-...} fallback in all 4 compose files.

Important: Do NOT run Docker Compose locally. The demo/production Docker Compose environment is on this server.

Operations

On the demo server (ssh root@88.198.125.135):

cd /root/supercheck/deploy/docker

docker compose -f docker-compose-secure.yml up -d        # Start all
docker compose -f docker-compose-secure.yml stop          # Stop (preserves data)
docker compose -f docker-compose-secure.yml down -v       # Full teardown (DATA LOSS)
docker compose -f docker-compose-secure.yml logs -f app   # App logs
docker compose -f docker-compose-secure.yml logs -f worker # Worker logs
docker compose -f docker-compose-secure.yml exec postgres pg_dump -U postgres supercheck > backup.sql  # Backup

Troubleshooting

File Reference