Invarn Docs

Self-hosting

Run your own Invarn with Docker Compose.

Invarn is two server processes, its dashboard, and PostgreSQL 16 or later, each its own image. invarn-gateway receives Discord's events; invarn-http serves the API, sign-in and Discord's interactions, and runs background jobs. The dashboard's image is Caddy serving it at /app and passing every other path to invarn-http.

With Docker Compose

  1. Create a Discord application and note its token, application ID, public key and client secret.
  2. Clone the repository and copy server/.env.example to server/.env. Fill in the Discord values and an encryption key (openssl rand -base64 32). Set INVARN_PUBLIC_URL to where people will open Invarn, for example https://invarn.example.com.
  3. Start it:
cd server && docker compose up -d --build

Open http://localhost:24100/app/. To serve it elsewhere, put a reverse proxy that terminates TLS in front of port 24100.

Configuration

VariableWhat it does
INVARN_DATABASE_URLPostgreSQL connection string.
INVARN_PUBLIC_URLThe origin people use; sign-in redirects and links in Discord use it.
INVARN_DISCORD_TOKEN, _APP_ID, _PUBLIC_KEY, _CLIENT_SECRETThe Discord application.
INVARN_ENCRYPTION_KEY32 bytes, base64: encrypts stored Discord tokens.
INVARN_SHARDSFor invarn-gateway: i/n, this process being i (from 0) of n. Default 0/1.
INVARN_SHARD_COUNTGateway shards; empty uses Discord's recommendation. Required with more than one gateway.
INVARN_SMTP_URL, INVARN_MAIL_FROMEmail for appeal updates (smtp://user:pass@host:port, or smtps://). Optional.
INVARN_STRIPE_*Payments. Without them and a server SKU, every server gets everything.
INVARN_DISCORD_SERVER_SKUA server subscription sold in Discord's store; its webhook is /webhooks/discord.
INVARN_SENTRY_DSNError reports (Sentry or Bugsink). Optional.

Scaling

The two processes scale apart, and never talk to each other: they meet in Postgres.

  • More requests (commands, the dashboard, jobs): run more invarn-http behind your load balancer.
  • More servers: split the gateway shards between several invarn-gateway processes with INVARN_SHARDS (0/2 and 1/2, say) and set INVARN_SHARD_COUNT. Never let two processes run the same shard on one token, so stop the old ones before changing n.

On shutdown a gateway process saves its sessions, so the next one resumes them instead of missing events.

Commands and buttons arrive over the gateway unless the application's Interactions Endpoint URL is set to https://<your host>/interactions; then they go to invarn-http, spread across its processes, and keep working while a gateway restarts.

On this page