n8n_stack/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Purpose

Production-grade n8n automation stack running on Docker Compose. The primary use-case is importing, managing, and running n8n workflow projects from third parties.

Intended Stack Architecture

Service	Role
n8n (main)	Workflow editor + webhook entrypoint
n8n-worker(s)	Queue-mode execution workers
PostgreSQL	Primary database
Redis	Queue backend for worker mode
Reverse Proxy	HTTPS termination (integrate existing proxy if present)

All data-heavy paths (volumes, backups) live under /home/dschlueter/nvme2n1p7_home/n8n_stack/.

Directory Layout (target)

compose/          # docker-compose.yml and any override files
.env              # secrets and config (never commit — see .gitignore)
.env.example      # safe template for .env
data/             # docker volume mount-points (gitignored)
backups/          # database + file backups (gitignored)
imports/
  workflows/      # JSON files to import
  credentials/    # JSON credential exports
local-files/      # files made available inside n8n containers
docs/             # architecture notes, runbooks
scripts/          # helper shell scripts (see below)

Helper Scripts (scripts/)

Script	Purpose
import-workflow.sh	Import a workflow JSON via n8n CLI
import-credentials.sh	Import credentials JSON via n8n CLI
export-workflows.sh	Dump all workflows to imports/workflows/
export-credentials.sh	Dump credentials (unencrypted — handle with care)
backup-n8n.sh	Snapshot DB + n8n data to backups/
restore-n8n.sh	Restore from a snapshot

Common Operations

# Start full stack
docker compose -f compose/docker-compose.yml up -d

# Stop stack
docker compose -f compose/docker-compose.yml down

# View logs
docker compose -f compose/docker-compose.yml logs -f n8n

# Check health
docker compose -f compose/docker-compose.yml ps

# Import a workflow
bash scripts/import-workflow.sh imports/workflows/my-workflow.json

# Export all workflows
bash scripts/export-workflows.sh

# Full backup
bash scripts/backup-n8n.sh

Key Configuration Notes

• All secrets (DB password, N8N_ENCRYPTION_KEY, Redis password) are generated once and stored in .env. The encryption key must never change after first run — doing so breaks stored credentials.
• Queue mode requires EXECUTIONS_MODE=queue in .env and a running Redis instance.
• Timezone is Europe/Berlin throughout.
• Only port 443/80 (via reverse proxy) should be exposed externally; n8n listens internally on 5678.

Security Notes on Export

export-credentials.sh produces unencrypted JSON — treat the output like a private key. Keep exports out of imports/credentials/ if that directory is ever shared.

Idempotency Rule

All scripts and compose changes must be idempotent (safe to re-run). Before risky changes, back up the relevant config or volume first.