Environment Variables

This page documents the environment variables that operators set when self-hosting Lombok. It is a practical deployment guide, not an exhaustive, auto-generated reference: it covers the variables that are clearly part of the supported deployment and demo flows, and flags the ones that are development-only or internal.

If a variable is not listed here, treat it as internal or unsupported for self-hosting unless a maintainer tells you otherwise.

At a glance

The minimum an operator needs to start a Lombok instance is:

A platform host (PLATFORM_HOST) — required; the app refuses to start without it.
Database connection details (DB_*).
Auth secrets (AUTH_JWT_SECRET, plus an email-verification secret).

Everything else has sensible defaults or is optional.

Platform host, URL & runtime

These define how the platform identifies itself and how it builds the public URLs it advertises to clients and its workers.

Variable	Required	Default	Description
`PLATFORM_HOST`	Yes	—	Public hostname of the instance (e.g. `lombok.example.com`). The container exits on startup if this is unset.
`PLATFORM_HTTPS`	No	`true`	Whether the platform’s public URL uses `https`. Set to `false` for plain-HTTP setups such as local demos.
`PLATFORM_PORT`	No	unset	Public port to advertise in generated URLs. Leave unset to use the protocol default.
`INITIAL_USER`	No	unset	Username of the initial user created on first startup.
`LOG_LEVEL`	No	`log`	Minimum log level for the backend (for example `debug`, `log`, `warn`, `error`).

[!NOTE] PLATFORM_HOST, PLATFORM_HTTPS, and PLATFORM_PORT together determine the base URL the platform uses for itself. Set them to match how users actually reach the instance.

Database

Lombok uses PostgreSQL. There are two deployment shapes:

External database — you run Postgres separately and point Lombok at it
Embedded database — the standalone image bundles Postgres and manages it for you

Variable	Required	Default	Description
`DB_HOST`	Yes (external)	—	Database host. Required for external Postgres deployments. Must not be set when `EMBEDDED_POSTGRES=true`.
`DB_PORT`	Yes (external)	—	Database port. Required for external Postgres deployments. Must not be set when `EMBEDDED_POSTGRES=true`.
`DB_USER`	Yes	—	Database user.
`DB_PASSWORD`	Yes	—	Database password.
`DB_NAME`	Yes	—	Database name.
`EMBEDDED_POSTGRES`	No	`false`	When `true`, the container runs and manages its own bundled Postgres.
`RUN_MIGRATIONS`	No	`false`	When `true`, runs pending database migrations on startup.
`CREATE_DATABASE`	No	`false`	When `true`, creates the database and user on startup if missing.
`LOG_QUERIES`	No	`false`	When `true`, logs SQL queries. Useful for debugging, noisy in normal operation.

[!NOTE] For a first deployment against a fresh database you will often set both CREATE_DATABASE=true and RUN_MIGRATIONS=true, as the demo compose files do.

Authentication & secrets

These secure user sessions and email verification. Use strong, random values in any real deployment — the demo files ship with placeholders that must be replaced.

Variable	Required	Default	Description
`AUTH_JWT_SECRET`	Yes	—	Secret used to sign authentication tokens.
`AUTH_EMAIL_JWT_ALGORITHM`	No	`HS`	Algorithm family for email-verification tokens: `HS` or `RS`.
`AUTH_EMAIL_VERIFICATION_JWT_SECRET`	Conditional	—	Required when `AUTH_EMAIL_JWT_ALGORITHM=HS`.
`AUTH_EMAIL_VERIFICATION_JWT_PUBLIC_KEY`	Conditional	—	Required when `AUTH_EMAIL_JWT_ALGORITHM=RS`.
`AUTH_EMAIL_VERIFICATION_JWT_PRIVATE_KEY`	Conditional	—	Required when `AUTH_EMAIL_JWT_ALGORITHM=RS`.

[!NOTE] The default algorithm is HS, so most deployments only need AUTH_JWT_SECRET and AUTH_EMAIL_VERIFICATION_JWT_SECRET.

Object storage

Object storage (S3-compatible buckets, MinIO, and similar providers) is not configured through operator environment variables in a normal production deployment. Storage is configured at runtime by an administrator through the application’s storage-provision settings.

The DEV_S3_* variables you may see in the repo are for local development only.

Advanced / core-worker options

These control embedded-worker and runtime internals. Most operators do not need to set them; they are listed here only so they are not mistaken for required configuration.

Variable	Default	Description
`INIT_EVENT_JOBS`	`false`	Initialize event jobs on startup.
`DISABLE_CORE_WORKER`	`false`	Disable the embedded core worker.
`PRINT_CORE_WORKER_OUTPUT`	`false`	Print core-worker output to logs.
`PRINT_CORE_WORKER_NSJAIL_VERBOSE_OUTPUT`	`false`	Verbose nsjail output for the core worker.
`APP_USER`	`bun`	OS user the backend process runs as inside the container.
`APP_UI_HOST`	`http://127.0.0.1:3001`	Internal upstream the bundled NGINX proxies the UI to.

[!NOTE] Some demo compose files reference additional flags that do not currently map cleanly to variables read by the application. They are intentionally not documented here as supported operator configuration.

Development-only variables

The following variables are for local development and are not intended for operators of a self-hosted instance:

PGDATA_DIR, MINIO_DATA_DIR
DOCKER_HOST_CONFIG
DEV_S3_ACCESS_KEY_ID, DEV_S3_SECRET_ACCESS_KEY, DEV_S3_BUCKET_NAME, DEV_S3_PREFIX, DEV_S3_REGION, DEV_S3_ENDPOINT, DEV_S3_LABEL
DEV_SEED_FILE

See DEVELOPMENT.md in the application repository for the dev workflow.