Self-hosting

Run VariantGate on your own server: setup, email, sign-on, upgrades and backups.

Keep API_ENFORCE_PLAN_LIMITS off on your own server: every feature stays available and no plan limits apply.

Everything VariantGate is runs from one Docker Compose file on one server: Postgres, sign-in (Supabase Auth), the API and the website. It is the same setup variantgate.com runs on. Self-hosting is part of the Enterprise plan; you get the code and the files below with it.

What you need

  • A Linux server with Docker and the Compose plugin. Two CPU cores, 4 GB of memory and 40 GB of disk are a comfortable start.
  • Three names pointing at it, such as vg.acme.com for the website, api.vg.acme.com and auth.vg.acme.com.
  • A web server in front that ends TLS. deploy/nginx has a configuration for nginx with a Let’s Encrypt certificate.
  • An email service that speaks SMTP, such as Resend, Postmark or your own. Sign-in links are sent by email.

Setting it up

  1. Copy the code to the server, for example to /opt/variantgate.
  2. Create the settings file and the secrets in it, then start everything:
cp deploy/.env.example deploy/.env
deploy/make-secrets.sh >> deploy/.env
chmod 600 deploy/.env
# fill in the addresses and the email settings, then:
docker compose -f deploy/compose.yml up -d --build
  1. Point the three names at the server and get a certificate covering them.
  2. Copy deploy/nginx/variantgate.conf to /etc/nginx/sites-enabled/ and the two files beside it to /etc/nginx/. Replace variantgate.com with your names, including the website origin allowed to call sign-in. Without Cloudflare in front, remove the real_ip lines.
  3. Open the website, sign in with your email, and create the first workspace.

The ports listen on 127.0.0.1 only and the database on none, so only nginx is reachable from outside. Let in SSH, 80 and 443.

Settings

All settings live in deploy/.env. Keep it readable by root only: it holds the database password and the sign-in signing key.

SITE_URL
The website's address, such as https://vg.acme.com.
API_URL
The API's address.
AUTH_URL
The sign-in service's address.
POSTGRES_PASSWORD, JWT_SECRET, JWT_KEYS, PUBLISHABLE_KEY, SAML_PRIVATE_KEY
Generated by deploy/make-secrets.sh. Do not change them on a running server: JWT_KEYS signs every session, and the database keeps the password it started with.
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM
Email for sign-in links.
EMAIL_API_KEY, EMAIL_FROM
Email to members when a request waits, with Approve and Deny links. Sent through Resend's API; leave EMAIL_API_KEY empty to send none.
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT
Push notifications to browsers. Make the pair once with node scripts/vapid-keys.mjs >> deploy/.env; leave both keys empty to keep push off.
INQUIRY_EMAIL
Where the Enterprise form on the website sends inquiries. Set your own address, or leave it empty to turn the form off.
SAML_ENABLED
true to offer single sign-on.
API_ENFORCE_PLAN_LIMITS
Leave false: on your own server no plan limits apply.
STRIPE_*
Leave empty. Billing is for the hosted service only.
BACKUP_DIR, BACKUP_REMOTE
Where backups go. See below.

Email

Sign-in links go out through the SMTP server in SMTP_HOST, from the address in SMTP_FROM. Verify that address’s domain with your email service (SPF and DKIM records), or links land in spam. Emails about waiting requests are separate: they go through Resend’s API with EMAIL_API_KEY, from EMAIL_FROM.

  • Use port 587 with STARTTLS. Port 465 also works; many hosts block port 25.
  • A link is valid for an hour, and one address gets at most one link a minute.
  • If no link arrives, docker compose -f deploy/compose.yml logs auth shows what the email service answered.

Single sign-on

To let people sign in through your identity provider over SAML, set SAML_ENABLED=true in deploy/.env and run the start command again. Then add each provider with its metadata URL and the email domains it signs in:

deploy/sso-provider.sh add https://idp.acme.com/metadata acme.com
deploy/sso-provider.sh list
deploy/sso-provider.sh remove <provider-id>

The script talks to the sign-in service on the server itself, with a five-minute admin token it signs from JWT_KEYS; it needs curl and python3. In the identity provider, use the addresses from Single sign-on with your own AUTH_URL in place of ours.

Upgrading

cd /opt/variantgate
# replace the code with the new release, keeping deploy/.env
docker compose -f deploy/compose.yml up -d --build
  • The database is migrated when the new API starts. Migrations only add, so they are safe while the old version is still answering.
  • The API waits up to 50 seconds for calls in progress, since an agent may be waiting for a decision.
  • Read the release notes first. When a release adds a new kind of rule, they say what to wait for before using it.
  • Back up before upgrading. Going back to an older release is safe only if the release notes say so.

Backups and restore

deploy/backup.sh writes a compressed dump of the product data and of the accounts to BACKUP_DIR and keeps 14 days. Set BACKUP_REMOTE to an rsync destination to keep a copy off the server too. Run it nightly from root’s crontab:

15 2 * * * /opt/variantgate/deploy/backup.sh >> /var/log/variantgate-backup.log 2>&1

Restoring

Stop everything but the database, load the dump, and start again. The restore replaces the current data with the backup’s.

docker compose -f deploy/compose.yml stop api auth web
cp variantgate-20261113T020000Z.dump /var/backups/variantgate/
docker compose -f deploy/compose.yml exec db pg_restore -U postgres \
  -d postgres --clean --if-exists /backups/variantgate-20261113T020000Z.dump
docker compose -f deploy/compose.yml start api auth web

A backup holds every decision and every account. Keep BACKUP_REMOTE somewhere only you can read, and try a restore on a spare server before you need one.

Keeping an eye on it

  • /healthz on the API answers while it runs; /readyz only while it can reach the database. Alert when /readyz fails.
  • Every server error is logged once, as JSON, with a request id. People see the same id in the app, so one id finds the whole story: docker compose -f deploy/compose.yml logs api.