Skip to main content

Environment Variables Reference

Each environment (staging, production) has its own .env and n8n.env files, which live on the server (in /app/{env}/) and are not in the repository — they hold secrets. This is the reference for what goes in them.

.env (the API / platform)​

Required:

  • DATABASE_URL — the Postgres connection string. Use the Docker service name postgres, not localhost (containers talk over the Docker network).
  • POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB — the database credentials. Use hex-only characters in the password to avoid URL-encoding issues in DATABASE_URL.
  • USER_JWT_SECRET and WORKFLOW_JWT_SECRET — the two signing secrets (min 32 chars each). They must be different values — the API refuses to start otherwise. Generate with openssl rand -hex 32.
  • NODE_ENV — production for deployed environments.
  • CORS_ORIGIN — the frontend URL (e.g. https://staging.circus.sh).

Optional:

  • API_PORT (default 4000), VITE_DOCS_URL (docs site URL), SENDGRID_API_KEY / SENDGRID_FROM_EMAIL (email — logs to console if unset), SENTRY_DSN (error tracking).
  • Reconciler tuning: WORKFLOW_EXECUTION_RECONCILER_INTERVAL_SECONDS (default 120), WORKFLOW_EXECUTION_RECONCILER_ADVISORY_LOCK_ID (default 918600 — override only if multiple independent deployments share one database).
  • Per-engine secrets (keyed by engine slug) — see Configuring Workflow Engine Secrets for the full set: WORKFLOW_ENGINE_PRODUCTION_WEBHOOK_SHARED_SECRET_{slug}, ..._TEST_WEBHOOK_SHARED_SECRET_{slug}, WORKFLOW_ENGINE_API_KEY_{slug}, and the webhook/stop timeouts.

n8n.env (the bundled n8n)​

  • N8N_HOST, N8N_PROTOCOL (https), WEBHOOK_URL — the n8n domain and webhook base.
  • N8N_BLOCK_ENV_ACCESS_IN_NODE=false and N8N_RUNNERS_ALLOW_ENV_VAR_ACCESS=true — allow workflow nodes to read env vars.
  • N8N_RUNNERS_ALLOWED_ENV_VARS — a comma-separated allowlist of the env var names nodes may read. Any AI-provider key you add (e.g. OPENAI_API_KEY) must also be listed here to be accessible.

(More on the n8n side — including bringing your own n8n — in n8n Deployment & Bring-Your-Own.)

GitHub secrets (for CI/CD)​

Set as repository secrets: DEPLOY_SSH_KEY (the ed25519 private key), DEPLOY_HOST (server IP), DEPLOY_USER (deploy), and GHCR_TOKEN (a classic PAT with write:packages — fine-grained tokens don't support Packages; rotate before its 90-day expiry).

After a change​

A .env change needs the container stopped and started, not restarted — docker compose restart reuses the existing container and won't pick up new values. Use stop then up -d (see Day-2 Operations).