diff --git a/RELOCATION.md b/RELOCATION.md index 184d57e3..3daadc8e 100644 --- a/RELOCATION.md +++ b/RELOCATION.md @@ -152,8 +152,188 @@ for port in "${PORTS_INTRANET[@]}"; do fi done + + echo -e "\n--- Testing Public Ports on $TARGET_IP (von extern prüfen!) ---" + for port in "${PORTS_PUBLIC[@]}"; do + echo " - Bitte prüfen Sie Port $port manuell von außerhalb des Netzwerks." + done -``` \ No newline at end of file + +``` + + + +--- + + + +### **Teil 4: Entwicklungs- vs. Produktions-Workflow** + + + +Dieses Kapitel definiert die verbindlichen Regeln für die Weiterentwicklung der GTM-Engine nach der Migration, um maximale Stabilität und Sicherheit des Produktivsystems zu gewährleisten. + + + +#### **1. Grundprinzipien: Getrennte Welten** + + + +* **Regel 1: Keine Entwicklung in der Produktion.** Auf der Wackler-VM (`docker1`) wird niemals Code direkt bearbeitet, experimentiert oder getestet. Sie ist ausschließlich für den Betrieb der stabilen Softwareversion vorgesehen. + +* **Regel 2: Getrennte Konfiguration.** Jede Umgebung hat ihre eigene Konfigurationsdatei. + + * **Produktion (Wackler):** `.env` – Enthält alle echten API-Schlüssel und Endpunkte. + + * **Entwicklung (Synology):** `.env.dev` (oder eine Kopie der `.env`) – Verwendet Test-Schlüssel, Sandbox-Endpunkte und Dummy-Werte. + +* **Regel 3: Die Produktionsdatenbank ist heilig.** Die produktiven Docker-Volumes (`explorer_db_data` etc.) werden niemals für Entwicklungszwecke angetastet. Lokale Entwicklung findet gegen eine separate, lokale Test-Datenbank statt. + + + +#### **2. Umgang mit Live-Daten & Aktionen** + + + +**a) SuperOffice Webhook** + + + +* **Problem:** Es darf nur einen aktiven Webhook geben, um Dateninkonsistenzen zu vermeiden. + +* **Lösung:** + + 1. **Produktion:** Der Webhook (`https:///connector/webhook`) wird bei SuperOffice registriert. In der `.env` ist das `WEBHOOK_SECRET_TOKEN` gesetzt. + + 2. **Entwicklung:** In der `.env.dev` wird das `WEBHOOK_SECRET_TOKEN` auskommentiert (`#WEBHOOK_SECRET_TOKEN=...`). Der Connector ist somit "taub" für externe Anrufe. + + 3. **Testen in der Entwicklung:** Um realistische Tests durchzuführen, wird eine Umgebungsvariable `LOG_WEBHOOKS=true` im **produktiv-Connector** gesetzt. Dieser schreibt dann den Body jedes eingehenden Webhooks in die Docker-Logs. Diese JSON-Payloads können kopiert werden, um mit einem Skript (`curl`) gezielte, manuelle Tests gegen die lokale Entwicklungsumgebung zu fahren. + + + +**b) E-Mail-Versand (Lead Engine & Co.)** + + + +* **Problem:** Das Entwicklungssystem darf unter keinen Umständen E-Mails an echte Kunden oder Kontakte senden. + +* **Lösung: Der "Safety Override"** + + 1. **Produktion:** Die echten MS Graph API Credentials (`INFO_...`) sind in der `.env` gesetzt. + + 2. **Entwicklung:** Die MS Graph Credentials in der `.env.dev` sind auskommentiert oder mit Dummy-Werten belegt. + + 3. **Sicherer Test-Modus:** Eine neue Umgebungsvariable `DEV_MODE_EMAIL_RECIPIENT` wird implementiert. + + * Wenn diese Variable in der `.env.dev` gesetzt ist (z.B. `DEV_MODE_EMAIL_RECIPIENT=ihre.test@adresse.de`), leitet der Code **alle** ausgehenden E-Mails an diese eine Adresse um. + + * **Test-Prozess:** Für einen E-Mail-Test werden in der `.env.dev` temporär die echten MS Graph Credentials eingetragen, `DEV_MODE_EMAIL_RECIPIENT` gesetzt, der Test durchgeführt und danach werden die Credentials **sofort wieder entfernt/auskommentiert**. + + + +#### **3. Deployment-Prozess: Von der Entwicklung zur Produktion** + + + +Der Prozess, um neuen, getesteten Code sicher auf das Produktivsystem zu bringen, ist wie folgt: + + + +1. **Entwicklung (Synology):** + + * Ein neues Feature wird entwickelt und lokal gegen die Test-Datenbank getestet. + + * Änderungen werden committet und in das **lokale Gitea auf der Synology** gepusht (`git push`). + + + +2. **Deployment (Wackler VM):** + + * Verbindung zur Wackler-VM via SSH. + + * Ins Projektverzeichnis navigieren (`/opt/gtm-engine`). + + * Den neuesten stabilen Code vom Entwicklungs-Gitea holen: `git pull synology main`. + + * Die Docker-Container mit dem neuen Code neu bauen und starten: `docker compose up -d --build`. + + + +3. **Netzwerkanforderung für Deployment:** + + * Für den `git pull`-Befehl muss die Wackler-VM (`10.10.81.2`) auf den **Gitea-Port (TCP 3000) der Synology-Diskstation** zugreifen können. Dies muss einmalig im Netzwerk konfiguriert werden. + +--- + +### **Teil 5: Alternative - Single-Host-Setup (Dev & Prod auf einer VM)** + +Dieses Szenario beschreibt den wahrscheinlicheren Fall, dass die gesamte Arbeit (Entwicklung und Produktion) auf der von der IT bereitgestellten VM (`docker1`) stattfinden muss. Der Ansatz wandelt sich von "physischer Trennung" zu **"logischer Trennung mit starker Isolation"**. + +#### **1. Grundkonzept: Schalldichte Räume** + +Auf der VM werden zwei komplett isolierte Umgebungen parallel betrieben. Docker ist für dieses Szenario optimiert und gewährleistet die Trennung von Code, Konfiguration, Ports und vor allem Daten. + +* **Produktionsumgebung (`prod`):** Läuft stabil mit dem geprüften Code und greift auf die produktiven Daten zu. +* **Entwicklungsumgebung (`dev`):** Dient zum Entwickeln und Testen. Hat eine eigene Konfiguration und eine komplett separate Test-Datenbank. + +#### **2. Implementierung** + +**a) Verzeichnisstruktur** + +Eine saubere Ordnerstruktur ist die Basis für die Trennung. + +``` +/opt/gtm-engine/ +├── dev/ +│ ├── docker-compose.yml +│ ├── .env +│ └── (kompletter Code des Projekts...) +│ +└── prod/ + ├── docker-compose.yml + ├── .env + └── (kompletter Code des Projekts...) +``` + +**b) Auflösung von Port-Konflikten** + +Zwei Stacks können nicht dieselben Ports nutzen. Die `dev`-Umgebung nutzt daher verschobene Ports. + +| Dienst | Produktions-Port (in `prod/docker-compose.yml`) | Entwicklungs-Port (in `dev/docker-compose.yml`) | +| :--- | :---: | :---: | +| Gateway | `8090:80` | `9090:80` | +| Webhook | `8003:8003` | `9003:8003` | +| GTM | `8094:3005` | `9094:3005` | + +So ist das **Produktivsystem** unter `http://10.10.81.2:8090` und das **Entwicklungssystem** unter `http://10.10.81.2:9090` erreichbar. + +**c) Garantierte Datenbank-Isolation** + +**Dies ist der wichtigste Punkt:** Docker stellt sicher, dass die Datenbanken niemals vermischt werden können. Docker Compose erstellt benannte Volumes mit dem Verzeichnisnamen als Präfix. + +* `docker compose up` im Ordner `prod/` erzeugt das Volume `prod_explorer_db_data`. +* `docker compose up` im Ordner `dev/` erzeugt das Volume `dev_explorer_db_data`. + +Diese beiden Volumes sind **vollständig voneinander isolierte Container** auf der Festplatte. Ein Zugriff von `dev` auf `prod`-Daten ist technisch unmöglich. **Ihre Anforderung, dass die Produktionsdatenbank sicher ist, wird hiermit zu 100% erfüllt.** + +#### **3. Vereinfachter Workflow auf einer Maschine** + +Das neue Gitea (auf Port 3000) wird zur zentralen "Source of Truth". + +1. **Entwicklung:** + * Sie arbeiten im Verzeichnis `/opt/gtm-engine/dev/`. + * Sie ändern den Code und testen ihn, indem Sie den `dev`-Stack starten: + `cd /opt/gtm-engine/dev/ && docker compose up -d --build` + * Sie verifizieren die Änderungen im Browser unter `http://10.10.81.2:9090`. + * Wenn alles passt, committen Sie und pushen zum Gitea auf derselben Maschine: `git push`. + +2. **Deployment (Release in die Produktion):** + * Wechseln Sie in das Produktionsverzeichnis: `cd /opt/gtm-engine/prod/`. + * Holen Sie den neuen, im `dev`-Zweig getesteten Code aus Gitea: `git pull`. + * Aktualisieren Sie den Produktions-Stack: `docker compose up -d --build`. + +Dieser Prozess ist sicher, schnell und wiederholbar, da er nur aus Standard-Git- und Docker-Befehlen besteht. +