Brancheneinstufung2/RELOCATION.md

Anforderungsdokument (Version 2): Docker-Migration von Synology nach Ubuntu VM (docker1)

Zweck: Dieses Dokument listet alle notwendigen Port-Freigaben und Netzwerk-Anforderungen für den Umzug des internen Docker-Anwendungsstacks auf die neue VM docker1 (IP: 10.10.81.2). Diese Version basiert auf der Analyse aller aktiven Docker-Container vom Quellsystem.

Teil 1: Externe Port-Freigaben (Firewall)

Die folgenden Ports müssen auf der Firewall für den eingehenden Verkehr zur VM 10.10.81.2 geöffnet werden.

Host-Port	Ziel-Dienst (Container)	Zweck / Beschreibung	Kritikalität
3000	gitea	Gitea Web UI. Zugriff auf die Weboberfläche des Git-Servers.	Hoch
2222	gitea	Gitea Git via SSH. Ermöglicht git clone, push, pull über SSH. (Auf dem Altsystem Port 32768, wird hier auf einen Standard-Port gelegt).	Hoch
8090	gateway_proxy (Nginx)	Zentraler App-Hub. Reverse-Proxy, der den Zugriff auf alle Web-Anwendungen (Dashboard, B2B, Market-Intel etc.) steuert und mit Passwort schützt.	Hoch
8003	connector-superoffice	SuperOffice Webhook-Empfänger. Muss aus dem Internet (von SuperOffice-Servern) erreichbar sein.	Hoch
8501	lead-engine	Lead Engine UI. Web-Interface der Lead Engine (Streamlit).	Mittel
8004	lead-engine (API)	Lead Engine API. Für externe Integrationen wie Kalender/Buchungs-Links.	Mittel
8002	heatmap-tool-backend	Heatmap Tool Backend. API für das Heatmap-Visualisierungs-Tool.	Niedrig
5173	heatmap-tool-frontend	Heatmap Tool Frontend. Direktzugriff auf die UI des Heatmap-Tools (typ. für Entwicklung).	Niedrig

Empfehlung: Der gesamte externe Zugriff sollte idealerweise über einen vorgeschalteten, von der IT verwalteten Reverse-Proxy mit SSL-Terminierung (HTTPS) laufen, um die Sicherheit zu erhöhen.

---

Teil 2: Interne Port-Nutzung (Host-System)

Die folgenden Ports werden von den Docker-Containern auf dem Host-System (docker1) belegt. Sie müssen nicht extern freigegeben werden, aber sie dürfen auf dem Host nicht von anderen Diensten belegt sein.

Host-Port	Ziel-Dienst (Container)	Zweck
8000	company-explorer	Haupt-API für Unternehmensdaten, wird vom App-Hub (gateway_proxy) genutzt.
8001	transcription-app	API und UI für das Transkriptions-Tool, wird vom App-Hub genutzt.

---

Teil 3: Externe Service-Abhängigkeiten (Ausgehender Verkehr)

Die VM muss in der Lage sein, ausgehende Verbindungen zu den folgenden externen Diensten aufzubauen.

Dienst	Zweck	Protokoll/Port
SuperOffice API	CRM-Synchronisation	HTTPS / 443
Google APIs	SerpAPI, Gemini AI	HTTPS / 443
Notion API	Wissensdatenbank-Sync	HTTPS / 443
DuckDNS	Dynamisches DNS	HTTPS / 443
GitHub / Docker Hub / etc.	Herunterladen von Docker-Images, Software-Paketen	HTTPS / 443
Öffentliche DNS-Server	Namensauflösung (z.B. 8.8.8.8)	DNS / 53 (UDP/TCP)

---

Teil 4: Netzwerk-Architektur & Kommunikation (Intern)

• Inter-Container-Kommunikation: Alle Container sind über ein internes Docker-Bridge-Netzwerk verbunden. Sie können sich gegenseitig über ihre Dienstnamen erreichen (z.B. connector-superoffice kann company-explorer über http://company-explorer:8000 erreichen).
• Keine speziellen Netzwerkregeln: Es sind keine komplexen internen Firewall-Regeln zwischen den Containern erforderlich. Die Kommunikation innerhalb des Docker-Netzwerks sollte uneingeschränkt möglich sein.

---

⚠️ Post-Mortem & Kritische Lehren (März 2026)

Hintergrund: Am 07.03.2026 führte ein Versuch, das Legacy-System auf der Synology für die Migration "aufzuräumen", zu massiver Instabilität und temporärem Datenverlust.

Identifizierte Fehlerquellen ("Root Causes"):

1. Destruktive Bereinigung: git clean -fdx löschte untracked Datenbanken.
2. Dateisystem-Inkompatibilität: Bind Mounts auf Synology führten zu Berechtigungsfehlern ("Database Locked").
3. Fehlende Isolation: Änderungen wurden am "lebenden Objekt" vorgenommen.

Erfolgreiche Stabilisierung (Status Quo):

• Docker Volumes: Alle Datenbanken laufen jetzt auf benannten Docker-Volumes (connector_db_data, explorer_db_data). Bind Mounts sind Geschichte.
• Healthchecks: Nginx wartet nun korrekt auf die Gesundheit der Backend-Services.
• Environment: Alle Secrets kommen aus der .env, keine Key-Files mehr im Repo.
• Daten: Die companies_v3_fixed_2.db konnte via Synology Drive Versioning wiederhergestellt und per docker cp injiziert werden.

Neue Richtlinien für die Migration ("Never Again Rules"):

1. Immutable Infrastructure: Wir ändern NICHTS mehr an der Konfiguration auf der Synology. Der dortige Stand ist eingefroren.
2. Code-Only Transfer: Die neue Umgebung auf docker1 wird ausschließlich durch git clone aufgebaut.
3. Docker Volumes Only: Datenbanken werden niemals mehr direkt auf das Host-Dateisystem gemountet.
4. Environment Isolation: Secrets existieren ausschließlich in der .env Datei.

---

Revidierter Migrationsplan (Clean Slate)

Phase 1: Code & Config Freeze (Abgeschlossen)

• docker-compose.yml reparieren (Named Volumes, Healthchecks, Env Vars).
• Dockerfiles reparieren (PostCSS/Tailwind Build-Fehler behoben).
• .env.example erstellt.
• Nginx Konfiguration stabilisiert.

Phase 2: Deployment auf docker1

1. Repository klonen: git clone <repo-url> /opt/gtm-engine
2. Environment einrichten: cp .env.example .env und echte Werte eintragen.
3. Starten: docker compose up -d --build
4. Datenimport (Optional): Falls nötig, Datenbanken via docker cp in die Volumes kopieren.

---

Aktuelle Offene Todos (Priorisiert)

1. UI Styling: Das Frontend des Company Explorers hat keine Stylesheets (PostCSS temporär deaktiviert, um Build zu ermöglichen). Muss auf der neuen VM sauber gelöst werden.
2. Datenverifizierung: Prüfen, ob die wiederhergestellte Datenbank vollständig ist.
3. Migration: Den Umzug auf docker1 nach dem neuen Plan durchführen.