Compass uses compass.yaml for self-hosting and local development. The file is visible, diffable, and contains secrets, so keep it out of git and back it up with the Docker volumes.
Examples:
- local development:
compass.example.yaml
- self-hosting:
self-host/compass.example.yaml
Runtime
| key | Required | Description |
|---|
runtime.version | Self-host | Docker image tag used by the self-host compose stack. Defaults to latest. Pin this for reproducible installs. |
runtime.nodeEnv | Yes | Runtime mode. Use production for self-hosted and staging; development for local dev. |
runtime.timezone | Yes | Backend timezone. Only Etc/UTC and UTC are accepted. |
runtime.logLevel | No | Winston log level. Defaults to info. Set to debug to include health-check requests (GET /api/health) in the logs, which are otherwise hidden. |
Web
| key | Required | Description |
|---|
web.port | 9080 | Host port bound to the web container on 127.0.0.1. |
web.url | Yes | Public frontend URL as seen by the backend. Example: https://compass.example.com. |
Backend
| key | Required | Description |
|---|
backend.port | 3000 | Host port bound to the backend container on 127.0.0.1. |
backend.apiUrl | Yes | Public API URL. Example: https://compass.example.com/api. This is baked into the web bundle when the web image is rebuilt. |
backend.originsAllowed | Yes | YAML list of allowed CORS origins. Include web.url. |
backend.compassToken | Yes | Bearer token protecting internal sync endpoints. |
MongoDB
| key | Required | Description |
|---|
mongo.uri | Yes | Backend MongoDB connection string. For self-hosted installs, must include authSource=admin and replicaSet=rs0. |
mongo.username | Self-host | MongoDB root username created on first container startup. Must match the credentials in mongo.uri. |
mongo.password | Self-host | MongoDB root password. Changing it after first startup requires a MongoDB user migration. |
mongo.replicaSetKey | Self-host | Shared secret used for internal authentication between replica set members. |
SuperTokens
SuperTokens handles user-sessions for us.
| key | Required | Description |
|---|
supertokens.uri | Yes | SuperTokens Core URL as seen by the backend. Self-hosted Docker uses http://supertokens:3567. |
supertokens.key | Yes | API key shared by backend and SuperTokens Core. |
supertokens.postgres.user | Self-host | Postgres user for the SuperTokens database container. |
supertokens.postgres.password | Self-host | Postgres password for the SuperTokens database container. |
supertokens.postgres.database | Self-host | Postgres database name for SuperTokens. |
Google
These values are only necessary if you want to enable Google Oauth and/or 2-way sync between Compass and Google Calendar
Both google.clientId and google.clientSecret must be real values for Google features to activate. Setting only one causes backend startup to fail.
| key | Required | Description |
|---|
google.clientId | No | Google OAuth client ID. Rebuild the web image after changing it. |
google.clientSecret | No | Google OAuth client secret. Backend-only. |
google.channelExpirationMin | No | Google Calendar watch channel lifetime in minutes. Defaults to 10080 (7 days). Watch repair renews a channel once it's within a 3-day buffer of expiring. Short values (e.g. single-digit minutes) are a dev/test override, not a self-hosting setting. |
google.webhookUrl | No | Public HTTPS API URL for Google Calendar push notifications. When omitted, Compass uses backend.apiUrl. |
google.notificationToken | Required for HTTPS Google webhooks | Token used to verify Google Calendar webhook requests. |
See Google Calendar for full setup instructions.
Sync Service
Standalone service (packages/sync) that owns Google Calendar sync end to
end. Every deployment runs it — the backend exits at startup without
sync.serviceUrl/sync.internalAuthToken configured, and the self-host
installer writes the sync: block by default (see
Self-Hosting). Sync uses an isolated Mongo
database and must not share the backend's database user/data.
| key | Required | Description |
|---|
sync.port | No | Sync HTTP port. Defaults to 3010 in examples. |
sync.mongoUri | Yes | Isolated Sync Mongo URI. Never point this at the API database. |
sync.internalAuthToken | Yes | Shared secret for Sync internal routes. Must match what the API uses. |
sync.callbackBaseUrl | Yes | Public base URL for provider OAuth/webhook callbacks (proxied as /sync/*). |
sync.postConnectRedirectUrl | No | Browser redirect after OAuth connect. Set this to web.url — an unset value falls back to callbackBaseUrl (Sync's own API host), which strands the user there instead of back on the calendar. |
sync.serviceUrl | Yes | Base URL the backend uses to reach Sync (e.g. http://localhost:3010). The backend refuses to start without this and internalAuthToken set. |
sync.cloudMutationMode | No | enabled (default) or maintenance. Maintenance rejects cloud edits/connect with typed MAINTENANCE (503). |
sync.execution | No | passive (default) or active. Active is required for OAuth begin and provider import/jobs. |
sync.maxConcurrency | No | Job concurrency hint for Sync workers. |
sync.enforceLeastPrivilege | No | When true, Sync verifies its Mongo user cannot read the API database. |
sync.compassApiDatabase | No | API database name the least-privilege check must be denied access to. |
Optional Integrations
| key | Required | Description |
|---|
posthog.key | No | PostHog project key injected into the web bundle. |
posthog.host | No | PostHog host injected into the web bundle. |
stripe.secretKey | No | Stripe secret (sk_test_... is fine on staging). All three Stripe keys are required together; omit the whole stripe: block on self-host. |
stripe.webhookSecret | No | Stripe webhook signing secret. |
stripe.priceId | No | Stripe Price id for the $7.99/month plan. |