Configuration
Configuration layers, environment variables, storage, and precedence.
Status stores configuration in five layers. The table identifies each layer's settings, storage location, and editor.
| Layer | Holds | Stored in | Changed by |
|---|---|---|---|
| 0 — Bootstrap | How to reach the database | Process environment, or $STATUS_STATE_DIR/database.json | Operator at deploy time, or the setup wizard |
| 1 — Instance secrets | Session secret, encryption key ring | $STATUS_STATE_DIR/secrets.json | Generated by the app |
| 2 — Instance settings | Public URL, identity provider, worker token, mail relay, profile storage | Database | Setup wizard, then Settings → Instance |
| 3 — Organization | Retention policy, default timezone, name and slug | Database | Settings → Organization |
| 4 — User | Display name, personal timezone, theme | Database | Settings → Profile |
Layers 0 and 1 must exist before the database can be read. A self-hosted first
run can omit the environment entirely: the wizard writes database.json into
the state directory after a successful connection test. Everything above layer 1
lives in the database and changes without a restart.
Layer 0 — bootstrap environment
The only environment Status requires in cloud mode. Self-hosted installs may
leave DATABASE_URL unset and enter the connection in /setup. It is read
synchronously at startup.
| Variable | Required | Default | Meaning |
|---|---|---|---|
DATABASE_URL | Cloud: yes. Self-hosted: no | — | PostgreSQL connection string. When unset, Status reads $STATUS_STATE_DIR/database.json written by the setup wizard. |
DATABASE_SSL | No | disable | disable or require. Must be require in production unless DATABASE_ALLOW_PLAINTEXT=true. |
DATABASE_ALLOW_PLAINTEXT | No | unset | Set to true to acknowledge a production database reachable only over a private network. |
STATUS_STATE_DIR | No | ./.status-state | Directory holding the instance secrets, the setup token, and a wizard-saved database.json. /var/lib/status in the Docker image. |
DEPLOYMENT_MODE | No | self-hosted | self-hosted or cloud. See below. |
STATUS_AUTO_MIGRATE | No | unset | true applies pending migrations on server startup. Set in the Docker image. |
Deployment mode
DEPLOYMENT_MODE changes two things and nothing else:
- Organization creation.
self-hostedcreates one organization in the setup wizard and joins the first user to it.cloudcreates organizations through signup instead. - Auth provider configuration.
self-hostedconfigures password auth, SSO, or both in the wizard and in Settings → Instance.cloudpins SSO from the environment, and the instance settings surface is hidden.
The setup wizard runs in both modes. Cloud installations skip these steps.
Layer 1 — instance secrets
On first start Status writes $STATUS_STATE_DIR/secrets.json with mode 0600:
{
"version": 1,
"sessionSecret": "...",
"encryptionKeys": [{ "id": "v2", "key": "<32-byte base64>" }]
}This directory must be on persistent storage. The key ring decrypts every
stored monitor and notification credential. If it is lost, those credentials
cannot be recovered and must be re-entered. A wizard-saved database connection
lives here too, as database.json, unless DATABASE_URL is pinned from the
environment.
Two environment variables still override this layer, so existing deployments and cloud installs keep working unchanged:
| Variable | Overrides |
|---|---|
NEXTAUTH_SECRET | sessionSecret |
MONITOR_ENCRYPTION_KEYS | encryptionKeys (comma-separated, current-first id:base64) |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY | vapid — the browser-push signing pair, generated on first use |
When the secrets file is created on an instance that previously ran with
NEXTAUTH_SECRET, the derived legacy key is carried forward into the ring
after the new current key, so credentials encrypted under the old scheme still
decrypt. Retain that legacy key while stored credentials still depend on it.
See Monitor credentials and secrets.
Layer 2 — instance settings
One record, written by the setup wizard and edited in Settings → Instance.
| Setting | Environment override |
|---|---|
| Instance name | — |
| Public URL | NEXTAUTH_URL |
| SSO issuer / client ID / client secret | AUTHENTIK_ISSUER, AUTHENTIK_CLIENT_ID, AUTHENTIK_CLIENT_SECRET |
| SAML 2.0 SSO | SAML_ENTRY_POINT, SAML_IDP_ISSUER, SAML_IDP_CERTIFICATE, SAML_SP_ENTITY_ID, SAML_EMAIL_ATTRIBUTE, SAML_NAME_ATTRIBUTE |
| Email/password sign-in | — |
| Trust proxy headers | TRUST_PROXY_HEADERS |
| Shared worker token | MONITOR_WORKER_TOKEN |
| Mail relay | SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_ADDRESS, SMTP_FROM_NAME, SMTP_REJECT_UNAUTHORIZED |
| Profile storage | STATUS_STORAGE_DRIVER, STATUS_STORAGE_LOCAL_DIR, STATUS_S3_BUCKET, STATUS_S3_REGION, STATUS_S3_ENDPOINT, STATUS_S3_PREFIX, STATUS_S3_FORCE_PATH_STYLE |
| Telemetry | — |
Environment values override database values. Use environment configuration to pin deployment settings. An SSO provider configured this way appears read-only in the settings UI.
Secrets in this layer stay write-only in the UI: the SSO client secret, SAML IdP signing certificate, and S3 credentials are encrypted at rest and never sent back to the browser. The shared worker token is stored as a fingerprint, so it is revealed exactly once—when it is generated. Individual passwords are salted hashes on user records; reset tokens expire after one hour.
S3 static credentials entered in the wizard are encrypted with the same key
ring. Leaving them blank uses the AWS SDK credential chain, including workload
or instance IAM roles. Uploaded profile pictures are always private and are
served through an organization-authorized application endpoint. Existing
installs with no explicit setting use $STATUS_STATE_DIR/profile-images.
Layer 3 — organization
Every monitor, incident, status page, tag, folder, and worker agent belongs to an organization. Organization settings are tenant policy:
- Name and URL slug
monitorResultRetentionDays: how long check results are kept- Default timezone — used to enter and evaluate maintenance windows
Layer 4 — user
Personal preferences only: display name, unique mention handle, avatar, job title, pronouns, bio, personal timezone, and console theme. A user's timezone affects how timestamps are displayed to them; it does not affect maintenance-window evaluation, which uses the organization default.
Related documentation
- Self-hosting: installing and upgrading
- Monitor credentials and secrets: the key ring
- Data retention: the retention job