Deployment configuration
Load self-hosted configuration with explicit precedence, secret files, validation, and persistence.
Deployment configuration defines installation identity, persistence, transport, and independently deployed executors. Organization policies cannot override a server's database, encryption key, or trusted proxy boundary.
Configure guard.env in the verified release directory on the management host. Inspect effective non-secret values at Installation → Configuration → Effective configuration. The inventory is split by consumer:
- Server and persistence: API, database, TLS, storage, session identity, bundle inputs.
- Workers and connections: scanning, retention, feed sync, SOC, and DDoS Connector.
- Agents and gateways: executor identity, queues, listeners, and management transport.
Parsing and precedence
Use the configuration source for the process you are changing:
| Configuration | Which value applies |
|---|---|
| Server or worker | Explicit process settings override the release bundle's defaults |
| Agent or gateway | Environment values override matching supported fields supplied by enrollment |
| Organization policy | Console settings control protection decisions; they cannot change an executor's identity |
| Bundle input | Compose consumes the value; it is not a daemon runtime setting |
Value syntax and validation
Omitting an optional setting selects its documented default. Omitting a required setting prevents its consumer from starting. Empty strings count as omitted.
| Type | Accepted input |
|---|---|
| Boolean | Exactly true or false |
| Integer | Decimal notation within the entry's inclusive bounds |
| URL | The scheme and format specified by the entry |
| List | Comma-separated entries; whitespace is trimmed and empty members are rejected |
Unknown variables in a process's documented GUARD_ family, invalid values, and conflicting settings prevent that process from starting. Values are not coerced or clamped.
When changes take effect
Processes read these settings at startup. Restart a setting's named consumer after changing its environment or mounted secret file. A changed state path points the process at a different location; it does not move data from the previous path.
Bootstrap settings initialize a new organization. To change retention or authentication for an existing organization, use its console settings; changing bootstrap values and restarting does not update those policies.
Secret loading
For entries offering raw and _FILE forms, configure exactly one. Each _FILE setting names a readable UTF-8 file containing one secret; one trailing newline is stripped. Supplying both forms, an empty required secret, or an unreadable file rejects startup. File-only encryption and identity settings do not have an implicit raw-value equivalent.
Use the release's secret-generation workflow. Keep deployment configuration readable only by the installation operator. This example assumes the named secrets already exist as service-readable mounts:
GUARD_RELEASE=2025.11
GUARD_PUBLIC_URL=https://guard.example.com
GUARD_DATABASE_URL_FILE=/run/secrets/guard-database-url
GUARD_SESSION_SECRET_FILE=/run/secrets/guard-session-secret
GUARD_ENCRYPTION_KEY_FILE=/run/secrets/guard-encryption-key
GUARD_LICENSE_FILE=/run/secrets/guard-license
GUARD_STATE_DIR=/var/lib/guard
GUARD_TLS_MODE=proxy
GUARD_PUBLISHED_ADDRESS=127.0.0.1
GUARD_PUBLISHED_PORT=8080
GUARD_EVIDENCE_RETENTION_DAYS=30Use the actual release supplied to the installation. A 30-day evidence example is a deployment choice, not a substitute for the 13-month alert/log retention policy.
Apply and recover
From the release directory on the management host, run docker compose --env-file guard.env config --quiet before restarting services. After restart, check Installation → Health for readiness and Installation → Configuration → Effective configuration for the applied non-secret values. Resume jobs only after the affected service is ready. Replicas sharing an identity or encryption key must use the same values.
If startup fails, restore the previous validated configuration and its secret mounts, then restart the affected service. Keep the original encryption key: a new key cannot decrypt credentials stored under the old one. Use backup recovery if required state or keys are missing.
Outbound proxies
The bundle passes HTTPS_PROXY, HTTP_PROXY, and NO_PROXY to enabled outbound HTTP consumers. Omission selects direct connections. Set NO_PROXY for private destinations that must connect directly. These variables do not authorize incoming forwarded headers; that boundary uses GUARD_TRUSTED_PROXY_CIDRS in the server settings.