Configuration

Updated 12 October 2026

With Docker Compose, all production settings live in one private environment file, based on deploy/compose.prod.env.example. Keep it outside the repository checkout with mode 0600, and preserve its passwords, keys and identity settings across upgrades. Changing a key later can invalidate stored state.

Images#

Variable	Purpose
`NIX_IMAGE_REGISTRY`	Optional. Defaults to `ghcr.io/sianachi/nix`. Set `localhost/nix` only for images built on the host
`NIX_IMAGE_TAG`	The full commit SHA of the release for the API, migrator, collaboration and worker images
`NIX_WEB_IMAGE_TAG`	The full commit SHA for the web image
`NIX_WORKER_IMAGE_TAG`	Optional. A different worker image, for a worker-only fix

The release script exports the tags in the shell, which takes precedence over the file, so you do not edit the file per release.

Database#

Variable	Purpose
`NIX_PG_SUPERUSER_PASSWORD`	The PostgreSQL superuser password
`NIX_PG_MIGRATOR_PASSWORD`	The `nix_migrator` password
`NIX_MIGRATOR_CONNECTION_STRING`	Core migrations, as `nix_migrator`
`NIX_CORE_DATABASE_URL`	Core at runtime, as `nix_app`
`NIX_COLLAB_DATABASE_URL`	Collaboration at runtime, as `nix_collab`
`NIX_COLLAB_MIGRATOR_CONNECTION_STRING`	Document migrations, as `nix_migrator`. Used only by the one-shot job

NIX_CORE_DATABASE_URL=Host=postgres;Port=5432;Database=nix;Username=nix_app;Password=<app-password>
NIX_COLLAB_DATABASE_URL=postgresql://nix_collab:<collab-password>@postgres:5432/nix

Internal secrets#

Variable	Purpose
`NIX_INTERNAL_SECRET`	Authenticates internal calls between services
`NIX_PUBLIC_FORMS_SIGNING_KEY`	Signs interactive form links

Generate each with a strong random value, for example openssl rand -base64 48.

RabbitMQ#

Each component has its own broker credential. Use URL-safe values, because Compose builds connection URLs from them.

NIX_RABBITMQ_API_PASSWORD, NIX_RABBITMQ_IMPORT_PASSWORD, NIX_RABBITMQ_EXPORT_PASSWORD, NIX_RABBITMQ_PLUGIN_PASSWORD, NIX_RABBITMQ_CALENDAR_PASSWORD, NIX_RABBITMQ_NOTIFY_PASSWORD, and NIX_RABBITMQ_SITES_PASSWORD when Sites is enabled

To use an external TLS broker instead of the bundled one, set a full amqps:// URL for every role: NIX_RABBITMQ_API_URL, NIX_RABBITMQ_IMPORT_URL, NIX_RABBITMQ_EXPORT_URL, NIX_RABBITMQ_PLUGIN_URL, NIX_RABBITMQ_CALENDAR_URL and NIX_RABBITMQ_NOTIFY_URL.

Object storage#

Variable	Purpose
`NIX_OBJECT_STORE_ENDPOINT`	The S3 endpoint Core and the workers use
`NIX_OBJECT_STORE_PUBLIC_ORIGIN`	The origin browsers use for signed links
`NIX_OBJECT_STORE_REGION`	Defaults to `us-east-1`
`NIX_OBJECT_STORE_BUCKET`	The bucket name
`NIX_OBJECT_STORE_ACCESS_KEY`, `NIX_OBJECT_STORE_SECRET_KEY`	Storage credentials

With the bundled store, set both the endpoint and the public origin to https://<your-domain>; the web container routes the bucket path to the store. The bucket must not be called w, workspaces or launch, because the installed app treats those paths as its own pages.

Variable	Purpose
`NIX_PUBLIC_ORIGIN`	`https://<your-domain>`
`NIX_OIDC_ISSUER`	Your identity provider's issuer URL
`NIX_OIDC_CLIENT_ID`	The OIDC client ID for Nix
`NIX_OIDC_ACCOUNT_URL`	Optional. The provider's self-service account page. Defaults to the Zitadel console

Access tokens#

Nix issues its own short-lived access tokens to browsers, nixctl and personal access tokens.

Variable	Purpose
`NIX_CORE_TOKEN_ISSUER`	Usually `https://<your-domain>`
`NIX_CORE_TOKEN_AUDIENCE`	Usually `nix`
`NIX_CORE_TOKEN_KEY_ID`	A name for the signing key, such as `nix-core-2026-10`
`NIX_CORE_TOKEN_SIGNING_KEY_FILE`	Absolute path to the P-256 private key

openssl ecparam -name prime256v1 -genkey -noout -out core-access-token.pem

Generate the key once and keep it.

Push notifications#

Variable	Purpose
`NIX_PUSH_VAPID_PRIVATE_KEY`	The VAPID private key: 32 raw bytes, base64url, no padding
`NIX_PUSH_VAPID_PUBLIC_KEY`	The matching public key: an uncompressed P-256 point, base64url
`NIX_PUSH_VAPID_SUBJECT`	A `mailto:` or `https:` contact for push services

Generate one key pair for the lifetime of the deployment. Changing it means every device has to subscribe again.

Calendar sync#

Optional. A provider without a client ID and secret is shown as unavailable.

Variable	Purpose
`NIX_CALENDAR_GOOGLE_CLIENT_ID`, `NIX_CALENDAR_GOOGLE_CLIENT_SECRET`	Google OAuth application
`NIX_CALENDAR_MICROSOFT_CLIENT_ID`, `NIX_CALENDAR_MICROSOFT_CLIENT_SECRET`	Microsoft OAuth application
`NIX_CALENDAR_MICROSOFT_TENANT`	Defaults to `common`

https://<your-domain>/auth/calendar/callback/google
https://<your-domain>/auth/calendar/callback/microsoft

Core keeps calendar refresh tokens encrypted with its data-protection keys, which live in the nix-api-data-protection volume. Back that volume up separately from the database. If it is lost, every calendar connection has to be made again.

Tunnel#

Variable	Purpose
`CLOUDFLARE_TUNNEL_TOKEN`	The token for the optional tunnel connector. Set a placeholder if you use your own reverse proxy

Sites#

Optional. Leave these unset and nothing about Sites runs.

Variable	Purpose
`COMPOSE_PROFILES`	Set to `sites` to start the two Sites services
`NIX_SITES_DOMAIN`	The domain sites are served under, as `<slug>.<sites-domain>`. It must not share a registrable domain with `NIX_PUBLIC_ORIGIN`
`NIX_SITES_BUCKET`	The bucket built sites are written to. Defaults to `nix-sites`
`NIX_RABBITMQ_SITES_PASSWORD`	The sites worker's own broker password
`NIX_SITES_READ_ACCESS_KEY`, `NIX_SITES_READ_SECRET_KEY`	The serving process's storage credential. Use a key that can only read the sites bucket where your store supports it
`NIX_SITES_DEFAULT_LABEL_SUFFIX`	Optional. A label suffix for this instance's default hostnames, as `<slug><suffix>.<sites-domain>`, when another deployment shares the sites domain
`NIX_SITES_CLOUDFLARE_API_TOKEN`	Optional. Lets Nix create DNS records and tunnel routes for site hostnames. Needs Zone:Read, DNS:Edit and Cloudflare Tunnel:Edit
`NIX_SITES_CLOUDFLARE_ACCOUNT_ID`, `NIX_SITES_CLOUDFLARE_TUNNEL_ID`	The account and tunnel those routes are added to
`NIX_SITES_CLOUDFLARE_DEFAULT_HOSTNAME_ZONE_ID`	The zone for this instance's default hostnames when a label suffix is set. Never used for custom hostnames

Kubernetes#

The Kubernetes manifests read the same settings from Secrets and ConfigMaps instead of an environment file. deploy/k8s/create-secrets.sh creates the Secrets and lists them as it goes; see Kubernetes. The settings passed to deploy/k8s/deploy.sh are:

Variable	Purpose
`NIX_DEPLOY_TARGET`	Must be `kubernetes`, or the script refuses to run
`REGISTRY`, `TAG`	Where the images are and the full commit SHA to run
`DOMAIN`	The app's domain, also used for `auth.` and for sites
`OIDC_CLIENT_ID`	The Nix application's client ID at the identity provider
`OIDC_ISSUER`	Optional. Defaults to `https://auth.<DOMAIN>`
`NIX_TEMPLATE_BOOT_ENABLED`	`false` on a first install; `true` requires the `TEMPLATE_BOOT_*` settings
`NIX_SITES_REQUIRE_OPERATOR_APPROVAL`	Defaults to `true`
`SITES_FOREIGN_LABEL_SUFFIX`	Defaults to `-home`; set it empty when no other deployment shares the domain
`POD_CIDR`	Defaults to `10.42.0.0/16`

The inputs to create-secrets.sh include DOMAIN, the NIX_OBJECT_STORE_* and NIX_CALENDAR_* values, NIX_SITES_BUCKET and NIX_SITES_READ_*, the optional NIX_SITES_CLOUDFLARE_* values, NIX_PUSH_VAPID_*, NIX_ORIGIN_TLS_CERT_FILE, NIX_ORIGIN_TLS_KEY_FILE, and NIX_ZITADEL_ADMIN_USERNAME and NIX_ZITADEL_ADMIN_PASSWORD. Passwords for the database, broker, internal secret and signing keys are generated.