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.comfor the website,api.vg.acme.comandauth.vg.acme.com. - A web server in front that ends TLS.
deploy/nginxhas 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
- Copy the code to the server, for example to
/opt/variantgate. - 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- Point the three names at the server and get a certificate covering them.
- Copy
deploy/nginx/variantgate.confto/etc/nginx/sites-enabled/and the two files beside it to/etc/nginx/. Replacevariantgate.comwith your names, including the website origin allowed to call sign-in. Without Cloudflare in front, remove thereal_iplines. - 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.
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 authshows 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>&1Restoring
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 webA 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
/healthzon the API answers while it runs;/readyzonly while it can reach the database. Alert when/readyzfails.- 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.