Configuration

Orbit is configured with environment variables, normally in .env at the repository root. .env.example lists them all.

Database and storage

Variable	Default	Purpose
`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`	`orbit`	Postgres container credentials (Compose derives `DATABASE_URL` from them)
`DATABASE_URL`	–	`postgres://user:pass@host:port/db` (required for api and worker)
`S3_ENDPOINT_URL`	–	S3-compatible endpoint
`S3_REGION`	`us-east-1`
`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`	–	Storage credentials
`S3_BUCKET`	`orbit-storage`	Bucket name
`S3_FORCE_PATH_STYLE`	`true`	Needed for SeaweedFS and MinIO

Authentication

Variable	Default	Purpose
`JWT_SIGNING_KEY`	dev value	Change in production. Signs all tokens
`JWT_ACCESS_TTL_MINUTES`	30	Access token lifetime (sessions refresh silently)
`JWT_REFRESH_TTL_DAYS`	14	How long a session can last without signing in again
`INVITE_TOKEN_TTL_HOURS`	72	Invitation link validity
`SUPERADMIN_EMAIL`, `SUPERADMIN_PASSWORD`	–	First superadmin, created at API start-up if missing
`REQUIRE_SUPERADMIN_MFA`	`true`	Superadmins must enrol two-step verification before using Overseer
`MFA_OTP_LENGTH`	6	Code length
`MFA_CHALLENGE_TTL_SECONDS`	600	Code validity
`MFA_MAX_ATTEMPTS`	5	Wrong attempts per code
`MFA_RECOVERY_CODE_COUNT`	8	Recovery codes issued
`AUTH_BOOTSTRAP_MAX_ATTEMPTS`, `AUTH_BOOTSTRAP_RETRY_DELAY_SECONDS`	20, 1.5	Retries while waiting for the database at start-up

URLs

Variable	Purpose
`APP_BASE_URL`	Dashboard address; used in password-reset and invitation links
`PUBLIC_PORTAL_BASE_URL`	Portal address; used in confirmation links (defaults to `APP_BASE_URL`)
`PUBLIC_SUBMISSION_CONFIRM_TTL_HOURS`	Confirmation link validity (default 72)
`NEXT_PUBLIC_API_URL`	API address for the Next apps (build time)
`NEXT_PUBLIC_DEFAULT_TENANT_SLUG`	Pre-fills Tenant ID on the sign-in page (build time). Useful for single-organisation installs
`BACKEND_ADMIN_BASE_URL`	API address the Overseer server uses
`PORT`	API port (8000)

Email (SMTP)

Variable	Default	Purpose
`SMTP_HOST`	empty	Empty = no email; messages are written to the API log
`SMTP_PORT`	587
`SMTP_USERNAME`, `SMTP_PASSWORD`	–
`SMTP_FROM`	`orbit@localhost`	From address
`SMTP_USE_TLS`	`true`

Emails Orbit sends: password reset, two-step codes, invitations, portal submission confirmations, and reports (manual and scheduled). Report emailing returns Email delivery is not configured (SMTP) when SMTP is empty.

Integrations

Variable	Purpose
`PLACEKIT_API_KEY`	Platform-default address-search key (tenants can override it)
`NEXT_PUBLIC_PLACEKIT_API_KEY`, `NEXT_PUBLIC_PLACEKIT_COUNTRIES`	Client-side PlaceKit key and countries (e.g. `ca`) (build time)

Worker

Variable	Default	Purpose
`WORKER_POLL_INTERVAL_SECONDS`	5	Loop tick, and how often pending imports are claimed
`WORKER_SCHEMA_POLL_INTERVAL`	60	How often the active-tenant list is refreshed
`WORKER_REMINDER_INTERVAL_SECONDS`	60	Reminder generation (0 disables)
`WORKER_SCHEDULE_INTERVAL_SECONDS`	60	Report schedule executor (0 disables)
`WORKER_CLEANUP_INTERVAL_SECONDS`	3600	Expired portal submission cleanup (0 disables)

Misc

Variable	Default	Purpose
`cors_origin`	`*`	Allowed origins (comma list) for `/v1/` and `/api/`
`cors_supports_credentials`	`false`
`debug_mode`	`false`	Verbose errors
`buildBar` / `GIT_BRANCH`, `NEXT_PUBLIC_GIT_BRANCH`	`dev`	Build label shown in the sidebar and `/ping`
`appname`	`Orbit`	Product name in emails