From 62089b0b4b07ded30f3da48d0449a8d96310d3d2 Mon Sep 17 00:00:00 2001 From: Yury Kossakovsky Date: Tue, 9 Dec 2025 17:34:29 -0700 Subject: [PATCH] docs: document worker-runner sidecar architecture update CLAUDE.md with sidecar pattern details including dynamic generation, network mode, and scaling instructions. add worker count and architecture info to final installation report. --- CLAUDE.md | 9 ++++++--- scripts/07_final_report.sh | 2 ++ 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7fffed7..abe0b8b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -93,16 +93,19 @@ Follow this workflow when adding a new optional service (refer to `.cursor/rules ### n8n Configuration (v2.0+) - n8n runs in `EXECUTIONS_MODE=queue` with Redis as the queue backend -- **Task runners**: n8n v2.0 uses external task runners for Code node execution (JavaScript and Python) - - Runner count controlled by `N8N_RUNNER_COUNT` env var (defaults to 1) +- **OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true**: All executions (including manual tests) run on workers +- **Worker-Runner Sidecar Pattern**: Each worker has its own dedicated task runner + - Workers and runners are generated dynamically via `scripts/generate_n8n_workers.sh` + - Configuration stored in `docker-compose.n8n-workers.yml` (auto-generated, gitignored) + - Runner connects to its worker via `network_mode: "service:n8n-worker-N"` (localhost:5679) - Runner image `n8nio/runners` must match n8n version +- **Scaling**: Change `N8N_WORKER_COUNT` in `.env` and run `bash scripts/generate_n8n_workers.sh` - **Code node libraries**: Configured on the runner container (not n8n): - `NODE_FUNCTION_ALLOW_EXTERNAL`: JS packages (`cheerio`, `axios`, `moment`, `lodash`) - `NODE_FUNCTION_ALLOW_BUILTIN`: Node.js built-in modules (`*` = all) - `N8N_RUNNERS_STDLIB_ALLOW`: Python stdlib modules - `N8N_RUNNERS_EXTERNAL_ALLOW`: Python third-party packages - Workflows can access the host filesystem via `/data/shared` (mapped to `./shared`) -- Worker count is controlled by `N8N_WORKER_COUNT` env var (defaults to 1) - `N8N_BLOCK_ENV_ACCESS_IN_NODE=false` allows Code nodes to access environment variables ### Caddy Reverse Proxy diff --git a/scripts/07_final_report.sh b/scripts/07_final_report.sh index d221b59..aeab431 100644 --- a/scripts/07_final_report.sh +++ b/scripts/07_final_report.sh @@ -51,6 +51,8 @@ if is_profile_active "n8n"; then echo "================================= n8n =================================" echo echo "Host: ${N8N_HOSTNAME:-}" + N8N_WORKER_COUNT_VAL="${N8N_WORKER_COUNT:-1}" + echo "Workers: $N8N_WORKER_COUNT_VAL (each with dedicated task runner sidecar)" fi if is_profile_active "open-webui"; then