Install & configure / Configuration reference

Configuration reference

Jangka is configured entirely with environment variables. Settings that change at runtime, such as LLM providers, SSO and permissions, live in the database and are managed under Admin in the app.

With the release compose file, MASTER_KEY, PUBLIC_URL and JANGKA_VERSION (the image tag) come from .env. Add any other variable under app.environment in docker-compose.yml, then run docker compose up -d to recreate the container.

Required

Variable	Format	Notes
`DATABASE_URL`	`postgres://user:pass@host:5432/db`	Also accepts `postgresql://`. Postgres 18 or later.
`MASTER_KEY`	Base64, decoding to exactly 32 bytes	Generate with `openssl rand -base64 32`. Encrypts stored LLM API keys and OIDC client secrets (AES-256-GCM).
`PUBLIC_URL`	`http://` or `https://` URL	The address people open. Used for session cookies, the CSRF origin check and OIDC redirect URIs. A trailing slash is removed.

Optional

Variable	Default	Notes
`PORT`	`3000`	Port the app listens on inside the container, 1 to 65535.
`APP_ROLE`	`all`	`api` serves HTTP only, `worker` runs export and diagram jobs only, `all` does both in one process. See Run a separate worker.
`LOG_LEVEL`	`info`	`fatal`, `error`, `warn`, `info`, `debug` or `trace`. Logs are JSON on stdout.
`SESSION_TTL_DAYS`	`30`	Rolling session lifetime in days, 1 to 365. Each request extends it.
`TRUST_PROXY`	`false`	Set to `true` when exactly one reverse proxy sits in front of Jangka. Client IPs, used for login rate limits and the audit log, then come from `X-Forwarded-For`. See Reverse proxy & TLS.
`FORCE_PASSWORD_LOGIN`	`false`	Turns password login back on when SSO is misconfigured and nobody can sign in. Unset it once SSO works again. See Troubleshooting.
`ENABLE_FAKE_LLM`	`false`	Offers a deterministic fake LLM provider. For development and tests only.

Boolean variables take true or false.

Validation at startup

Jangka checks every variable before it connects to the database. If one is missing or invalid, it prints which one and why, then exits:

Invalid environment:
MASTER_KEY: must decode to 32 bytes (openssl rand -base64 32)
PUBLIC_URL: must be an http(s) URL

The message names the variable and the rule, never the value, so secrets don't end up in logs. The container stops; check docker compose logs app.