Self-Hosted Setup

Deployment Options

Option	SSL/HTTPS	Status Pages
Without Domain	❌ HTTP only	❌ No
With Domain	✅ Automatic	✅ Yes

Option 1: Without Domain

Best for testing or internal networks. No configuration required — all secrets are auto-generated.

Install Docker

Skip this step if you already have Docker or Docker Desktop installed.

Option A: Docker Engine (Linux/Server)

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

Option B: Docker Desktop (Mac/Windows/Linux)

Download from docker.com/products/docker-desktop

Clone Repository

git clone https://github.com/supercheck-io/supercheck.git
cd supercheck/deploy/docker

Configure OAuth

At least one OAuth provider is required. Create a .env file:

# GitHub OAuth (get from https://github.com/settings/developers)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

See OAuth Setup for detailed instructions.

Deploy

docker compose up -d

Access at http://localhost:3000.

Security secrets (BETTER_AUTH_SECRET, SECRET_ENCRYPTION_KEY, database passwords) are auto-generated with secure defaults. Override in .env only if needed.

Option 2: With Domain

For deployments with HTTPS and status pages.

Install Docker

Skip this step if you already have Docker or Docker Desktop installed.

Option A: Docker Engine (Linux/Server)

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

Option B: Docker Desktop (Mac/Windows/Linux)

Download from docker.com/products/docker-desktop

Configure DNS

Go to your DNS provider (Cloudflare, Route53, etc.)
Create an A Record: app.yourdomain.com → Your server IP
For status pages: *.yourdomain.com → Your server IP

DNS changes take 5-30 minutes. Verify with dig app.yourdomain.com.

Clone Repository

git clone https://github.com/supercheck-io/supercheck.git
cd supercheck/deploy/docker

Configure Environment

Create .env file with your domain:

# Your domain (required) - all URLs are derived from this
APP_DOMAIN=app.yourdomain.com
ACME_EMAIL=admin@yourdomain.com

# OAuth (at least one provider required)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Security secrets are auto-generated. Only your domain is required.

Deploy

docker compose -f docker-compose-secure.yml up -d

Access at https://app.yourdomain.com.

OAuth (Required)

At least one provider is required for authentication.

GitHub OAuth

Go to GitHub Developer Settings
Click New OAuth App
Set callback URL: https://app.yourdomain.com/api/auth/callback/github

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Google OAuth

Go to Google Cloud Console
Create OAuth 2.0 credentials
Add redirect URI: https://app.yourdomain.com/api/auth/callback/google

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

Optional: Email (SMTP)

Required for alerts, password resets, and invitations.

# Your SMTP server (Gmail, SendGrid, Mailgun, AWS SES, etc.)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=notifications@yourdomain.com

Optional: AI Features

Enables AI-powered test fix suggestions.

# OpenAI API key from https://platform.openai.com
OPENAI_API_KEY=sk-your-api-key

# Model options: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
AI_MODEL=gpt-4o-mini

Scaling Workers

By default, Supercheck runs with 1 worker for single-server deployments. Scale for more concurrent tests:

# Scale to 2 workers (requires RUNNING_CAPACITY adjustment)
WORKER_REPLICAS=2 RUNNING_CAPACITY=2 docker compose up -d

Capacity Planning

Workers	Concurrent Tests	Server Size
1	1	2 vCPU / 4GB
2	2	4 vCPU / 8GB
4	4	8 vCPU / 16GB

Each worker runs one Playwright test at a time with 1 browser worker inside the container (default for 2GB container memory). For larger servers, set PLAYWRIGHT_WORKERS=2.

Updates

# Pull latest images
docker compose pull
docker compose up -d

Backup

# Export database
docker exec supercheck-postgres pg_dump -U postgres supercheck > backup.sql

# Restore
cat backup.sql | docker exec -i supercheck-postgres psql -U postgres supercheck

Troubleshooting

Container won't start: docker compose logs app

Database errors: docker compose ps

SSL issues: Ensure ports 80/443 are open

DNS not resolving: Wait for propagation or check with dig yourdomain.com

On this page