Self-Hosted
Install Supercheck on one server with a guided commandEdit
Self-host Supercheck on one Linux server. One command installs Docker, the isolated test sandbox, and every Supercheck service, then checks that it is healthy.
Architecture
Scroll horizontally to view the full diagram.
Prerequisites
| Requirement | Details |
|---|---|
| OS | Ubuntu 22.04+ or Debian 12+ (x86_64 or arm64) |
| Resources | 2 vCPU and 4 GB RAM minimum; 10 GB free disk minimum, 15 GB to start, 30–50 GB for regular use |
| Access | sudo and outbound internet access. Docker and Compose are installed for you |
| Public HTTPS only | A domain pointing at the server, inbound ports 80 and 443, and an email address for certificate notices. Status pages on subdomains also need a wildcard DNS record and a wildcard certificate |
Linux only. The test sandbox needs the Linux kernel. macOS, Windows, WSL2, and Docker Desktop are not supported.
Install
Download the installer
curl -fsSL https://raw.githubusercontent.com/supercheck-io/supercheck/v1.6.0/deploy/docker/install.sh -o install.shUse the same release in the URL and in --version. Add --dry-run in the next step to preview the plan.
Run it
sudo bash install.sh --version 1.6.0The installer asks only what it cannot detect:
| Prompt | Default | Notes |
|---|---|---|
Choose | 1 | 1 = try it on this server (HTTP on localhost); 2 = public server (HTTPS) |
Domain for Supercheck | none | Public only. A hostname such as app.example.com, not an IP address or URL |
Email for Let's Encrypt notices | none | Public only |
Continue? | Yes | Last confirmation before anything is installed |
Allow about 10 minutes. Re-running is safe: it keeps your .env and secrets.
Open Supercheck
Open the URL the installer prints: https://<your-domain>, or http://localhost:3000 for a local install (from your laptop: ssh -L 3000:localhost:3000 <user>@<server>). The HTTPS certificate can take a minute on first visit.
On a public server, sign-up is open to anyone who can reach the URL. Create your account first, then set SIGNUP_ENABLED=false in .env (or restrict it with ALLOWED_EMAIL_DOMAINS) and recreate the app. See Optional configuration.
Verify
Run from /opt/supercheck/deploy/docker (or <your --dir>/deploy/docker):
sudo docker compose ps
curl --fail --silent --show-error http://localhost:3000/api/healthAll services should be healthy and the health endpoint should return {"status":"ok".... For HTTPS, also open https://<your-domain>/api/health.
Optional configuration
Edit .env in deploy/docker, then run sudo docker compose up -d --force-recreate app worker (add monitor-control if you enabled it).
Upgrade
Download the installer of the release you want and run it with --upgrade on the server:
curl -fsSL https://raw.githubusercontent.com/supercheck-io/supercheck/v1.6.0/deploy/docker/install.sh -o install.sh
sudo bash install.sh --upgradeUpgrading from a release before 1.6.0 runs migration 0056, which drops columns the previous release still reads. Upgrade in a short maintenance window and don't roll back the image afterwards; restore the pre-upgrade backup instead. Keep the same SECRET_ENCRYPTION_KEY: older webhook secrets are encrypted with it during the upgrade. Unsubscribe links in emails sent before the upgrade stop working.
Replace v1.6.0 with the target release. The upgrade dumps the database to /var/backups/supercheck/ first, applies migrations, and checks health; expect a few minutes of downtime. Keep your changes in .env: the upgrade stops if tracked files were edited. Then upgrade remote workers.
Never run docker compose down -v: it deletes the database, stored artifacts, and the queue.
Backups
From deploy/docker:
sudo bash backup.shThis saves the database, storage, .env and certificates to /var/backups/supercheck/<UTC time>/, stopping the app and worker for about a minute. Copy backups off the server and keep them private: they contain your secrets.
To restore, install the same release as the backup (on a new server, install it first), stop remote workers, then run the command below. It permanently replaces the current .env, storage and database:
sudo bash backup.sh --restore /var/backups/supercheck/<UTC time>For daily backups (old backups are not deleted, so prune them to keep the disk from filling):
echo '0 3 * * * root cd /opt/supercheck/deploy/docker && bash backup.sh >>/var/log/supercheck/backup.log 2>&1' | sudo tee /etc/cron.d/supercheck-backupExternal PostgreSQL, Redis or S3 are not covered; use your provider's backups.