Environment Variables Reference
API Server platform/api/.env
| Variable | Default | Description | Required |
|---|---|---|---|
| Server | |||
PORT |
3000 |
API server listen port | |
DOMAIN |
localhost:3000 |
Public-facing domain (used for CORS, preview URLs, OIDC issuer) | |
PORTAL_URL |
http://localhost:4200 |
Portal URL for CORS and OAuth redirects | |
NODE_ENV |
development |
Node.js environment (development, production) |
|
PLATFORM_ENV |
production |
Cairn deployment environment name | |
PLATFORM_URL |
— | Full platform URL for portal builds | |
KUBECONFIG |
~/.kube/config |
Path to Kubernetes kubeconfig | |
| PostgreSQL | |||
PLATFORM_PG_HOST |
— | PostgreSQL hostname | Yes |
PLATFORM_PG_PORT |
5432 |
PostgreSQL port | |
PLATFORM_PG_USER |
platform |
PostgreSQL user | |
PLATFORM_PG_PASSWORD |
— | PostgreSQL password | Yes |
PLATFORM_PG_DB |
platform |
PostgreSQL database name | |
PLATFORM_PG_POOL |
10 |
Connection pool size | |
| MongoDB | |||
PLATFORM_MONGO_URI |
— | MongoDB connection URI | Yes |
PLATFORM_MONGO_POOL |
5 |
Connection pool size | |
| Redis | |||
PLATFORM_REDIS_HOST |
— | Redis hostname | |
PLATFORM_REDIS_PORT |
6379 |
Redis port | |
PLATFORM_REDIS_PASSWORD |
— | Redis password | |
PLATFORM_REDIS_DB |
0 |
Redis database index | |
| Shared API state (Redis) | |||
REDIS_HOST / REDIS_PORT / REDIS_DB |
redis-master.databases.svc.cluster.local / 6379 / 0 |
Redis for login state, one-time codes, rate limits and permission-cache invalidation | |
REDIS_PASSWORD |
— | Cairn Redis password; the API derives and creates its own ACL user (plat-api, keys plat:api:*) from it |
Yes |
REDIS_API_USERNAME / REDIS_API_PASSWORD |
— | Use an externally managed ACL user instead | |
REDIS_SENTINEL_HOSTS |
— | Comma-separated Sentinel host:port list (default port 26379). When set, every API Redis client finds the master through Sentinel and ACL users are created on every node; platformctl sets it on the ha profile |
|
REDIS_SENTINEL_MASTER |
mymaster |
Sentinel master set name | |
REDIS_SENTINEL_USERNAME / REDIS_SENTINEL_PASSWORD |
— / REDIS_PASSWORD |
Credentials the API uses for Sentinel | |
REDIS_OP_TIMEOUT_MS |
2000 |
Deadline for one state-store operation before it counts as unavailable | |
PLATFORM_STATE_STORE |
redis |
memory = per-process state for single-process local development only |
|
SHUTDOWN_TIMEOUT_MS |
25000 |
Graceful-shutdown drain deadline after SIGTERM | |
| Secrets Encryption | |||
SECRETS_ENCRYPTION_KEY |
— | 32-byte master key for AES-256-GCM (base64 or hex) | Yes |
| JWT | |||
JWT_SECRET |
plat-super-secret-key |
JWT signing secret | |
| GitLab | |||
GITLAB_API_URL |
https://gitlab.com/api/v4 |
GitLab API base URL | |
GITLAB_TOKEN |
— | GitLab Personal Access Token (scopes: api, read_repository) |
|
GITLAB_WEBHOOK_SECRET |
— | Secret token for GitLab webhook verification | |
| GitHub | |||
GITHUB_TOKEN |
— | GitHub Personal Access Token (scopes: repo, admin:org_hook, write:packages) |
|
GITHUB_ORG |
— | GitHub organization name | |
GITHUB_WEBHOOK_SECRET |
— | Secret for GitHub webhook HMAC-SHA256 verification | |
| ClickUp | |||
CLICKUP_API_TOKEN |
— | ClickUp API token | |
CLICKUP_TEAM_ID |
— | ClickUp workspace team ID | |
CLICKUP_DEFAULT_LIST_ID |
— | Default list ID for bug reports | |
| SMTP / Email | |||
SMTP_PROVIDER |
— | Provider type: custom, ses, sendgrid, mailgun |
|
SMTP_HOST |
— | SMTP server hostname | |
SMTP_PORT |
587 |
SMTP server port | |
SMTP_USER |
— | SMTP username | |
SMTP_PASS |
— | SMTP password | |
SMTP_FROM_EMAIL |
noreply@DOMAIN |
From email address | |
SMTP_FROM_NAME |
Platform |
From display name | |
SMTP_AWS_REGION |
us-east-1 |
AWS SES region (when SMTP_PROVIDER=ses) |
|
SMTP_AWS_KEY |
— | AWS SES access key | |
SMTP_AWS_SECRET |
— | AWS SES secret key | |
SENDGRID_API_KEY |
— | SendGrid API key (when SMTP_PROVIDER=sendgrid) |
|
MAILGUN_DOMAIN |
— | Mailgun sending domain (when SMTP_PROVIDER=mailgun) |
|
MAILGUN_API_KEY |
— | Mailgun API key | |
| Integration Flags (for bootstrap status) | |||
ARGOCD_URL |
— | ArgoCD URL (alternative to auto-detect) | |
ARGOCD_TOKEN |
— | ArgoCD API token | |
GRAFANA_URL |
— | Grafana URL (alternative to auto-detect) | |
LOKI_URL |
http://localhost:3100 |
Loki push endpoint |
Docker / Bootstrap platform-bootstrap/.env
| Variable | Default | Description | Required |
|---|---|---|---|
| Domain & Identity | |||
DOMAIN |
— | Primary domain (e.g. platform.company.com) |
Yes |
ADMIN_EMAIL |
— | Admin email for Let's Encrypt + notifications | Yes |
PLATFORM_NAME |
Platform |
Display name for the platform | |
| Bootstrap Behaviour | |||
NON_INTERACTIVE |
false |
Skip all prompts (CI mode) | |
SKIP_K8S |
false |
Skip Kubernetes install (use existing cluster) | |
PLATFORM_IMAGE_TAG |
latest |
Docker image tag to deploy | |
PLATFORM_REPO_URL |
— | Container registry URL | |
| Component Toggles | |||
API_REPLICAS |
2 (1 on minimal) |
Cairn API replica count (1–10); a PodDisruptionBudget is added when ≥ 2 | |
INSTALL_ARGOCD |
y |
Install ArgoCD | |
INSTALL_MONITORING |
y |
Install Grafana + Prometheus + Loki | |
INSTALL_PORTAINER |
y |
Install Portainer | |
INSTALL_CERTMANAGER |
y |
Install cert-manager | |
| Let's Encrypt | |||
LE_EMAIL |
— | Email for Let's Encrypt certificate registration | Yes |
| Generated Secrets | |||
POSTGRES_PASSWORD |
— | PostgreSQL admin password (auto-generated if blank) | |
MONGO_PASSWORD |
— | MongoDB root password | |
REDIS_PASSWORD |
— | Redis password | |
MINIO_ACCESS_KEY |
platformadmin |
MinIO access key | |
MINIO_SECRET_KEY |
— | MinIO secret key | |
JWT_SECRET |
— | JWT signing secret | |
PLATFORM_WEBHOOK_SECRET |
— | Webhook shared secret | |
ARGOCD_PASSWORD |
— | ArgoCD admin password | |
GRAFANA_PASSWORD |
— | Grafana admin password | |
| GitHub Integration | |||
GITHUB_TOKEN |
— | PAT with repo, admin:org_hook, write:packages |
|
GITHUB_ORG |
— | GitHub organization name | |
GITHUB_REGISTRY |
ghcr.io |
Container registry (e.g. ghcr.io) |
|
| GitLab Integration | |||
GITLAB_URL |
https://gitlab.com |
GitLab instance URL | |
GITLAB_TOKEN |
— | PAT with api, read_repository |
|
GITLAB_GROUP |
— | GitLab group namespace | |
| ClickUp Integration | |||
CLICKUP_API_TOKEN |
— | ClickUp API token | |
CLICKUP_TEAM_ID |
— | Workspace team ID | |
CLICKUP_DEFAULT_LIST_ID |
— | Default list for bug reports | |
| External S3 / Backup Storage | |||
EXT_S3_ENDPOINT |
— | External S3 endpoint URL | |
EXT_S3_BUCKET |
platform-backups |
External S3 bucket name | |
EXT_S3_KEY |
— | External S3 access key | |
EXT_S3_SECRET |
— | External S3 secret key | |
EXT_S3_REGION |
us-east-1 |
External S3 region |
Legacy CAPS Variables (Backward Compat)
The following legacy CAPS_* variables are kept for backward compatibility with the original CAPS naming convention. They are read in the bootstrap and deployment configurations.
| Legacy Variable | Maps To | Notes |
|---|---|---|
CAPS_POSTGRES_HOST |
POSTGRES_HOST / PLATFORM_PG_HOST |
|
CAPS_POSTGRES_PORT |
POSTGRES_PORT / PLATFORM_PG_PORT |
|
CAPS_POSTGRES_DB |
POSTGRES_DB / PLATFORM_PG_DB |
|
CAPS_POSTGRES_USER |
POSTGRES_USER / PLATFORM_PG_USER |
|
CAPS_POSTGRES_PASSWORD |
POSTGRES_PASSWORD |
|
CAPS_MONGODB_URI |
MONGO_URI / PLATFORM_MONGO_URI |
|
CAPS_REDIS_HOST |
REDIS_HOST / PLATFORM_REDIS_HOST |
|
CAPS_REDIS_PORT |
REDIS_PORT / PLATFORM_REDIS_PORT |
|
CAPS_REDIS_PASSWORD |
REDIS_PASSWORD |
|
CAPS_JWT_SECRET |
JWT_SECRET |
|
CAPS_ENCRYPTION_KEY |
SECRETS_ENCRYPTION_KEY |
|
CAPS_DOMAIN |
DOMAIN |
|
CAPS_SMTP_HOST |
SMTP_HOST |
|
CAPS_SMTP_PORT |
SMTP_PORT |
|
CAPS_SMTP_USER |
SMTP_USER |
|
CAPS_SMTP_PASS |
SMTP_PASS |
|
CAPS_MINIO_ENDPOINT |
S3_ENDPOINT / MINIO_ENDPOINT |
|
CAPS_MINIO_ACCESS_KEY |
MINIO_ACCESS_KEY |
|
CAPS_MINIO_SECRET_KEY |
MINIO_SECRET_KEY |
|
CAPS_GITLAB_TOKEN |
GITLAB_TOKEN |
|
CAPS_CLICKUP_TOKEN |
CLICKUP_API_TOKEN |
|
CAPS_CLICKUP_TEAM_ID |
CLICKUP_TEAM_ID |
|
CAPS_CLICKUP_LIST_ID |
CLICKUP_DEFAULT_LIST_ID |
Kubernetes Secret Mapping
When deployed to Kubernetes, the platform-env Secret is created from the bootstrap .env file. The key names in the K8s Secret correspond directly to the environment variable names above. See platform-bootstrap/bootstrap.sh lines 409--448 for the complete mapping.
# Example: creating K8s secret from env vars
kubectl create secret generic platform-env \
--namespace platform \
--from-literal=JWT_SECRET="$JWT_SECRET" \
--from-literal=POSTGRES_HOST=postgresql.databases \
--from-literal=POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
--from-literal=SECRETS_ENCRYPTION_KEY="$SECRETS_ENCRYPTION_KEY" \
# ... all other vars
Installer object storage
Fresh installs only; see external object storage.
These settings are saved in /etc/platform/.env and passed to the API by the installer.
| Variable | Default | Description |
|---|---|---|
OBJECT_STORAGE_MODE |
bundled |
bundled or external, on any profile. External skips MinIO and its console/SSO/bootstrap steps. |
OBJECT_STORAGE_ENDPOINT |
Empty | Required in external mode: S3 API URL with no credentials, path or query. |
OBJECT_STORAGE_REGION |
us-east-1 |
Signing region; R2 uses auto. |
OBJECT_STORAGE_BUCKET_PREFIX |
cairn |
Unique bucket prefix; buckets are <prefix>-<purpose> for uploads, backups, replays, loki, tempo, pyroscope and registry. |
OBJECT_STORAGE_FORCE_PATH_STYLE |
true |
true for path addressing, false for virtual-hosted addressing. |
Credentials use Kubernetes Secret platform/platform-object-storage keys
OBJECT_STORAGE_ACCESS_KEY and OBJECT_STORAGE_SECRET_KEY, written from stdin
with provision --object-storage-credentials-stdin or hidden interactive prompts.
Do not put these keys in argv or the host .env file. Namespace-local consumer
Secrets are derived from the master Secret. Missing buckets are created through
S3 when permitted; write/read/delete preflight must pass before k3s starts.