.env.example

# Platform checks every variable marked "Checked at start" when its Node.js server starts (src/instrumentation.ts).
# A missing or invalid value stops `npm run dev`, `npm start` and the container with one ConfigError that names every such variable and never its value.
# An empty value counts as unset, and `next build` checks nothing.

# Database
# The values below match the development roles that database-compose.yml creates.
# Checked at start: required, a postgresql:// URL that includes schema=platform.
# The runtime role libredb_platform: DML on schema platform, no DDL.
DATABASE_URL=postgresql://libredb_platform:libredb_platform_dev@localhost:5432/libredb?schema=platform
# Read by the Prisma CLI only (prisma.config.ts), never by the running server.
# The owner role libredb_owner, which runs every migration and owns schema platform.
MIGRATE_DATABASE_URL=postgresql://libredb_owner:libredb_owner_dev@localhost:5432/libredb?schema=platform
# A database libredb_owner owns, for `npm run db:migration` and the drift check `npm run db:drift`, which empty it before every use.
SHADOW_DATABASE_URL=postgresql://libredb_owner:libredb_owner_dev@localhost:5432/libredb_shadow

# Auth
# Checked at start: required, at least 32 characters.
AUTH_SECRET=your-auth-secret-min-32-chars-here
# Optional, set only while rotating AUTH_SECRET: the previous value, so existing sessions stay valid.
# Checked at start: at least 32 characters and different from AUTH_SECRET. Remove it once the session lifetime (8 days) has passed.
# AUTH_SECRET_PREVIOUS=
# Checked at start: the absolute http(s) URL of Platform, required when NODE_ENV is production, which `npm start` and the Docker image set.
AUTH_URL=http://localhost:3000

# Platform
# Checked at start: required, cloud or self-hosted, with no default.
DEPLOYMENT_MODE=cloud
# Read by the seed only: development adds the fake data of prisma/seeds/development.ts, which needs SEED_USER_PASSWORD and SEED_STUDIO_DATABASE_URL.
# The seed refuses development in self-hosted mode, so leave it unset there.
SEED_MODE=development
# Read by the seed only, required in self-hosted mode: the name of the install's one tenant, slug default.
# The first seed sets it, and a later run never renames the tenant.
# PLATFORM_ORGANIZATION_NAME=
BILLING_ENABLED=false
# Checked at start: the absolute http(s) URL of the Studio deployment, required in self-hosted mode.
# The sidebar's Studio link opens it in a new tab; in cloud mode, leave it unset to hide that link.
STUDIO_PUBLIC_URL=http://localhost:3001

# Keycloak
# Checked at start: AUTH_KEYCLOAK_ISSUER, AUTH_KEYCLOAK_ID and AUTH_KEYCLOAK_SECRET are required in self-hosted mode.
# The issuer is the realm URL that Keycloak writes into its tokens, ending in /realms/<realm>, such as https://auth.example.com/realms/libredb.
# The client is the confidential client libredb-platform, whose service account reads users and clients through the Admin API with only the realm-management roles view-users and view-clients.
AUTH_KEYCLOAK_ISSUER=
AUTH_KEYCLOAK_ID=
AUTH_KEYCLOAK_SECRET=
# Checked at start: optional, the base URL of Keycloak inside the install network, such as http://keycloak:8080, for an admin console that the public hostname does not expose.
# Platform then requests its service-account token and calls the Admin API there; when it is unset, it calls the issuer's host with /realms/<realm> rewritten to /admin/realms/<realm>.
KEYCLOAK_ADMIN_URL=
# Checked at start: optional, the flat ID-token claim that carries the client roles of the libredb client, libredb_roles when unset.
# The claim is read by its whole name, so a dot in it never means a nested path.
PLATFORM_ROLE_CLAIM=libredb_roles
# Checked at start: optional, the role in that claim that admits a Keycloak account to Platform, admin when unset.
# A Keycloak account without it lands on /login?error=AccessDenied, and an account whose ID token has no email on /login?error=IdentityClaimMissing.
PLATFORM_ADMIN_ROLE=admin
# Checked at start: optional, the role in that claim of the users who work in Studio, user when unset; it must differ from PLATFORM_ADMIN_ROLE.
STUDIO_USER_ROLE=user
# Checked at start: optional, a positive integer of at most 86400, 300 when unset.
# This many seconds after its last attempt, a Keycloak session asks the Admin API again whether its user still exists, is enabled, holds PLATFORM_ADMIN_ROLE and keeps the Keycloak session it signed in with.
# A session that fails the check ends at that request.
PLATFORM_SESSION_RECHECK_SECONDS=300
# Checked at start: optional, a positive integer of at most 86400, 900 when unset.
# While the Admin API is unreachable or refuses the service account of AUTH_KEYCLOAK_ID, a session stays signed in, marked as degraded, for this many seconds after its last successful check, and then ends.
PLATFORM_RECHECK_GRACE_SECONDS=900
# Checked at start: optional, a positive integer of at most 86400, 60 when unset.
# In self-hosted mode, directory sync lists the members of PLATFORM_ADMIN_ROLE and STUDIO_USER_ROLE this many seconds after its last run ends.
# It writes a session revocation for every member who lost a role, was disabled or was deleted in Keycloak since then, which ends that user's Studio sessions.
DIRECTORY_SYNC_INTERVAL_SEC=60

# Sealed credentials
# Checked at start: Studio's seal public key, the unpadded base64url of a raw 32-byte X25519 public key, required in self-hosted mode and optional in cloud mode.
# Platform seals every connection credential to it and never decrypts, and a key that fails the self-test seal at start stops Platform.
# In self-hosted mode Platform publishes the key's canary in bridge.seal_canary_v1, which Studio opens to prove that it holds the private key.
# The value below is the development key that `node scripts/dev/gen-seal-keypair.mjs` prints together with the keyring of a development Studio.
# Its private key is published, so never seal a real credential to it; an install gets its own key pair from the installer.
BRIDGE_SEAL_PUBLIC_KEY=WULR-dfqAG93r5aNvR9xqMm_AkNbdbimJmSD1YzobyY

# Query audit
# Checked at start: optional, the days a query event is kept, a positive integer of at most 36500, 90 when unset.
# Platform deletes older events every 6 hours; the database keeps every event younger than 7 days whatever the value.
QUERY_LOG_RETENTION_DAYS=90

# License
# Checked at start: required in self-hosted mode, the license token from LibreDB, one line of the form ldl1.<kid>.<payload>.<signature>.
# A token that fails verification never stops the start: the install then adds no user, connection or admin until a valid one is installed, and Platform logs the license state once at start, never the token.
# Cloud mode, which this file runs, ignores it.
# PLATFORM_LICENSE=

# Bearer API
# Checked at start: optional, the audience an access token must carry in aud to call the bearer API under /api/v1.
# Unset turns the API off, and cloud mode, which this file runs, answers 404 API_DISABLED on every /api/v1 route whatever the value.
# PLATFORM_API_AUDIENCE=libredb-platform-api
# Checked at start: required when PLATFORM_API_AUDIENCE is set, the comma-separated client ids whose tokens the API accepts in azp.
# PLATFORM_API_CLIENT_IDS=libredb-mobile

# Logging
LOG_LEVEL=debug
LOG_FORMAT=pretty

# Storage
STORAGE_PROVIDER=LOCAL
STORAGE_LOCAL_PATH=./uploads

# Cloud installs
# Read by the production seed, which creates the first platform admin only when both are set: an email address and a password of at least 8 characters.
# Setting only one stops the seed with a ConfigError. No default password exists, and a later run never changes that admin or its password.
# BOOTSTRAP_ADMIN_EMAIL=
# BOOTSTRAP_ADMIN_PASSWORD=

# Development
# Required by the development seed (SEED_MODE=development): the password of every user it creates.
SEED_USER_PASSWORD=LibreDBPlatform.2026!
# Required by the development seed, and for development only: the libredb_studio URL that database-compose.yml creates.
# The seed inserts its sample query events through bridge.query_events_v1 as libredb_studio, as Studio does; Platform itself never connects as that role.
# The seed seals the credentials of its connections to the development seal key that `node scripts/dev/gen-seal-keypair.mjs` prints, whatever BRIDGE_SEAL_PUBLIC_KEY holds.
SEED_STUDIO_DATABASE_URL=postgresql://libredb_studio:libredb_studio_dev@localhost:5432/libredb