Configuration reference

Lumaft is configured entirely through environment variables. Secrets — the bootstrap password, backend definitions, database URLs, keys — are read from files whose paths those variables name, never from the variables themselves.

How configuration behaves

• Read once at startup. Changing any setting or file requires a restart. There is no live reload and no configuration API.
• Fail closed. An invalid value, a missing file, or a file that breaks the rules below stops startup with one sanitized log line. Nothing starts in a degraded mode.
• Booleans are exact. true or false, lowercase. 1, yes, and TRUE are refused.
• Paths are literal. Absolute, already normalized; no ~, no variables, no trailing slash.
• Every replica is identical. On Enterprise PostgreSQL, all replicas start from the same settings and files.

File rules

Every file a setting names must:

• be a regular file reached without following a final symlink, with a non-symlinked parent;
• have a parent directory that is not writable by group or others (mode 0700 is the norm);
• not be writable by group or others (mode 0600);
• be readable by UID 1000, the node user the container runs as.

Kubernetes Secret volumes and other projected mounts materialize files as symlinks and are rejected. Write files into a task-local volume from an init step instead; every environment guide shows the pattern.

Core

Bootstrap administrator

See Users and permissions.

Backends

Backend credentials are not Lumaft settings. The AWS SDK's default credential chain applies:

NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem adds a private CA for an S3-compatible endpoint or a corporate proxy certificate. Certificate verification cannot be disabled.

Database

Exactly one database source applies. Setting more than one refuses startup.

A SQLite installation adopted to PostgreSQL through the console keeps a UI-managed provider file in the data directory instead; do not also set a PostgreSQL variable. See PostgreSQL operations.

Replicas (Enterprise, PostgreSQL only)

Startup refuses with pool-topology-exceeds-server unless replicas × (pool + 2) + headroom ≤ max_connections − reserved, and with multi-replica-requires-postgresql when the ceiling is above 1 on SQLite.

Schema upgrades

See Gated migrations.

Licensing

An installation with none of these runs as Community.

On SQLite the two connected settings are set together or not at all; a non-HTTPS URL refuses startup. Activation itself happens in Administration → Licensing.

Federated sign-in (Enterprise)

Providers are registered in the console; their protocol settings are environment variables. <KEY> is the issuer key uppercased with dashes changed to underscores (corp-idp → CORP_IDP). LUMAFT_PUBLIC_ORIGIN is required for OIDC and SAML.

Walkthroughs for common providers: Federated identity.

Optional capture and audit

The three audit-sink settings are set together on every replica or not at all. The URL and id are bound in the database on first configured startup and cannot be changed in this version; rotating the secret keeps the binding.

Health and diagnostics endpoints

Diagnostic reports are per process and reset on restart. None contains backend identity or provider payloads.

Worked examples

SQLite on a VM (Community)

LUMAFT_LOCAL_ADMIN_PASSWORD_FILE=/run/lumaft/admin-password   # remove after first sign-in
LUMAFT_BACKENDS_FILE=/run/lumaft/backends.json
LUMAFT_PUBLIC_ORIGIN=https://lumaft.example.com

Credentials come from the instance profile; the database is at the default /data/lumaft.db.

PostgreSQL, one replica (Business)

LUMAFT_BACKENDS_FILE=/run/lumaft/backends.json
LUMAFT_POSTGRES_URL_FILE=/run/lumaft/postgres-url
LUMAFT_PUBLIC_ORIGIN=https://lumaft.example.com
LUMAFT_LICENSING_SERVICE_URL=https://licensing.dekglas.com

PostgreSQL, three replicas (Enterprise)

LUMAFT_BACKENDS_FILE=/run/lumaft/backends.json
LUMAFT_POSTGRES_URL_FILE=/run/lumaft/postgres-url
LUMAFT_PUBLIC_ORIGIN=https://lumaft.example.com
LUMAFT_LICENSING_SERVICE_URL=https://licensing.dekglas.com
LUMAFT_REPLICAS_MAX=3
LUMAFT_POSTGRES_POOL_MAX=2
LUMAFT_POSTGRES_CONNECTION_HEADROOM=10
LUMAFT_OIDC_CORP_IDP_CLIENT_ID=…
LUMAFT_OIDC_CORP_IDP_CLIENT_SECRET=…

Requires 3 × (2 + 2) + 10 = 22 non-reserved PostgreSQL connections.

Loopback evaluation on a laptop

LUMAFT_LOCAL_ADMIN_PASSWORD_FILE=/run/lumaft/admin-password
LUMAFT_BACKENDS_FILE=/run/lumaft/backends.json
LUMAFT_ALLOW_HTTP=true
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…
AWS_SESSION_TOKEN=…

This is the Quickstart shape and nothing else.