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. |
Initial admin account
Section titled “Initial admin account”Created only on first launch, when the users table is empty.
| Variable | Default | Description |
|---|---|---|
COMPASSDOCS_ADMIN_USER |
admin |
Username for the bootstrap admin. |
COMPASSDOCS_ADMIN_PASSWORD |
admin |
Password for the bootstrap admin. If you set this, the account is ready to use; if you leave it as the default, the user must change it on first sign-in. |
AI-powered search (optional)
Section titled “AI-powered search (optional)”| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY |
— | Enables synthesized, cited answers on the Ask CompassDocs page. Without it, search falls back to keyword snippets. |
COMPASSDOCS_AI_MODEL |
claude-opus-4-8 |
Override the model used for answers. |
See AI-powered search for how the pipeline works.
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. |
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. |
Workspace settings live in the app, not the environment
Section titled “Workspace settings live in the app, not the environment”Company name & logo, 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.