3 Configuration Reference
TraxrGRC takes its server-level configuration from environment variables
set in .env. Everything else (email, sign-in integrations, sessions,
branding, notifications) is configured in the application under Settings and
stored in the database.
3.1 How values reach the containers
Compose reads .env to fill in docker-compose.yml. Each container receives
only the variables docker-compose.yml lists for it, sometimes under another
name (for example, APP_URL is also passed as AUTH_URL). Setting a
variable in .env that docker-compose.yml does not use changes nothing. To
pass anything else, add it to the service's environment in
docker-compose.override.yml.
After changing .env, apply it with the same command you start the stack
with, for example:
docker compose --profile tls up -d
Compose recreates the containers whose configuration changed; migrate runs
again first.
In the tables below, Required means Compose or the application refuses to start without the value. Secret values must be kept out of tickets, chat and source control.
3.2 Instance settings (.env)
| Variable | Purpose | Default | Required | Secret |
|---|---|---|---|---|
| Core | ||||
APP_URL | The public address of the instance, with scheme and no trailing slash. Used for sign-in redirects (passed to Auth.js as AUTH_URL), links in emails, the SAML service provider addresses, SCIM and MCP addresses, and as an accepted origin for cross-site request checks. Use https://; SAML sign-in requires it. | None | Yes (Compose) | No |
APP_NAME | Product name shown until one is set under Settings → Branding. | GRC Platform | No | No |
AUTH_SECRET | Signs session tokens and the SAML sign-in state. Unless the dedicated keys below are set, it is also the source of the backup signing key and the key that encrypts stored integration secrets. web refuses to start in production when it is missing, shorter than 32 characters, or contains a placeholder (change-me, changeme or dev-secret). | None | Yes (Compose and web) | Yes |
BACKUP_SIGNING_KEY | Source of the key that signs in-app backup snapshots. When empty, the key is derived from AUTH_SECRET. At least 32 characters when set. | Empty | No | Yes |
BACKUP_WORK_DIR | Where in-app backups are assembled before download and unpacked before restore. When empty, backup-work inside the uploads volume, so a finished file moves into place with a rename. Under Compose any other path must be a mounted volume, since the rest of the container is read-only; never point it at /tmp, which is held in memory. See In-app snapshots. | Empty | No | No |
SETTINGS_ENCRYPTION_KEY | Source of the key that encrypts the SMTP password, LDAP bind password, SAML private key and each user's two-step verification secret in the database. When empty, the key is derived from AUTH_SECRET. At least 32 characters when set. Changing it (or AUTH_SECRET while it is empty) makes existing two-step verification enrollments unreadable; see Two-step verification. | Empty | No | Yes |
API_RATE_LIMIT_PER_MINUTE | Requests per minute each API token may make on /api/v1 before it is refused with 429 and a Retry-After header. Counted per web process. 0 turns the limit off; a value that is not a whole number counts as the default. | 600 | No | No |
JOBS_DB_POOL_MAX | Most database connections the job queue opens in each web and worker process, beside the application's own pool (whose size is set with connection_limit in DATABASE_URL). Lower it when many processes share one database server. Any value that is not a whole number of 1 or more counts as the default. | 10 | No | No |
TRUSTED_PROXY_HOPS | How many reverse proxies in front of web append the client address to X-Forwarded-For. The client address is read that many entries from the right. Any value that is not a whole number of 1 or more counts as 1. | 1 | No | No |
| Database | ||||
POSTGRES_PASSWORD | Password of the database owner. Used by db, migrate and the backup scripts. Keep it URL-safe. | None | Yes (Compose) | Yes |
APP_DB_PASSWORD | Password of the application role that web and worker connect as. migrate sets it on every start. Keep it URL-safe. | None | Yes (Compose; migrate requires 16 characters or more) | Yes |
POSTGRES_DB | Database name. | grc | No | No |
POSTGRES_USER | Database owner role name. | grc | No | No |
APP_DB_USER | Application role name: lower-case letters, digits and underscores, starting with a letter or underscore, and different from POSTGRES_USER. | grc_app | No | No |
| First administrator | ||||
INITIAL_ADMIN_EMAIL | Email of the administrator created when the database has no users. | Empty | Only on an empty database | No |
INITIAL_ADMIN_PASSWORD | Its password, 12 characters or more. Remove it after the first sign-in. | Empty | Only on an empty database | Yes |
| HTTPS (bundled Caddy) | ||||
DOMAIN | Host name Caddy serves and requests a certificate for. | Empty | With --profile tls | No |
ACME_EMAIL | Contact address for the certificate authority. | Empty | With --profile tls | No |
| Docker | ||||
COMPOSE_PROJECT_NAME | Project name; prefixes container and volume names. | grc | No | No |
APP_IMAGE | Tag of the application image Compose builds and runs. Leave it unset unless you need a specific name; it must differ between instances on one server. | grc-platform-<COMPOSE_PROJECT_NAME>:latest | No | No |
WEB_BIND | Host address the web port is published on. | 127.0.0.1 | No | No |
WEB_PORT | Host port for web. | 3000 | No | No |
3.3 Set by Compose and the image
These are set for you. Do not override them unless you are changing how the image runs.
| Variable | Set to | Purpose |
|---|---|---|
DATABASE_URL | Built from the database settings above: the application role for web and worker, the owner for migrate. | Database connection for the application and the job queue. |
AUTH_URL | APP_URL | Base address Auth.js builds its redirects from. |
AUTH_TRUST_HOST | true | Tells Auth.js to trust the proxy's host header. |
NODE_ENV | production | Production mode; enables the AUTH_SECRET check and refuses the demo seed. |
PORT, HOSTNAME | 3000, 0.0.0.0 | Where web listens inside its container. |
UPLOAD_DIR | /app/uploads | Where attachments and in-app snapshots are stored (the uploads volume). |
NEXT_TELEMETRY_DISABLED, CHECKPOINT_DISABLE | 1 | Turn off Next.js telemetry and Prisma's update check, so the application makes no unsolicited outbound calls. |
3.4 Operator script variables
These are read by the scripts you run on the server, not by the application.
| Variable | Read by | Purpose | Default |
|---|---|---|---|
BACKUP_AGE_RECIPIENTS | deploy/backup.sh | Path to a file of age public keys. When set, both backup files are encrypted and the plain-text copies removed. | Unset (no encryption) |
BACKUP_AGE_IDENTITY | deploy/restore.sh | Path to the age private key file. Required when restoring .age files. | Unset |
UPDATE_POLL_SECONDS | deploy/update.sh | Seconds between health checks while waiting for web (60 checks in all). | 3 |
GRC_API_TOKEN | scripts/load-bundle.ts | API token used to load a data bundle. See Loading and Importing Data. | Unset |
NODE_EXTRA_CA_CERTS | scripts/load-bundle.ts | Extra CA certificates for reaching an instance with an internal certificate. | Unset |
3.5 Development and demonstration only
Never set these on a production instance.
| Variable | Read by | Purpose |
|---|---|---|
ALLOW_DEMO_SEED | prisma/seed.ts | 1 lets the destructive development seed run when NODE_ENV is production. |
SEED_ADMIN_EMAIL, SEED_ADMIN_PASSWORD | prisma/seed.ts | Administrator account the development seed creates. |
DEMO_ACCOUNTS_FILE | prisma/demo-seed.ts | Where the demonstration seed writes its sign-in accounts (default .demo-accounts). The demonstration seed refuses to run on a database that holds business data. |
3.6 Settings that live in the application
These are not environment variables. Set them in the application:
| Setting | Address | Chapter |
|---|---|---|
| SMTP server, LDAP, SAML single sign-on, SSO only | /settings/integrations | Notifications and Email; Authentication and Single Sign-On |
| Session length, idle timeout, API token lifetime, attachment storage per user, required two-step verification, separation of duties | /settings/security (Sessions) | Authentication and Single Sign-On |
| SCIM provisioning | /settings/provisioning | Authentication and Single Sign-On |
| Product name, logo, color | /settings/branding | Platform Settings |
| Notification templates and the digest schedule | /settings/notifications | Notifications and Email |
| Audit log retention | /settings/audit-log | Audit Log and Evidence Integrity |