diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2b71b03 --- /dev/null +++ b/.gitignore @@ -0,0 +1,42 @@ +# Secrets und Konfiguration mit Credentials +.env +.env.* +!.env.example +secrets/ + +# Docker-Volumes und persistente Daten (groß, nicht versioniert) +data/ +volumes/ +pgdata/ + +# Backups (können sehr groß werden) +backups/ + +# Logs +*.log +logs/ + +# Temporäre Dateien +*.tmp +*.swp +*.bak +*~ + +# OS +.DS_Store +Thumbs.db +desktop.ini + +# Editor +.idea/ +.vscode/ +*.iml + +# Python (falls Hilfsskripte) +__pycache__/ +*.pyc +*.pyo + +# Node (falls lokale Tools) +node_modules/ +npm-debug.log* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a297dc9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,86 @@ +# 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 + +```bash +# 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. diff --git a/INITIAL_PROMPT.md b/INITIAL_PROMPT.md new file mode 100644 index 0000000..ed6a467 --- /dev/null +++ b/INITIAL_PROMPT.md @@ -0,0 +1,85 @@ +Du arbeitest auf meinem Linux-System und sollst einen vollständigen, produktionsnahen n8n-Stack installieren und konfigurieren. Zumindest die Stack-Anteile, die viel Speicher verbrauchen, sollen im Verzeichnis /home/dschlueter/nvme2n1p7_home/n8n_stack liegen. + +Ziel: +Ich möchte danach komplette n8n-Projekte von Dritten übernehmen, lokal speichern, importieren, verwalten, sichern und ausführen können. Das System soll robust, updatefähig und nachvollziehbar dokumentiert sein. + +Wichtige Arbeitsregeln: +1. Führe zuerst eine Bestandsaufnahme meines Systems durch und gib einen Umsetzungsplan aus, bevor du Änderungen machst. +2. Prüfe OS, Distribution, Docker, Docker Compose, Firewall, freie Ports, verfügbare Domain/Subdomain, Reverse-Proxy-Situation, RAM, CPU, Plattenplatz und Benutzerrechte. +3. Wenn Informationen fehlen, frage gezielt nach oder lege eine sinnvolle Standardkonfiguration in einer CONFIG-Sektion offen. +4. Nimm nur idempotente Änderungen vor und erstelle vor riskanten Änderungen Backups vorhandener Konfigurationen. +5. Dokumentiere alle erzeugten Dateien und Befehle in einer Markdown-Datei im Projektordner. + +Technische Zielarchitektur: +- Deployment mit Docker Compose +- n8n als Hauptservice +- Postgres als Datenbank +- Redis für Queue-Mode +- mindestens ein n8n-Worker +- Reverse Proxy mit HTTPS +- persistente Volumes +- separater Projektordner, z. B. ~/stacks/n8n +- .env-Datei für Konfiguration +- automatischer Start nach Reboot +- Healthchecks, sinnvolle Restart-Policy +- Zeitzone Europe/Berlin +- sichere Dateirechte +- keine Demo-Konfiguration + +Funktionsanforderungen: +- Ich muss Workflow-JSON-Dateien importieren können +- Ich muss Credentials und Workflows per CLI exportieren und importieren können +- Lege dafür Hilfsskripte an: + - import-workflow.sh + - import-credentials.sh + - export-workflows.sh + - export-credentials.sh + - backup-n8n.sh + - restore-n8n.sh +- Erstelle Ordner für: + - backups/ + - imports/workflows/ + - imports/credentials/ + - local-files/ + - compose/ + - docs/ + +Sicherheitsanforderungen: +- generiere starke zufällige Secrets +- verwende eine feste N8N_ENCRYPTION_KEY-Konfiguration +- setze sichere Datei- und Verzeichnisrechte +- exponiere nur notwendige Ports +- falls bereits ein Reverse Proxy existiert, integriere n8n dort statt einen zweiten Proxy unnötig parallel zu betreiben +- dokumentiere klar, welche Daten unverschlüsselt exportiert werden können und welche Risiken das hat + +Betriebsanforderungen: +- richte Logs, Update-Hinweise und Wartungsbefehle ein +- prüfe den Stack nach dem Start mit health/status checks +- teste, dass n8n erreichbar ist +- teste, dass ein Workflow-Import grundsätzlich möglich ist +- richte ein Beispiel für CLI-Import/Export ein +- richte ein Backup-Konzept für Datenbank, n8n-Daten und Compose-Dateien ein + +Erwartetes Ergebnis: +1. Vollständig installierter und laufender n8n-Stack +2. Alle Konfigurationsdateien erstellt +3. Alle Skripte funktionsfähig +4. README.md mit: + - Architektur + - Pfaden + - Start/Stop/Update-Befehlen + - Backup/Restore + - Import/Export von Workflows und Credentials + - Hinweise zur Übernahme fremder n8n-Projekte +5. Abschließend eine kompakte Übergabe mit: + - verwendeten URLs + - Zugangspfad + - wichtigen Secrets-Dateien bzw. Speicherorten + - To-do-Punkten, falls manuell noch Domain/DNS erforderlich ist + +Bevor du Änderungen machst: +- analysiere zuerst mein System +- formuliere dann einen konkreten Plan +- führe danach die Installation und Konfiguration Schritt für Schritt aus +- zeige mir am Ende alle erzeugten Dateien +