Server and persistence settings
Reference API, database, TLS, evidence storage, licensing, and Compose inputs.
Server settings configure the API and shared persistence. All entries follow loading and restart rules; invalid configuration rejects startup before normal request serving.
API and shared identity
These variables configure the API listener, shared identity, and license:
| Variable | Consumer | Default or requirement | Type, bounds, and dependencies |
|---|---|---|---|
GUARD_PUBLIC_URL | API, worker | Required | Absolute HTTPS origin without path, query, or fragment; callback and link origin |
GUARD_HTTP_LISTEN | API | 0.0.0.0:8080 | Host and port; port 1–65535; bind on a private deployment network |
GUARD_TLS_MODE | API | proxy | proxy or direct; proxy mode requires trusted HTTPS termination |
GUARD_TLS_CERT_FILE | API | Required for direct | Readable PEM certificate chain; forbidden in proxy mode |
GUARD_TLS_KEY_FILE | API | Required for direct | Readable matching private key; file only; forbidden in proxy mode |
GUARD_TRUSTED_PROXY_CIDRS | API | Omitted: trust none | Comma-separated valid CIDRs; only these peers can supply forwarded client identity |
GUARD_SESSION_SECRET | API | One source required | Secret containing at least 32 bytes; shared across replicas |
GUARD_SESSION_SECRET_FILE | API | Alternative to raw source | Mounted session-secret value; mutually exclusive with raw form |
GUARD_ENCRYPTION_KEY_FILE | API, worker | Required | File containing a 32-byte base64-encoded key; no raw variant; protects retained credentials |
GUARD_LICENSE_FILE | API, worker | Required | Signed installation-bound entitlement file; no raw variant |
GUARD_LOG_LEVEL | API, worker | info | error, warn, info, or debug; logs must still redact secrets |
Use the procedure for the identity value being changed:
- Public origin: update SSO callbacks and executor management URLs before switching the origin. Test sign-in and executor reporting through the new address.
- Session secret: replacing it invalidates existing console sessions. Keep a working administrator sign-in path for the restart.
- Encryption key: use Installation → Keys → Rotate. Keep the previous key until stored credentials have been re-encrypted and remain readable; replacing the file alone loses access to those credentials.
A license failure appears under Installation → Health and blocks newly admitted licensed work. Existing agents keep their applied local policies. Correct the license mount or entitlement, restart its consumer, and confirm that the license health condition clears before submitting new work.
Database and artifacts
These variables configure database connections and evidence persistence:
| Variable | Consumer | Default or requirement | Type, bounds, and persistence |
|---|---|---|---|
GUARD_DATABASE_URL | API, worker | One source required | PostgreSQL connection URL; TLS parameters follow approved database transport |
GUARD_DATABASE_URL_FILE | API, worker | Alternative to raw source | Mounted complete connection URL; mutual exclusion applies |
GUARD_DATABASE_POOL_SIZE | API, worker, each process | 10 | Integer connections 1–100; total replicas must fit database capacity |
GUARD_STATE_DIR | API, worker | /var/lib/guard | Absolute writable persistent path; mount the same artifact storage for consumers |
GUARD_EVIDENCE_BACKEND | API, worker | filesystem | filesystem or s3; switching does not migrate objects |
GUARD_EVIDENCE_PATH | API, worker | /var/lib/guard/evidence | Absolute persistent path; used only for filesystem backend |
GUARD_S3_ENDPOINT | API, worker | Required for s3 | HTTPS endpoint; forbidden for filesystem backend |
GUARD_S3_BUCKET | API, worker | Required for s3 | Existing bucket name; forbidden for filesystem backend |
GUARD_S3_REGION | API, worker | Required for s3 | Provider signing-region string; no inferred default |
GUARD_S3_CREDENTIALS_FILE | API, worker | Required for s3 | JSON file with access_key_id and secret_access_key; file only |
Limit S3 credentials to the operations needed in the configured evidence prefix. After startup, monitor Installation → Health → Storage for loss of object access; the startup test checks access only at that time.
Back up the database and artifact objects together using Create a recoverable set. Restoring metadata without the referenced objects leaves evidence unavailable.
Bundle inputs
These are consumed by Compose, not read by the API as runtime settings. Validate them through the pinned release bundle.
| Variable | Default or requirement | Behavior |
|---|---|---|
GUARD_RELEASE | Required | Exact available signed release tag; no floating latest |
GUARD_PUBLISHED_ADDRESS | 127.0.0.1 | Host bind IP for the API; exposing another address requires the intended TLS/proxy boundary |
GUARD_PUBLISHED_PORT | 8080 | Integer host port 1–65535 |
POSTGRES_DB | guard | Bundled database bootstrap database name |
POSTGRES_USER | guard | Bundled database bootstrap user name |
POSTGRES_PASSWORD_FILE | Required for bundled database | Readable mounted password; initializes the database account |
POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD_FILE initialize the bundled database on its first start. Changing them later does not rename that database or rotate its account. For an existing database, change the account in PostgreSQL, update Guard's database URL secret, restart the API and workers, and check database readiness under Installation → Health.
Keep the deployment's persistent volumes during a routine restart. Removing them can destroy the database or evidence objects. Use backup recovery before replacing a lost volume.