### **Anforderungsdokument (Version 3): Docker-Migration nach Ubuntu VM (`docker1`)** **Zweck:** Verbindliche Netzwerk-Anforderungen und schrittweiser Migrationsplan für den Umzug des GTM-Engine Stacks (ca. 20 Container). Basierend auf den Stabilisierungs-Erkenntnissen vom 07.03.2026. #### **Teil 1: Externe Port-Freigaben (Firewall)** Diese Ports müssen auf der Firewall für den eingehenden Verkehr zur VM `10.10.81.2` geöffnet werden. | Host-Port | Ziel-Dienst | Zugriff | Zweck | | :--- | :--- | :--- | :--- | | **8090** | `gateway_proxy` | Intranet | **Zentraler Zugang.** Alle Web-Apps (Dashboard, CE, Lead). | | **3000** | `gitea` | Intranet | Gitea Web UI. | | **2222** | `gitea` | Intranet | Gitea Git via SSH. | | **8003** | `connector-so` | **Public** | SuperOffice Webhook-Empfänger (SSL erforderlich!). | | **5678** | `n8n` | **Public** | Automation Workhooks. | | **8094** | `gtm-architect`| Intranet | GTM Architect Direct. | | **8092** | `b2b-marketing`| Intranet | B2B Marketing Assistant Direct. | | **8001** | `transcription`| Intranet | Transcription Tool Direct (via 8090). | --- ### **Port-Mapping (docker-compose.yml)** Die folgende Tabelle listet alle Host-Ports auf, die durch die `docker-compose.yml` gebunden werden. Diese sind die Ports, die auf `docker1` lauschen werden. | Host-Port | Ziel-Dienst | Zweck / Notiz | | :--- | :--- | :--- | | **8090** | `nginx` (Gateway) | Zentraler Zugang (Intranet) | | **8000** | `company-explorer` | API (intern) | | **8003** | `connector-superoffice`| Webhook (Public) | | **8501** | `lead-engine` | UI (intern) | | **8004** | `lead-engine` | API (intern) | | **8092** | `b2b-marketing-assistant`| UI/API (Intranet) | | **8093** | `content-engine` | UI/API (Intranet) | | **8094** | `gtm-architect` | UI/API (Intranet) | | **8096** | `heatmap-frontend` | UI (Intranet) | | **8002** | `heatmap-backend` | API (intern) | | **8097** | `competitor-analysis` | UI/API (Intranet) | | **8098** | `market-intelligence` | UI/API (Intranet) | | **8001** | `transcription-tool` | UI/API (Intranet) | --- #### **Teil 2: Netzwerk-Architektur (Intern)** * **DNS Resolver:** In Nginx konfiguriert (`resolver 127.0.0.11`). * **WebSockets:** Das Gateway unterstützt `Upgrade`-Header (kritisch für Streamlit/Lead-Engine). * **Echo-Prävention:** Der Connector (`worker.py`) identifiziert sich dynamisch. Keine manuellen ID-Einträge in `.env` nötig, solange `SO_CLIENT_ID` passt. * **Routing:** * `/ce/` -> `company-explorer:8000` * `/lead/` -> `lead-engine:8501` (UI) * `/feedback/` -> `lead-engine:8004` (API) * `/gtm/` -> `gtm-architect:3005` (API/Frontend) * `/b2b/` -> `b2b-marketing-assistant:3002` (API/Frontend) * `/content/` -> `content-engine:3000` (API/Frontend) * `/market/` -> `market-intelligence:3001` (API/Frontend) * `/competitor/` -> `competitor-analysis:3000` (API/Frontend) * `/heatmap/` -> `heatmap-frontend:80` (Static/Proxy) * `/tr/` -> `transcription-tool:8001` (API/Frontend) -> **Achtung:** Benötigt expliziten `rewrite` in Nginx! --- # ⚠️ Kritische Lehren (Update 08.03.2026) Der Umzug muss zwingend diese Punkte beachten, um den "Totalausfall" zu vermeiden: ### 1. Datenbank-Schema & Volumes **Regel:** Datenbanken werden **NIEMALS** mehr direkt auf einen Host-Pfad gemountet. **Grund:** Permission-Errors und SQLite-Locks auf Netzwerk-Dateisystemen. **Vorgehen:** Nutzung von benannten Volumes (`explorer_db_data`, `connector_db_data`, `lead_engine_data`, `gtm_architect_data`, `b2b_marketing_data`, `content_engine_data`, `market_intel_data`, `competitor_analysis_data`, `transcription_uploads`). ### 2. Lead Engine: Kalender-Logik (v1.4) * **Raster:** Das System bietet Termine nur im **15-Minuten-Takt** (:00, :15, :30, :45) an. * **Abstand:** Zwischen zwei Terminvorschlägen liegen mind. **3 Stunden** Pause. * **AppOnly Workaround:** Termin wird im Kalender von `info@robo-planet.de` erstellt und der Mitarbeiter (`e.melcer@`) als Teilnehmer hinzugefügt. ### 3. GTM Architect & B2B Assistant: Standalone-Betrieb * **Architektur:** Beide Apps nutzen das "Self-Contained Image" Muster. Code, Frontend-Builds (`dist/`) und `node_modules` sind fest im Image verbaut. * **GTM Port:** 3005 intern. * **B2B Port:** 3002 intern. * **DB-Abhängigkeit:** Der B2B Assistant benötigt zwingend die Datei `market_db_manager.py` (wird beim Build aus dem Root kopiert). ### 4. Transcription Tool: FFmpeg & Routing * **FFmpeg:** Muss im Image vorhanden sein (Build dauert ca. 15 Min auf Synology). * **Pfade:** Das Tool benötigt eine `tsconfig.json` im `frontend/` Ordner für den TypeScript-Build. * **Nginx:** Der Pfad `/tr/` muss explizit umgeschrieben werden: `rewrite ^/tr/(.*) /$1 break;`. --- ### 📂 Docker Volume Migration (Der "Plug & Play" Weg) Um die Daten (Companies, Leads, Projekte, Audio-Files) ohne Verluste umzuziehen, müssen die benannten Volumes gesichert werden. **Auf der Synology (Quelle):** ```bash # Backup aller kritischen Volumes in ein Archiv docker run --rm -v explorer_db_data:/data -v $(pwd):/backup alpine tar czf /backup/explorer_data.tar.gz -C /data . docker run --rm -v lead_engine_data:/data -v $(pwd):/backup alpine tar czf /backup/lead_data.tar.gz -C /data . docker run --rm -v gtm_architect_data:/data -v $(pwd):/backup alpine tar czf /backup/gtm_data.tar.gz -C /data . docker run --rm -v b2b_marketing_data:/data -v $(pwd):/backup alpine tar czf /backup/b2b_data.tar.gz -C /data . docker run --rm -v content_engine_data:/data -v $(pwd):/backup alpine tar czf /backup/content_data.tar.gz -C /data . docker run --rm -v market_intel_data:/data -v $(pwd):/backup alpine tar czf /backup/market_data.tar.gz -C /data . docker run --rm -v competitor_analysis_data:/data -v $(pwd):/backup alpine tar czf /backup/competitor_data.tar.gz -C /data . docker run --rm -v transcription_uploads:/data -v $(pwd):/backup alpine tar czf /backup/tr_uploads.tar.gz -C /data . ``` **Auf der Ubuntu VM (Ziel):** 1. Volumes anlegen: `docker volume create explorer_db_data` (etc.) 2. Daten wiederherstellen: ```bash docker run --rm -v explorer_db_data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/explorer_data.tar.gz" ``` --- ### **Verbindlicher Migrationsplan** **Phase 1: Vorbereitung** 1. [ ] **`git push`** auf Synology (aktuellster Stand inkl. GTM-Integration). 2. [ ] **`.env` Datei sichern** (Vollständigkeit prüfen!). 3. [ ] **Volumes sichern** (siehe oben: `tar.gz` Erstellung). **Phase 2: Deployment auf `docker1`** 1. [ ] Repo klonen: `git clone ... /opt/gtm-engine` 2. [ ] `.env` kopieren. 3. [ ] **Volumes restoren** (BEVOR `docker compose up` ausgeführt wird). 4. [ ] Starten: `docker compose up -d --build` 5. [ ] **Schema-Check:** `docker exec -it company-explorer python /app/fix_missing_columns.py` **Phase 3: Verifizierung** 1. [ ] Check Kalender-Lesen: `docker exec lead-engine python /app/trading_twins/test_calendar_logic.py` 2. [ ] Check GTM Architect: `https://10.10.81.2:8090/gtm/` --- ### **Anhang A: Post-Deployment Port Check** Führen Sie dieses Skript auf einem Client-Rechner aus (nicht auf `docker1` selbst), um die Erreichbarkeit der freigegebenen Ports zu testen. Ersetzen Sie `TARGET_IP` durch `10.10.81.2`. ```bash #!/bin/bash TARGET_IP="10.10.81.2" PORTS_INTRANET=(8090 3000 2222 8092 8093 8094 8096 8097 8098 8001) PORTS_PUBLIC=(8003 5678) echo "--- Testing Intranet Ports on $TARGET_IP ---" for port in "${PORTS_INTRANET[@]}"; do if nc -z -w 2 $TARGET_IP $port; then echo "✅ Port $port is OPEN" else echo "❌ Port $port is CLOSED" fi done echo -e "\n--- Testing Public Ports on $TARGET_IP (von extern prüfen!) ---" for port in "${PORTS_PUBLIC[@]}"; do echo " - Bitte prüfen Sie Port $port manuell von außerhalb des Netzwerks." done ``` --- ### **Teil 4: Entwicklungs- vs. Produktions-Workflow** Dieses Kapitel definiert die verbindlichen Regeln für die Weiterentwicklung der GTM-Engine nach der Migration, um maximale Stabilität und Sicherheit des Produktivsystems zu gewährleisten. #### **1. Grundprinzipien: Getrennte Welten** * **Regel 1: Keine Entwicklung in der Produktion.** Auf der Wackler-VM (`docker1`) wird niemals Code direkt bearbeitet, experimentiert oder getestet. Sie ist ausschließlich für den Betrieb der stabilen Softwareversion vorgesehen. * **Regel 2: Getrennte Konfiguration.** Jede Umgebung hat ihre eigene Konfigurationsdatei. * **Produktion (Wackler):** `.env` – Enthält alle echten API-Schlüssel und Endpunkte. * **Entwicklung (Synology):** `.env.dev` (oder eine Kopie der `.env`) – Verwendet Test-Schlüssel, Sandbox-Endpunkte und Dummy-Werte. * **Regel 3: Die Produktionsdatenbank ist heilig.** Die produktiven Docker-Volumes (`explorer_db_data` etc.) werden niemals für Entwicklungszwecke angetastet. Lokale Entwicklung findet gegen eine separate, lokale Test-Datenbank statt. #### **2. Umgang mit Live-Daten & Aktionen** **a) SuperOffice Webhook** * **Problem:** Es darf nur einen aktiven Webhook geben, um Dateninkonsistenzen zu vermeiden. * **Lösung:** 1. **Produktion:** Der Webhook (`https:///connector/webhook`) wird bei SuperOffice registriert. In der `.env` ist das `WEBHOOK_SECRET_TOKEN` gesetzt. 2. **Entwicklung:** In der `.env.dev` wird das `WEBHOOK_SECRET_TOKEN` auskommentiert (`#WEBHOOK_SECRET_TOKEN=...`). Der Connector ist somit "taub" für externe Anrufe. 3. **Testen in der Entwicklung:** Um realistische Tests durchzuführen, wird eine Umgebungsvariable `LOG_WEBHOOKS=true` im **produktiv-Connector** gesetzt. Dieser schreibt dann den Body jedes eingehenden Webhooks in die Docker-Logs. Diese JSON-Payloads können kopiert werden, um mit einem Skript (`curl`) gezielte, manuelle Tests gegen die lokale Entwicklungsumgebung zu fahren. **b) E-Mail-Versand (Lead Engine & Co.)** * **Problem:** Das Entwicklungssystem darf unter keinen Umständen E-Mails an echte Kunden oder Kontakte senden. * **Lösung: Der "Safety Override"** 1. **Produktion:** Die echten MS Graph API Credentials (`INFO_...`) sind in der `.env` gesetzt. 2. **Entwicklung:** Die MS Graph Credentials in der `.env.dev` sind auskommentiert oder mit Dummy-Werten belegt. 3. **Sicherer Test-Modus:** Eine neue Umgebungsvariable `DEV_MODE_EMAIL_RECIPIENT` wird implementiert. * Wenn diese Variable in der `.env.dev` gesetzt ist (z.B. `DEV_MODE_EMAIL_RECIPIENT=ihre.test@adresse.de`), leitet der Code **alle** ausgehenden E-Mails an diese eine Adresse um. * **Test-Prozess:** Für einen E-Mail-Test werden in der `.env.dev` temporär die echten MS Graph Credentials eingetragen, `DEV_MODE_EMAIL_RECIPIENT` gesetzt, der Test durchgeführt und danach werden die Credentials **sofort wieder entfernt/auskommentiert**. #### **3. Deployment-Prozess: Von der Entwicklung zur Produktion** Der Prozess, um neuen, getesteten Code sicher auf das Produktivsystem zu bringen, ist wie folgt: 1. **Entwicklung (Synology):** * Ein neues Feature wird entwickelt und lokal gegen die Test-Datenbank getestet. * Änderungen werden committet und in das **lokale Gitea auf der Synology** gepusht (`git push`). 2. **Deployment (Wackler VM):** * Verbindung zur Wackler-VM via SSH. * Ins Projektverzeichnis navigieren (`/opt/gtm-engine`). * Den neuesten stabilen Code vom Entwicklungs-Gitea holen: `git pull synology main`. * Die Docker-Container mit dem neuen Code neu bauen und starten: `docker compose up -d --build`. 3. **Netzwerkanforderung für Deployment:** * Für den `git pull`-Befehl muss die Wackler-VM (`10.10.81.2`) auf den **Gitea-Port (TCP 3000) der Synology-Diskstation** zugreifen können. Dies muss einmalig im Netzwerk konfiguriert werden. --- ### **Teil 5: Alternative - Single-Host-Setup (Dev & Prod auf einer VM)** Dieses Szenario beschreibt den wahrscheinlicheren Fall, dass die gesamte Arbeit (Entwicklung und Produktion) auf der von der IT bereitgestellten VM (`docker1`) stattfinden muss. Der Ansatz wandelt sich von "physischer Trennung" zu **"logischer Trennung mit starker Isolation"**. #### **1. Grundkonzept: Schalldichte Räume** Auf der VM werden zwei komplett isolierte Umgebungen parallel betrieben. Docker ist für dieses Szenario optimiert und gewährleistet die Trennung von Code, Konfiguration, Ports und vor allem Daten. * **Produktionsumgebung (`prod`):** Läuft stabil mit dem geprüften Code und greift auf die produktiven Daten zu. * **Entwicklungsumgebung (`dev`):** Dient zum Entwickeln und Testen. Hat eine eigene Konfiguration und eine komplett separate Test-Datenbank. #### **2. Implementierung** **a) Verzeichnisstruktur** Eine saubere Ordnerstruktur ist die Basis für die Trennung. ``` /opt/gtm-engine/ ├── dev/ │ ├── docker-compose.yml │ ├── .env │ └── (kompletter Code des Projekts...) │ └── prod/ ├── docker-compose.yml ├── .env └── (kompletter Code des Projekts...) ``` **b) Auflösung von Port-Konflikten** Zwei Stacks können nicht dieselben Ports nutzen. Die `dev`-Umgebung nutzt daher verschobene Ports. | Dienst | Produktions-Port (in `prod/docker-compose.yml`) | Entwicklungs-Port (in `dev/docker-compose.yml`) | | :--- | :---: | :---: | | Gateway | `8090:80` | `9090:80` | | Webhook | `8003:8003` | `9003:8003` | | GTM | `8094:3005` | `9094:3005` | So ist das **Produktivsystem** unter `http://10.10.81.2:8090` und das **Entwicklungssystem** unter `http://10.10.81.2:9090` erreichbar. **c) Garantierte Datenbank-Isolation** **Dies ist der wichtigste Punkt:** Docker stellt sicher, dass die Datenbanken niemals vermischt werden können. Docker Compose erstellt benannte Volumes mit dem Verzeichnisnamen als Präfix. * `docker compose up` im Ordner `prod/` erzeugt das Volume `prod_explorer_db_data`. * `docker compose up` im Ordner `dev/` erzeugt das Volume `dev_explorer_db_data`. Diese beiden Volumes sind **vollständig voneinander isolierte Container** auf der Festplatte. Ein Zugriff von `dev` auf `prod`-Daten ist technisch unmöglich. **Ihre Anforderung, dass die Produktionsdatenbank sicher ist, wird hiermit zu 100% erfüllt.** #### **3. Vereinfachter Workflow auf einer Maschine** Das neue Gitea (auf Port 3000) wird zur zentralen "Source of Truth". 1. **Entwicklung:** * Sie arbeiten im Verzeichnis `/opt/gtm-engine/dev/`. * Sie ändern den Code und testen ihn, indem Sie den `dev`-Stack starten: `cd /opt/gtm-engine/dev/ && docker compose up -d --build` * Sie verifizieren die Änderungen im Browser unter `http://10.10.81.2:9090`. * Wenn alles passt, committen Sie und pushen zum Gitea auf derselben Maschine: `git push`. 2. **Deployment (Release in die Produktion):** * Wechseln Sie in das Produktionsverzeichnis: `cd /opt/gtm-engine/prod/`. * Holen Sie den neuen, im `dev`-Zweig getesteten Code aus Gitea: `git pull`. * Aktualisieren Sie den Produktions-Stack: `docker compose up -d --build`. Dieser Prozess ist sicher, schnell und wiederholbar, da er nur aus Standard-Git- und Docker-Befehlen besteht. --- ### **UMZUG Live - Lessons Learned (März 2026)** Der reale Umzug von der Synology auf die Wackler-VM (`docker1`) hat gezeigt, dass die Theorie gut war, die Praxis aber spezifische Hürden bereithielt. Diese Lektionen sind kritisch für alle zukünftigen Deployments: #### **1. Die Git-Historien-Falle (Packfile / Timeout Error)** * **Problem:** Versuche, das Repository per `git clone` oder über die Gitea-Migrations-Funktion umzuziehen, brachen reproduzierbar mit `RPC failed; HTTP 504` oder `fatal: expected 'packfile'` ab. * **Ursache:** Das lokale `.git` Verzeichnis war auf **1,4 Gigabyte** angewachsen, da in der Vergangenheit versehentlich große MP3-Dateien committet wurden. Auch nach dem Löschen verbleiben diese in der Historie und blockieren den Transfer über Proxies. * **Lösung:** Radikale Bereinigung der Historie via `git filter-branch` (oder `git filter-repo`) für den Ordner `uploads_audio/`, gefolgt von einer aggressiven Garbage Collection (`git gc --prune=now --aggressive`). * **Ergebnis:** Schrumpfung des Repos von 1,4 GB auf **130 MB**. * **Lesson:** Bei Git-Transfer-Fehlern zuerst die Größe des `.git` Ordners prüfen. #### **2. Der "Filter-Branch" Nebeneffekt (.env Schutz)** * **Problem:** Nach der Git-Bereinigung schienen ungetrackte Dateien (wie `.env` und `volume_backups/`) plötzlich verschwunden. * **Ursache:** `git filter-branch` erzwingt einen harten Reset auf den bereinigten Stand. Dateien, die in der `.gitignore` stehen, werden dabei oft aus dem Arbeitsverzeichnis entfernt. * **Lösung:** Wiederherstellung aus einem zuvor erstellten `.tar.gz`-Backup des gesamten Projektverzeichnisses. * **Lesson:** Führe niemals tiefe Git-Eingriffe ohne ein physisches Dateibackup der ungetrackten Dateien durch. #### **3. Das "Transit-Repo" Muster für Secrets** * **Problem:** Sicherer Transfer der `.env` und Datenbanken ohne Einchecken in das Haupt-Repo und ohne Zugriff auf externe Transfer-Dienste (Firewall-Blockade). * **Lösung:** Erstellung eines temporären, privaten Gitea-Repositorys namens `transit` auf dem Ziel-System. Hochladen des verschlüsselten Backups über die Gitea-Weboberfläche und anschließendes Klonen/Entpacken auf der VM. Danach sofortige Löschung des `transit` Repos. * **Lesson:** Gitea ist das beste Transit-Medium für große Files hinter restriktiven Firewalls. #### **4. Docker Build Context & Berechtigungen** * **Problem:** `docker compose up --build` brach ab mit: `failed to solve: error from sender: open /volume_backups: permission denied`. * **Ursache:** Docker versucht beim Bauen das gesamte Verzeichnis einzulesen. Ordner, die dem `root` User gehören (z.B. durch Gemini-Aktionen erstellt), blockieren den Prozess. * **Lösung:** 1. Berechtigungen korrigieren: `sudo chown -R $USER:$USER volume_backups/` 2. Ordner in der `.dockerignore` ausschließen, damit er gar nicht erst eingelesen wird. * **Lesson:** Alles, was nicht in ein Container-Image gehört, **muss** in die `.dockerignore`. #### **5. Vite & TypeScript Build-Tücken** * **Problem:** Der Frontend-Build schlug fehl, weil die `tsconfig.json` im Container nicht gefunden wurde. * **Ursache:** `COPY . .` verhält sich in komplexen Verzeichnisstrukturen manchmal unvorhersehbar. * **Lösung:** Explizites Kopieren aller Konfigurationsdateien im Dockerfile: `COPY tsconfig.json tsconfig.node.json tsconfig.app.json vite.config.ts ./` direkt vor dem Build-Schritt. * **Lesson:** Verlasse dich beim Build nicht auf Wildcards; kopiere essenzielle Config-Files explizit.