Environment Configuration¶
Trustpoint can be configured through environment variables using a .env file.
Create the file from the provided example:
cp .env.example .env
Unless stated otherwise, all variables are optional.
Startup¶
Variable |
Values / Default |
Description |
|---|---|---|
|
|
Controls whether Trustpoint determines the startup phase automatically, starts the setup wizard, or starts directly in operational mode. |
The container entrypoint records privileged deployment paths and ports in a
root-owned file at /run/trustpoint/deployment.json before starting the web
application. Configure these through the deployment environment. The web
application cannot override these settings through sudo or wizard state.
Wizard handoff files retain their operational.env / operational.pending.env
names but must contain JSON data. Do not shell-source them. Shell assignments,
malformed JSON, and unsupported settings are rejected.
Runtime switching exposes only the --pending and --final sudo actions. Both
select the corresponding deployment-configured file; arbitrary file arguments
are rejected. Wizard values and application environment variables are applied
only after dropping privileges to www-data.
The default application home and uv cache are /run/trustpoint/home and
/run/trustpoint/uv-cache. Overrides require an existing root-controlled parent
directory; these directories cannot be symlinks.
The application code, virtual environment, dependency metadata, and documentation
sources are root-owned and not writable by www-data. Translation catalogs are
compiled during the image build. Writable application paths are limited to
trustpoint/media, trustpoint/collected_static, docker/trustpoint/nginx/tls,
and docs/build, plus separately configured runtime state outside the source tree.
Documentation build locks are stored under MEDIA_ROOT. Mount additional code
or configuration read-only to preserve this boundary.
The privileged boundary has an isolated Linux regression test using real sudo rules and process identities. It replaces service operations with observations, so it does not start Trustpoint or require a database:
docker build -f tests/docker_security/Dockerfile -t trustpoint-runtime-boundary-test .
docker run --rm --network=none trustpoint-runtime-boundary-test
Django signing key¶
Initialize the deployment’s key once with sudo python3 docker/init_secret.py.
The helper creates secrets/django_secret_key on the host with owner root, group
33 (www-data in the image), and mode 0440. Existing keys are never overwritten
or silently repaired. Compose mounts the file read-only in web and worker.
Variable |
Default |
Description |
|---|---|---|
|
|
Host source file for the Compose secret. |
|
|
Mounted path read by production Django settings. |
|
|
Application image used by web and worker. |
|
|
Network name for the standard and worker configurations. |
Production never generates a key and fails if the mounted file is missing,
empty, or unreadable. A separate local-development key is cached under the ignored
var/development/ directory only when running non-Docker development settings.
Keep the host key across upgrades. Import an existing installation’s exact key
with sudo python3 docker/init_secret.py --import-from /path/to/saved-key before
replacing its containers. A conflicting existing destination is left unchanged
and reported as an error. See the Docker deployment guide
for initial installation, updates, and recovery. Importing a Django signing key
does not restore the separate database KEK or HSM state.
Database¶
Variable |
Default |
Description |
|---|---|---|
|
|
PostgreSQL database name. |
|
|
PostgreSQL user. |
|
|
PostgreSQL password. Change for production deployments. |
|
unset |
Path to a mounted database-password secret. Takes precedence over |
|
|
PostgreSQL hostname. |
|
|
PostgreSQL port. |
|
|
Django database backend. |
The setup wizard requires its database password to match either the mounted
DATABASE_PASSWORD_FILE secret or DATABASE_PASSWORD supplied by the deployment.
The operational handoff file stores connection settings and the secret-file path,
but never the password itself. Keep the external credential available to the web
container and workers across restarts. Supply or mount a replacement credential
before applying a password change in the wizard.
TLS and Network Configuration¶
Variable |
Default |
Description |
|---|---|---|
|
|
Comma-separated IPv4 addresses used for TLS SANs, Django |
|
|
Comma-separated IPv6 addresses. |
|
|
Comma-separated DNS names. |
|
|
HTTP port. |
|
|
HTTPS port. |
Outgoing Mail¶
Trustpoint maps the following environment variables to Django’s MAILERS['default'] configuration.
If EMAIL_HOST is not configured, Trustpoint uses Django’s console email backend.
Variable |
Default |
Description |
|---|---|---|
|
|
Sender address used for outgoing email. |
|
unset |
SMTP server. Setting this enables SMTP delivery. |
|
|
SMTP server port. |
|
automatic |
Enable STARTTLS. |
|
automatic |
Enable implicit TLS. |
|
unset |
SMTP username. |
|
unset |
SMTP password. |
|
|
SMTP connection timeout in seconds. |
Security Configuration¶
TP_SECURITY_MODE defines the security baseline. Additional security variables may only make the selected preset more restrictive.
Variable |
Values |
Description |
|---|---|---|
|
|
Selects the security preset. |
|
Integer / |
Minimum allowed RSA key size. |
|
Integer / |
Maximum certificate validity period. |
|
Integer / |
Maximum CRL validity period. |
|
Boolean |
Allow issuance of CA certificates. |
|
Boolean |
Allow local self-signed CA creation ( |
|
Boolean |
Allow importing self-signed CAs. |
|
Boolean |
Allow importing existing private-key credentials. |
|
Comma-separated HMAC names |
Restrict accepted CMP MACs, e.g. |
|
Boolean |
Accept CMP HMAC-SHA1 protection (including the OpenSSL default). Allowed by Lab and Brownfield presets; may be further restricted to false. |
|
Boolean |
Enable the local automatically generated PKI. |
|
Comma-separated list |
Allowed PKI protocols without onboarding. |
|
Comma-separated list |
Allowed onboarding protocols. |
Supported no-onboarding protocols:
CMP_SHARED_SECRET
EST_USERNAME_PASSWORD
MANUAL
REST_USERNAME_PASSWORD
Supported onboarding protocols:
MANUAL
CMP_IDEVID
CMP_SHARED_SECRET
EST_IDEVID
EST_USERNAME_PASSWORD
AOKI
BRSKI
OPC_GDS_PUSH
REST_USERNAME_PASSWORD
AGENT
Boolean values accept true, false, 1, 0, yes, no, on, and off.
Unset security restriction variables inherit the selected preset. Environment restrictions cannot enable functionality that is prohibited by the preset.
If a new security configuration conflicts with existing devices or CAs, the requested change is rejected, the previous valid configuration remains active, and the conflict is logged.
Automatic Setup¶
Automatic setup can be used for automated testing and repeatable deployments.
Variable |
Default |
Description |
|---|---|---|
|
|
Skip the interactive setup wizard and configure Trustpoint from environment variables. |
|
unset |
Superuser username. Required when auto-setup is enabled. |
|
unset |
Superuser password. Required when auto-setup is enabled. |
|
unset |
Optional superuser email address. |
|
|
Inject example devices and certificates for development and demonstration environments. |
When automatic setup is enabled, the TLS certificate is generated using the configured TP_TLS_* values.
Software database KEK (Trustpoint 1.0)¶
Initialize the independent software KEK with sudo python3 docker/init_secret.py --type kek
or provision both secrets using --type all. Compose mounts secrets/trustpoint_software_kek
read-only at /run/secrets/trustpoint_software_kek. Set TRUSTPOINT_SOFTWARE_KEK_HOST_FILE
to change the host source; TRUSTPOINT_SOFTWARE_KEK_FILE selects the application input.
The input must contain exactly 64 hexadecimal characters, without whitespace.
It is never derived from Django’s signing key. Production startup never generates it.
Preserve it separately alongside database backups: losing it may permanently prevent
recovery of encrypted fields. PKCS#11-only deployments use the HSM KEK instead and
must select the documented Compose overrides to omit the software-secret mount.
Pre-1.0 encrypted database migration and key rotation are unsupported.
For local development with DEBUG=True outside Docker, leaving
TRUSTPOINT_SOFTWARE_KEK_FILE unset uses var/development/software_kek. A fresh
backend creates this ignored, developer-owned file atomically with mode 0600;
later commands reuse it. A missing file in an initialized installation is never
regenerated. Explicitly configured files must already exist, even in development.