82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
### **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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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). |