Environment Variables
CompassDocs is configured entirely through environment variables (via a .env
file locally, or your platform’s environment settings). Only DATABASE_URL is
required.
Database
Section titled “Database”| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL |
✅ | — | PostgreSQL connection string, e.g. postgres://user:pass@host:5432/compassdocs. |
DATABASE_SSL |
auto | require forces TLS; disable turns it off. When unset, SSL is enabled for non-local hosts and off for localhost/127.0.0.1. |
|
DATABASE_POOL_MAX |
5 |
Maximum connections in the pool. Keep modest on serverless. | |
DATABASE_POOL_WAIT_MS |
30000 |
How long, in milliseconds, a request waits for a free connection before it fails (1.19.0). Before 1.19.0 it waited forever, so one stuck connection could stall every request. |
Initial admin account
Section titled “Initial admin account”Optional. Without them, the first visit to a fresh install opens the
setup wizard, which creates the admin account in the browser (see
First-run setup). With
COMPASSDOCS_ADMIN_PASSWORD set, the admin is created on first launch
instead, only while the users table is empty, and the wizard is skipped.
| Variable | Default | Description |
|---|---|---|
COMPASSDOCS_ADMIN_USER |
admin |
Username for the bootstrap admin (used only when COMPASSDOCS_ADMIN_PASSWORD is set). Its email is set to <username>@compassdocs.local; change it under your profile. |
COMPASSDOCS_ADMIN_PASSWORD |
— | Password for the bootstrap admin. When set, the account is created ready to use, with no forced password change. When unset, no account is created and the setup wizard runs. |
Sign-in throttling and client addresses
Section titled “Sign-in throttling and client addresses”| Variable | Default | Description |
|---|---|---|
COMPASSDOCS_TRUSTED_PROXY_HOPS |
1 |
How many trusted proxies sit in front of the app (the bundled Caddy counts as one). The sign-in throttle, the sign-in page’s lookup limit and the audit log read the client’s address from X-Forwarded-For that many entries from the right, so a client can’t dodge the limits by sending its own header. Set it to 2 when another proxy (Cloudflare, a load balancer) sits in front of Caddy. |
The limits are counted per app process: with several instances behind a load balancer, each counts its own share. See Security.
AI-powered search (optional)
Section titled “AI-powered search (optional)”| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY |
unset | Enables synthesized, cited answers on the Ask CompassDocs page. Without it, search falls back to keyword snippets. A key saved in Settings → AI takes precedence. From 1.20.0 it also serves Claude in the desk once an admin turns that on. |
COMPASSDOCS_AI_MODEL |
claude-opus-5-5 (before 1.20.0, claude-opus-4-8) |
The model used when none is saved in Settings → AI. A model saved there wins. Any model ID is accepted; see Choosing a model. |
COMPASSDOCS_ANTHROPIC_BASE_URL |
unset | Testing only, not a supported setting. (1.20.0) Sends every Anthropic API call to another address, such as the fake Messages API the test suite starts. Never set it in production. |
See AI-powered search for how the pipeline works. Claude in the desk adds no environment variable of its own: its settings are in Desk settings → Claude in the desk.
Runtime
Section titled “Runtime”| Variable | Default | Description |
|---|---|---|
PORT |
3000 |
Port the app listens on (used by the Docker compose file). |
COMPASSDOCS_BACKUP_DIR |
/backups |
Where database backups are written (mount a volume here). |
COMPASSDOCS_UPLOAD_DIR |
/uploads |
Where document attachments are stored (mount a volume here). |
COMPASSDOCS_SECRET_KEY |
— | Master key for encryption at rest (32 bytes: 64 hex or 44 base64 chars, e.g. openssl rand -hex 32). If unset, a key file is auto-generated in the uploads volume. Back it up outside your backup bucket. |
COMPASSDOCS_KEY_FILE |
$COMPASSDOCS_UPLOAD_DIR/.secret.key |
Where the auto-generated master key file lives when COMPASSDOCS_SECRET_KEY isn’t set. |
COMPASSDOCS_PLANTUML_SERVER |
https://www.plantuml.com/plantuml |
PlantUML server used to render ```plantuml blocks. Point at a self-hosted plantuml/plantuml-server to keep diagram text in-network, or set to off to disable. |
COMPASSDOCS_EMBEDDINGS_URL |
provider default | Override the semantic-search embeddings endpoint (e.g. an internal gateway). Takes precedence over the URL saved in Settings → AI. |
COMPASSDOCS_FETCH_ALLOW_PRIVATE |
unset | Set to 1 to let the server call addresses on private networks (10.x, 172.16.x to 172.31.x, 192.168.x, CGNAT and IPv6 ULA), such as webhooks to internal tools, a Snipe-IT server or (1.19.4) a helpdesk webhook receiver on your network. Unset, they are refused. Loopback, link-local and cloud metadata addresses are refused either way. See SSRF protection. |
Monitoring
Section titled “Monitoring”See Monitoring & health for the endpoints these configure.
| Variable | Default | Description |
|---|---|---|
COMPASSDOCS_METRICS_TOKEN |
— | Bearer token a Prometheus scraper presents to GET /metrics. Unset, the endpoint is admin-session-only. |
COMPASSDOCS_LOG_FORMAT |
console lines | Set to json for JSON-lines operational logs (for Loki, CloudWatch, etc.). |
Custom domain (TLS stack)
Section titled “Custom domain (TLS stack)”Used by docker-compose.tls.yml to serve the app
behind Caddy with HTTPS.
| Variable | Default | Description |
|---|---|---|
COMPASSDOCS_DOMAIN |
— | Your domain, e.g. docs.example.com. Caddy serves it with automatic HTTPS. |
Off-site backups
Section titled “Off-site backups”Optional — mirror database backups to object storage.
| Variable | Description |
|---|---|
BACKUP_S3_BUCKET / BACKUP_S3_REGION / BACKUP_S3_ACCESS_KEY_ID / BACKUP_S3_SECRET_ACCESS_KEY |
S3-compatible target (AWS S3, Cloudflare R2, MinIO). |
BACKUP_S3_ENDPOINT |
Set for R2/MinIO (custom endpoint). Optional for AWS. |
BACKUP_S3_PREFIX |
Optional key prefix. |
BACKUP_AZURE_CONNECTION_STRING / BACKUP_AZURE_CONTAINER |
Azure Blob Storage target. |
Helpdesk
Section titled “Helpdesk”Optional, for the helpdesk (Enterprise, 1.19.0).
| Variable | Default | Description |
|---|---|---|
COMPASSDOCS_PUSH_SUBJECT |
the custom domain, then the site’s https:// address, then the SMTP sender |
The contact the browsers’ push services see for your server, an https: URL or a mailto: address. Recommended: Safari refuses push without a valid one. |
COMPASSDOCS_PUSH_HOSTS |
— | More push service hosts to allow, comma-separated, for a browser whose push service is not one of the built-in ones below. |
COMPASSDOCS_HD_ATTACHMENT_MAX_MB |
25 |
The largest file, in MB, an agent or requester can attach to a ticket. Attachments are kept in the uploads volume. |
Outbound hosts for push
Section titled “Outbound hosts for push”Push notifications are sent from your server to each browser’s push service, over HTTPS (port 443). If your server’s outbound traffic is restricted, allow:
| Host | For |
|---|---|
fcm.googleapis.com (and the older android.googleapis.com) |
Chrome, Edge on Android, Brave, Opera, Samsung Internet |
updates.push.services.mozilla.com (any *.push.services.mozilla.com) |
Firefox |
web.push.apple.com (any *.push.apple.com) |
Safari on macOS, iPhone and iPad |
*.notify.windows.com |
Edge on Windows |
Push goes through HTTPS_PROXY when it is set (and honours NO_PROXY).
The server only ever sends to these hosts and any in
COMPASSDOCS_PUSH_HOSTS: a subscription to any other host is refused.
Push needs the site on HTTPS (localhost is the one exception). The push
keys are generated on first use and stored encrypted under the
master key: changing
COMPASSDOCS_SECRET_KEY without migrating the data means every agent turns
push on again.
Inbound endpoints
Section titled “Inbound endpoints”The helpdesk’s email channel and
integrations receive requests from outside:
/api/helpdesk/inbound/<secret> from your mail provider and
/api/helpdesk/intake/<id> from monitoring tools. If CompassDocs is
behind a firewall or a reverse proxy that limits paths, let those reach it
over HTTPS.
Workspace settings live in the app, not the environment
Section titled “Workspace settings live in the app, not the environment”Company name & logo, the sign-in page’s artwork and text, timezone, date/time format, theme, session timeout, trash retention, backup schedule, and the attachment size limit are configured from Settings (in the app) and stored in the database — not as environment variables. See Appearance & workspace.