168 lines
9.6 KiB
Markdown
168 lines
9.6 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.
|
|
|
|
---
|
|
|
|
**Zusammenfassende Handlungsempfehlung für die IT:**
|
|
|
|
1. **Firewall-Regeln (eingehend):** Bitte öffnen Sie die Ports `3000`, `2222`, `8090`, `8003`, `8501`, `8004`, `8002` und `5173` für die Ziel-IP `10.10.81.2`.
|
|
2. **Firewall-Regeln (ausgehend):** Stellen Sie sicher, dass die VM ausgehende HTTPS-Verbindungen (Port 443) zu beliebigen Zielen im Internet aufbauen kann.
|
|
3. **Reverse Proxy (Optional, aber empfohlen):** Planen Sie die Einrichtung eines Reverse Proxys (z.B. Nginx, Traefik) mit SSL-Zertifikaten für den Zugriff auf die Web-Anwendungen, insbesondere für den Haupt-Port `8090`.
|
|
|
|
---
|
|
|
|
### **Anhang: Migrationsvorschlag der IT**
|
|
|
|
Das Folgende ist der initial vorgeschlagene Migrationsprozess seitens der IT.
|
|
|
|
```bash
|
|
# Auf dem Quellsystem (Synology)
|
|
cd /volume1/homes/Floke/python
|
|
tar czf lead-engine-app.tgz brancheneinstufung/
|
|
|
|
docker images
|
|
docker save <image-name>:<tag> > lead-engine-image.tar
|
|
|
|
# Manuelle Übertragung via USB-Stick
|
|
|
|
# Auf dem Zielsystem (docker1)
|
|
docker load < lead-engine-image.tar
|
|
mkdir -p /srv/lead-engine
|
|
tar xzf lead-engine-app.tgz -C /srv/lead-engine
|
|
|
|
# Und starten
|
|
```
|
|
|
|
---
|
|
|
|
### **Empfohlener Migrationsplan (Sicherer Ansatz)**
|
|
|
|
Der Vorschlag der IT ist für einen einzelnen, einfachen Container geeignet, birgt jedoch für diesen komplexen Anwendungs-Stack erhebliche Risiken (Datenverlust, Konfigurationsfehler). Ein sicherer Umzug muss zwingend **Code, Konfiguration UND persistente Daten** umfassen.
|
|
|
|
**Analyse der Risiken des IT-Vorschlags:**
|
|
1. **Fokus auf nur einen Container:** Der Plan berücksichtigt nur die `lead-engine`, ignoriert aber die ca. 20 anderen, voneinander abhängigen Dienste (Gitea, Datenbanken, Proxy etc.).
|
|
2. **Fehlende persistente Daten (Größtes Risiko):** Der Plan sichert nur den Anwendungs-Code. Er ignoriert die Daten-Volumes, was zum **Totalverlust aller Git-Repositories, Datenbankinhalte und anderer kritischer Daten** führen würde.
|
|
3. **Fehlende Orchestrierung:** Die `docker-compose.yml`, das "Gehirn" des Systems, wird ignoriert. Ohne sie ist ein Starten des komplexen Stacks nicht möglich, da alle Netzwerk-Verbindungen, Port-Mappings und Volume-Zuweisungen fehlen.
|
|
|
|
**Der empfohlene, sichere Prozess:**
|
|
|
|
Der korrekte Ansatz ist, das gesamte Projektverzeichnis zu archivieren, welches alle drei Säulen (Code, Konfiguration, Daten) enthält.
|
|
|
|
**Schritt 1: Ein vollständiges Archiv auf dem Quellsystem erstellen**
|
|
Anstatt nur einen Dienst zu sichern, wird das gesamte Projekt-Stammverzeichnis, das alle Docker-Konfigurationen und Daten-Volumes enthält, als einzelnes Archiv (`.tar.gz`) zusammengefasst.
|
|
|
|
```bash
|
|
# Beispielhafter Befehl im übergeordneten Verzeichnis
|
|
# Der genaue Pfad und Name muss vor der Ausführung verifiziert werden.
|
|
tar czf GTM_ENGINE_MIGRATION_ARCHIVE.tar.gz ./DEIN_PROJEKT_ORDNER/
|
|
```
|
|
|
|
Dieses Archiv enthält:
|
|
- Den gesamten Quellcode aller Dienste.
|
|
- Die zentrale `docker-compose.yml`.
|
|
- Alle `.env`-Dateien mit API-Schlüsseln und Secrets.
|
|
- **Alle lokalen Daten-Volumes** (z.B. `./postgres:/var/lib/postgresql/data`, `./gitea:/data`, etc.), die in der `docker-compose.yml` definiert sind.
|
|
|
|
**Schritt 2: Archiv auf das Zielsystem übertragen**
|
|
Die erstellte Archivdatei (`GTM_ENGINE_MIGRATION_ARCHIVE.tar.gz`) wird auf die neue VM `docker1` übertragen (z.B. via `scp` oder `rsync`).
|
|
|
|
**Schritt 3: Auf dem Zielsystem wiederherstellen und starten**
|
|
Auf der neuen VM sind nur zwei Befehle nötig:
|
|
```bash
|
|
# 1. Archiv entpacken
|
|
tar xzf GTM_ENGINE_MIGRATION_ARCHIVE.tar.gz
|
|
|
|
# 2. Den kompletten Stack starten
|
|
cd DEIN_PROJEKT_ORDNER/
|
|
docker compose up -d
|
|
```
|
|
---
|
|
### **Migrations-Vorbereitung: Status & Offene Todos (Stand: 2026-03-05)**
|
|
|
|
**Aktueller Status:**
|
|
Wir haben mit der Vorbereitung des "Greenfield" Migrations-Archivs begonnen, wobei der Fokus zunächst auf einem kritischen Sicherheits-Audit lag.
|
|
|
|
**Erreichte Meilensteine:**
|
|
* **Sicherheits-Audit gestartet:** Eine Liste potenziell unsicherer, fest codierter Token-Dateien wurde erstellt.
|
|
* **Erster Key erfolgreich bereinigt:** Die Datei `api_key.txt` (ein alter OpenAI-Key) wurde erfolgreich und vollständig aus dem Dateisystem **und** der gesamten Git-Historie entfernt.
|
|
|
|
**Wichtige Erkenntnis:**
|
|
Der Prozess zur Bereinigung der Git-Historie ist sehr zeitaufwändig und muss für die verbleibenden Dateien effizienter gestaltet werden.
|
|
|
|
---
|
|
|
|
**Offene Todos / Nächste Schritte:**
|
|
|
|
1. **Effiziente Bereinigung der restlichen Token-Dateien (Batch-Prozess):**
|
|
* **Analyse:** Alle verbleibenden Token-Dateien aus der initialen Liste prüfen.
|
|
* **Validierung:** Sicherstellen, dass alle noch benötigten Schlüssel in der zentralen `.env`-Datei vorhanden sind.
|
|
* **Batch-Entfernung:** Alle nicht mehr benötigten Dateien in einem einzigen `git filter-repo`-Befehl aus der Git-Historie entfernen, um den Zeitaufwand zu minimieren.
|
|
* **Force Push:** Die bereinigte Historie auf den Git-Server pushen.
|
|
|
|
2. **Dokumentation strukturieren:**
|
|
* Einen zentralen Ordner `/app/docs` für allgemeine Projektdokumentation anlegen.
|
|
* Alle allgemeinen `.md`, `.txt`, `.pdf` Dateien aus dem Root-Verzeichnis dorthin verschieben.
|
|
* Spezifische Dokumentationen in die jeweiligen Projekt-Unterordner verschieben (z.B. `connector-superoffice/README.md`).
|
|
|
|
3. **Projekte und Altlasten archivieren:**
|
|
* Ein Verzeichnis `/app/ARCHIVE_vor_migration` erstellen.
|
|
* Den Ordner `_legacy_gsheet` und andere identifizierte Fremdprojekte dorthin verschieben.
|
|
|
|
4. **Finale Konfiguration und Verpackung:**
|
|
* **`docker-compose.yml` bereinigen:** Die nicht zu migrierenden Dienste (`gitea`, `duckdns`, `dns-monitor`) aus der Konfigurationsdatei entfernen.
|
|
* **Letzte Prüfung:** Eine finale Überprüfung des aufgeräumten Projektverzeichnisses durchführen.
|
|
* **Migrations-Archiv erstellen:** Das finale, saubere `.tar.gz`-Archiv des gesamten Projektordners erstellen.
|
|
|
|
Docker Compose wird die Konfiguration lesen, alle Dienste mit ihren Daten und Netzwerk-Verbindungen korrekt starten und den Zustand des Quellsystems exakt replizieren.
|