Configuration reference

Marolum 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 Marolum 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 (Business and Enterprise)

Business allows one OIDC or SAML connection; additional connections and trusted proxy require 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). MAROLUM_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.

Email notifications

Email notification channels stay inactive until the deployment names an email provider. Channels, recipients, and rules are administered on the console's Notifications page. Adding a recipient emails that address a one-time verification code; notifications go only to verified recipients.

Both TLS modes require TLS 1.2 or later. STARTTLS is required rather than opportunistic: a server that does not offer it is refused. none is for a relay on the same machine, so the host must be localhost, 127.0.0.1, or ::1. Keep the password file outside the data directory and out of images, command arguments, logs, and exports.

Email settings fail closed without stopping startup. An invalid value leaves the provider unconfigured with the reason invalid-configuration: nothing is sent, the startup log records one line without the values, and the Notifications page shows the reason. Marolum never applies part of an email configuration.

Messages are plain text with no attachments. Connections use 10-second connect and greeting timeouts and a 20-second socket timeout. Set MAROLUM_PUBLIC_ORIGIN to make the console link in each message absolute; without it, messages name the console path instead.

managed takes no SMTP settings. Dekglas-managed email is not yet available: even an entitled deployment that selects it reports the provider unavailable and sends nothing. Use your own SMTP server.

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)

MAROLUM_LOCAL_ADMIN_PASSWORD_FILE=/run/marolum/admin-password   # remove after first sign-in
MAROLUM_BACKENDS_FILE=/run/marolum/backends.json
MAROLUM_PUBLIC_ORIGIN=https://marolum.example.com

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

PostgreSQL, one replica (Business)

MAROLUM_BACKENDS_FILE=/run/marolum/backends.json
MAROLUM_POSTGRES_URL_FILE=/run/marolum/postgres-url
MAROLUM_PUBLIC_ORIGIN=https://marolum.example.com
MAROLUM_LICENSING_SERVICE_URL=https://licensing.dekglas.com

PostgreSQL, three replicas (Enterprise)

MAROLUM_BACKENDS_FILE=/run/marolum/backends.json
MAROLUM_POSTGRES_URL_FILE=/run/marolum/postgres-url
MAROLUM_PUBLIC_ORIGIN=https://marolum.example.com
MAROLUM_LICENSING_SERVICE_URL=https://licensing.dekglas.com
MAROLUM_REPLICAS_MAX=3
MAROLUM_POSTGRES_POOL_MAX=2
MAROLUM_POSTGRES_CONNECTION_HEADROOM=10
MAROLUM_OIDC_CORP_IDP_CLIENT_ID=…
MAROLUM_OIDC_CORP_IDP_CLIENT_SECRET=…

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

Loopback evaluation on a laptop

MAROLUM_LOCAL_ADMIN_PASSWORD_FILE=/run/marolum/admin-password
MAROLUM_BACKENDS_FILE=/run/marolum/backends.json
MAROLUM_ALLOW_HTTP=true
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…
AWS_SESSION_TOKEN=…

This is the Quickstart shape and nothing else.

Earlier environment names

Earlier builds used LUMAFT_* environment variables. Configure the documented MAROLUM_* names before upgrading; do not rely on the temporary compatibility adapter. Keep the existing SQLite file's exact path in MAROLUM_SQLITE_PATH (including /data/dekglas.db if that is your installation's file). A product rename is not a database migration.