Shellius is configured through the environment. The example files in the repository are the canonical list: .env.example for development and .env.prod.example for production. The exhaustive table, including defaults, lives in docs/DEPLOYMENT.md.
This page covers the ones that matter most.
Secrets you must generate
Every one of these should be unique per deployment. Shellius refuses to start if they are left at their example values.
| Variable | Generate with | Purpose |
|---|---|---|
JWT_SECRET | openssl rand -hex 32 | Signs access tokens |
JWT_REFRESH_SECRET | openssl rand -hex 32 | Signs refresh tokens |
SERVER_ENCRYPTION_KEY | openssl rand -hex 32 | Encrypts the CA private key and stored credentials |
AGENT_SHARED_SECRET | openssl rand -hex 32 | Authenticates hosts calling the verification endpoint |
METRICS_TOKEN | openssl rand -hex 16 | Guards the Prometheus endpoint |
POSTGRES_PASSWORD | any strong value | Database password |
DANGER
SERVER_ENCRYPTION_KEY is the one you cannot lose. It encrypts your certificate authority's private key at rest. Without it the CA is unrecoverable and every bootstrapped host must be re-bootstrapped against a new one. Store a copy somewhere other than the server it runs on.
Changing JWT_SECRET or JWT_REFRESH_SECRET invalidates every existing session, which is a useful thing to do deliberately after a suspected compromise.
URLs and networking
| Variable | Notes |
|---|---|
TRAEFIK_HOST | The hostname Shellius is served at |
FRONTEND_URL | The public URL of the portal |
CORS_ORIGIN | Must match the origin the browser actually uses, scheme and port included |
Getting FRONTEND_URL or CORS_ORIGIN wrong is the most common cause of a deployment where sign-in appears to work but every subsequent request fails.
First-run seeding
| Variable | Notes |
|---|---|
SEED_ADMIN_EMAIL | The first super admin |
SEED_ADMIN_PASSWORD | Change it from the portal straight after first sign-in |
Seeding is idempotent, so it is safe across restarts.
Email
Transactional email covers invitations, password resets, access request notifications, certificate expiry warnings, and email verification. Configure SMTP through the variables listed in docs/smtp-configuration.md. Without it, Shellius still runs, but nobody gets notified when a production request needs approval — which defeats much of the approval workflow.
Single sign-on
OIDC can be configured either through environment presets or per-organisation in the database, where credentials are stored encrypted. See docs/sso-configuration.md.