Configuration reference

This page lists the variables of the node environment template deploy/env.example and maps each one to its field in src/cluster_erp/config/settings.py. It also lists the variables that the gunicorn configuration and the shell scripts read straight from the environment. Values are never shown: every value cell is the placeholder <value>. Types, defaults, and the readers of every field are in the settings reference.

Scope and source¶

• Defined in: deploy/env.example (the template) and src/cluster_erp/config/settings.py (Settings).
• Count: 88 distinct CLUSTER_ERP_ names in the template, counted with grep -oE "CLUSTER_ERP_[A-Z0-9_]+" deploy/env.example | sort -u. Of these, 77 are value lines, 6 are commented value lines, and 5 appear only inside a comment (the S3 variables). Every one of the 88 maps to a Settings field.

The Template column gives the line in deploy/env.example and whether the line is commented. The Meaning column is one sentence taken from the code comment of the field. The Source column is the field line in settings.py. A variable name is CLUSTER_ERP_ followed by the field name in upper case, read case-insensitively (src/cluster_erp/config/settings.py:64-70).

File format¶

• systemd reads the file with EnvironmentFile=. A line that starts with # or ; is a comment; a # after a value becomes part of the value. A value with spaces, #, or double quotes is wrapped in single quotes (deploy/env.example:6-10).
• The same file works as a .env file for a local run (deploy/env.example:11).
• install.sh refuses to start the service while any value line still contains a <...> placeholder; comment lines are ignored by this check (deploy/install.sh:176-179).
• systemd hands the file to the process only at start, so install.sh restarts instead of reloading when the file is newer than the running service (deploy/install.sh:228-243).

Variables of the template¶

Mode, secrets, and database¶

Template lines 13 to 38: the run mode, the signing and sealing keys, two optional switches, and the database connection.

Files and request size¶

Template lines 40 to 60: where the node stores files, the S3 alternative, and the request body limit.

Signup and domain verification¶

Template lines 62 to 74: the self-service signup door and the mail that verifies domain ownership.

System mailbox¶

Template lines 76 to 90: the relay for mail that the application itself sends.

Backups and archives¶

Template lines 92 to 128: the backup role, the dump folder, retention, encryption, and the optional archives. See backups and restore.

Processes, pool, and proxy¶

Template lines 130 to 148: worker count, connection pool, and trust of the reverse proxy. See service and process manager.

Storage limitation and data-subject requests¶

Template lines 150 to 166: retention windows and the privacy request settings. See scheduled jobs and retention.

Sessions¶

Template lines 168 to 175: session length and the sign-in rate limit.

Signup notice and security contact¶

Template lines 177 to 192: the privacy notice shown at signup and the security.txt document. See security.txt and readiness.

Request cost and analytics¶

Template lines 194 to 208: caching of permissions, list counting, and the analytics summary loop.

First administrator¶

Template lines 210 to 213: where a generated first password is written.

Residency, console origins, and regions¶

Template lines 215 to 244: the node's country, the country nodes, the console origins, and the data regions. See data residency check.

Licensing and operator console¶

Template lines 246 to 269: the licence verification key and the first operator account. See operator console.

Variables read by gunicorn and the scripts¶

These names are read straight from the environment by deploy/gunicorn.conf.py or by shell scripts. The first five are also Settings fields; the others are not.

Constraints and validation¶

Settings validates the loaded values and refuses to start when a rule fails (src/cluster_erp/config/settings.py:737-834):

• Region codes match [a-z0-9-]{2,8}; CLUSTER_ERP_REGION_DB_URLS names only known regions; every non-default region has a server (src/cluster_erp/config/settings.py:748-755).
• CLUSTER_ERP_NODE_COUNTRY is a two-letter code, and CLUSTER_ERP_COUNTRY_NODES lists the node's own country (src/cluster_erp/config/settings.py:756-767).
• CLUSTER_ERP_MULTI_TENANT=true together with CLUSTER_ERP_DEBUG=true is refused (src/cluster_erp/config/settings.py:768-772).
• The secret key must not be the default outside debug mode, must have at least 32 characters, and must not be weak outside debug mode (src/cluster_erp/config/settings.py:773-806).
• In multi-tenant mode the storage, backup, and mail encryption keys are required (src/cluster_erp/config/settings.py:807-823).
• The storage and backup keys must parse as 32 bytes of hex (src/cluster_erp/config/settings.py:824-829).
• CLUSTER_ERP_S3_BUCKET is required with the s3 backend; CLUSTER_ERP_SMTP_FROM_EMAIL is required when CLUSTER_ERP_SMTP_HOST is set (src/cluster_erp/config/settings.py:830-837).
• CLUSTER_ERP_CONSOLE_ORIGINS entries must be https origins, and CLUSTER_ERP_COUNTRY_NODES must be a JSON object of two-letter codes (src/cluster_erp/config/settings.py:867-898).

Discrepancies¶

Terms introduced¶

Related pages¶

• Operations
• Settings reference
• Install a Linux node
• Service and process manager

Verified against commit 92f8051 on 2026-11-13.