103 lines
6.3 KiB
Markdown
103 lines
6.3 KiB
Markdown
### **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)**
|
|
- [x] `docker-compose.yml` reparieren (Named Volumes, Healthchecks, Env Vars).
|
|
- [x] Dockerfiles reparieren (PostCSS/Tailwind Build-Fehler behoben).
|
|
- [x] `.env.example` erstellt.
|
|
- [x] 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.
|