n8n Deployment & Bring-Your-Own

Circus needs a workflow engine to actually run workflows, and the reference deployment bundles n8n in the compose stack. You can run with the bundled instance or point Circus at an n8n you host yourself — the platform only cares that an engine record's URLs are reachable.

The bundled n8n

The deploy/docker-compose.prod.yml ships an n8n service per environment, configured through n8n.env (N8N_HOST, N8N_PROTOCOL, WEBHOOK_URL). It stores its own data — workflows, credentials, execution history — in the n8n_data Docker volume using SQLite. No Postgres wiring is needed for n8n; its data is entirely separate from the Circus database.

Letting nodes read provider keys

n8n task runners block environment-variable access by default. The bundled config opens it deliberately and narrowly:

• N8N_BLOCK_ENV_ACCESS_IN_NODE=false and N8N_RUNNERS_ALLOW_ENV_VAR_ACCESS=true enable access;
• N8N_RUNNERS_ALLOWED_ENV_VARS is an allowlist of the exact variable names nodes may read.

So adding an AI-provider key is two edits: set the key (e.g. OPENAI_API_KEY=…) and add its name to N8N_RUNNERS_ALLOWED_ENV_VARS. A key that isn't on the allowlist is invisible to nodes.

Bring your own n8n

Nothing ties Circus to the bundled container. To use an external n8n, register an engine record (Configuring Workflow Engine Secrets) whose productionWebhookBaseUrl, testWebhookBaseUrl, and apiBaseUrl point at your instance, set the matching per-engine secrets, and simply don't route traffic to the bundled one (you can leave it out of your compose file). Circus reaches the engine over HTTP like any other — the only requirements are that the webhook base URLs accept the signed dispatch and the API base URL is reachable from the API container for stop calls.

Whichever you run, pin n8n to a specific version rather than tracking an implicit latest — see Upgrading n8n.