Brancheneinstufung2/RELOCATION.md

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.
8004	lead-engine	Public	Lead Engine API (für Buchungs-Links).

---

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.

---

⚠️ Kritische Lehren (Post-Mortem 07.03.2026)

Der Umzug am Montag muss zwingend diese Punkte beachten, um den "Totalausfall" von heute zu vermeiden:

1. Datenbank-Schema-Falle

Problem: Alte .db-Dateien (Backups) haben oft nicht alle Spalten, die der aktuelle Code erwartet. Lösung: Nach dem Starten der Container auf der neuen VM muss das Migrations-Skript ausgeführt werden:

docker exec -it company-explorer python /app/fix_missing_columns.py

Dies repariert Tabellen für Companies, Industries und Contacts (inkl. Unsubscribe-Tokens).

2. Docker Volumes vs. Bind Mounts

Regel: Datenbanken werden NIEMALS mehr direkt auf einen Host-Pfad gemountet. Grund: Permission-Errors und SQLite-Locks ("Database is locked") auf Netzwerk-Dateisystemen (Synology/NFS). Vorgehen: Nutzung von benannten Volumes (explorer_db_data, connector_db_data, lead_engine_data).

3. Daten-Injektion (Der "Rescue"-Befehl)

Um bestehende Daten in die neuen Volumes zu bekommen, nutzt man diesen Befehl:

# Beispiel für den Company Explorer
docker cp ./my_local_backup.db company-explorer:/data/companies_v3_fixed_2.db

4. Streamlit Proxy-Konfiguration

Problem: Streamlit (Lead Engine) verliert die Verbindung unter Sub-Pfaden (/lead/). Lösung:

• Dockerfile: --server.baseUrlPath=/lead ist Pflicht.
• Nginx: proxy_http_version 1.1 und Upgrade-Header müssen gesetzt sein.

---

Verbindlicher Migrationsplan (Montag)

Phase 1: Vorbereitung

1. git push auf Synology (aktuellster Stand d1b77fd2).
2. .env Datei sichern (enthält alle heute stabilisierten Keys!).

Phase 2: Deployment auf docker1

1. Repo klonen: git clone ... /opt/gtm-engine
2. .env anlegen und befüllen.
3. Starten: docker compose up -d --build
4. Schema-Check: docker exec -it company-explorer python /app/fix_missing_columns.py ausführen.

Phase 3: Datenrettung (Falls nötig)

1. Datenbank-Dumps vom Wochenende via docker cp in die Volumes schieben.
2. Webhook-Status prüfen: docker exec -it connector-superoffice python /app/register_webhook.py.

---

Aktuelle Offene Todos (Priorisiert)

1. Lead Engine: Microsoft Graph Credentials in .env ergänzen (401 Fehler beheben).
2. n8n: Workflow-Export von Synology und Import auf neuer Instanz.
3. Styling: Frontend-CSS im Company Explorer verifizieren (Build läuft wieder, aber UI-Check nötig).