Configuration
The installer generates .env for you (see Installation), but it’s
worth understanding what’s in it — especially if you’re editing it by hand later. It sits next to
docker-compose.prod.yml on the server.
| Variable | Purpose |
|---|---|
IMAGE_PREFIX |
Container registry path. Access is fully automatic — the Updater reads your license and asks Kuzium’s License Server for a short-lived pull token before every update, so there’s no static registry credential to manage or rotate. |
COMPOSE_PROJECT_DIR |
The absolute path on this server where the compose files actually live (e.g. /opt/orbit). Must be exact — the updater bind-mounts this same path on both sides so docker compose inside its container resolves paths the same way the host does. |
UPDATE_SHARED_SECRET |
Gates the updater’s internal-only endpoints. Only the api container calls these; never exposed publicly. |
FRONTEND_BASE_URL |
Your public domain, e.g. https://orbit.example-corp.com. Drives emailed action links and the OpenAPI spec’s advertised server URL. |
DEPLOYMENT_MODE |
Always SelfHost here — pins the instance to a single tenant, disabling public registration and the cross-tenant/System Admin surface. |
DEPLOYMENT_SETUP_TOKEN |
One-time token required by /auth/bootstrap to create the first account. Required before the instance is reachable externally. |
Database — appliance vs. bring-your-own
Section titled “Database — appliance vs. bring-your-own”Leave DATABASE_CONNECTION_STRING blank and set POSTGRES_PASSWORD to use the bundled Postgres
container — no extra setup. To bring your own managed Postgres instead, set
DATABASE_CONNECTION_STRING (Host=...;Port=5432;Database=...;Username=...;Password=...) and add
the BYO-DB compose overlay — this drops api/worker’s dependency on the bundled container
entirely so it never starts. See Backups & add-ons for the
exact -f flags.
Object storage — bring-your-own S3 vs. bundled MinIO
Section titled “Object storage — bring-your-own S3 vs. bundled MinIO”Bring-your-own is the default: fill in all five S3_* variables for any S3-compatible provider.
To use the bundled MinIO appliance instead, leave S3_ENDPOINT/S3_BUCKET/S3_REGION blank
(sane defaults take over: http://minio:9000, bucket orbit-uploads, region us-east-1) and
just set S3_ACCESS_KEY/S3_SECRET_KEY — these double as MinIO’s own root credentials.
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_ADDRESS — your own mailbox
for verification, invite, and password-reset emails. This is the only supported email path for
self-hosted instances.
Secrets
Section titled “Secrets”POSTGRES_PASSWORD, RABBITMQ_PASSWORD, GRAFANA_ADMIN_PASSWORD, and JWT_SIGNING_KEY should
all be strong random values — the installer generates these for you; if you’re editing .env by
hand, use openssl rand -base64 24 (or -base64 48 for the JWT signing key).
Next: Reverse proxy & TLS.