docs: KI-Kommentare für deploy.py und docker-compose.yaml — 100% zukunftssicher

docker-compose.yaml

@@ -1,3 +1,32 @@
+# =============================================================================
+# docker-compose.yaml — LeoCRM Multi-Container Setup
+#
+# ⚠️ KI / AGENT HINWEISE — BITTE VOR ÄNDERUNGEN LESEN ⚠️
+#
+# ARCHITEKTUR: Einzelner docker-compose Stack für Coolify (build_pack=dockercompose)
+# Coolify liest diese Datei aus dem Git-Repo und baut alle 4 Container in einem
+# gemeinsamen Stack. Alle Container teilen sich ein Docker-Netzwerk.
+#
+# ❌ NICHT tun:
+# - Service-Namen mit Bindestrich (crm-app, crm-worker). Coolify konvertiert
+#   Bindestriche zu Unterstrichen in docker_compose_domains → kein Match →
+#   keine Traefik-Labels → 503 Fehler. Verwende Unterstriche: crm_app, crm_worker.
+# - Datei als docker-compose.yml (mit .yml) speichern. Coolify sucht .yaml.
+# - :443 an Domain anhängen. Das führt zu leeren Host() Traefik-Labels.
+# - Eigene networks definieren. Coolify verwaltet das Netzwerk automatisch.
+# - container_name setzen. Coolify generiert Container-Namen automatisch.
+#
+# ✅ RICHTIG:
+# - Service-Namen mit Unterstrichen: postgres, redis, crm_app, crm_worker
+# - SERVICE_FQDN_CRM_APP_8000 in environment für automatische Domain-Konfiguration
+# - depends_on mit condition: service_healthy für korrekte Start-Reihenfolge
+# - crm_worker depends_on crm_app (service_healthy) damit prestart.sh zuerst läuft
+#   und DB-Passwörter setzt bevor der Worker startet
+#
+# MEHRERE INSTANZEN:
+# - APP_NAME und APP_DOMAIN als ENV-Variablen im deploy.py Aufruf setzen
+# - Alle anderen Werte werden aus ENV-Variablen gelesen
+# =============================================================================
 services:
   postgres:
     image: pgvector/pgvector:pg16

scripts/deploy.py

@@ -1046,14 +1046,56 @@ def create_api_application(client: CoolifyClient, project_uuid: str,
 def deploy_initial() -> int:
     """Initial deployment: create all Coolify resources from scratch.
 
-    Creates:
+    ═══════════════════════════════════════════════════════════════════════
-    1. PostgreSQL service (pgvector/pgvector:pg16)
+    ⚠️  KI / AGENT HINWEISE — BITTE VOR ÄNDERUNGEN LESEN  ⚠️
-    2. Redis service (redis:7-alpine)
+    ═══════════════════════════════════════════════════════════════════════
-    3. API application (from Git repo)
+
-    4. Worker service (same image as API)
+    ARCHITEKTUR: Einzelner docker-compose Stack (NICHT 4 separate Ressourcen!)
-    5. Sets all ENV variables
+    ─────────────────────────────────────────────────────────────────────
-    6. Deploys API (builds image + runs migrations)
+    Dieses Script erstellt EINE Coolify Application mit build_pack=dockercompose.
-    7. Deploys Worker
+    Coolify liest docker-compose.yaml aus dem Git-Repo und baut alle 4 Container
+    (postgres, redis, crm_app, crm_worker) in einem gemeinsamen Stack.
+
+    ❌ NICHT tun:
+    - 4 separate Coolify Ressourcen erstellen (Services für PG/Redis, Application
+      für API, Service für Worker). Das funktioniert NICHT weil Coolify jedem
+      Service ein eigenes Docker-Netzwerk gibt. Die Container können sich nicht
+      per DNS erreichen → socket.gaierror: Temporary failure in name resolution.
+    - connect_to_docker_network=True setzen. Coolify kümmert sich selbst um das
+      Netzwerk innerhalb eines docker-compose Stacks.
+    - :443 an die Domain anhängen (z.B. https://crm.media-on.de:443). Das führt
+      zu leeren Host() Traefik-Labels → 503 Fehler. Siehe unten.
+    - docker-compose.yml (mit .yml) verwenden. Coolify sucht docker-compose.yaml
+      (mit .yaml). Falsche Dateiendung → "Docker Compose file not found" Fehler.
+    - Service-Namen mit Bindestrich verwenden (crm-app, crm-worker). Coolify
+      konvertiert Bindestriche zu Unterstrichen in docker_compose_domains. Die
+      DB zeigt dann crm_app aber die docker-compose.yaml hat crm-app → kein
+      Match → keine Traefik-Labels → 503. Verwende Unterstriche: crm_app,
+      crm_worker.
+
+    ✅ RICHTIG:
+    - Service-Namen mit Unterstrichen: crm_app, crm_worker, postgres, redis
+    - docker-compose.yaml (mit .yaml, nicht .yml)
+    - 2-Phase Deploy: Erster Deploy OHNE Domain, dann docker_compose_domains
+      setzen, dann Redeploy. Grund: Coolify muss zuerst die docker-compose.yaml
+      aus dem Git-Repo lesen um die Service-Namen zu kennen. Erst dann kann
+      docker_compose_domains korrekt zugeordnet werden.
+    - docker_compose_domains Format: [{"name": "crm_app", "domain": "https://crm.media-on.de"}]
+      WICHTIG: KEIN :443 am Ende! Das :443 führt zu leeren Host() Labels.
+    - SERVICE_FQDN_CRM_APP_8000 in docker-compose.yaml environment block für
+      automatische Domain-Konfiguration durch Coolify Magic ENV.
+
+    FUNKTIONIERENDE BEISPIEL-APP: hms-licht-ton (UUID wvus7va5u0f9dmg27ggca7rl)
+    - docker_compose_domains: {"frontend":{"domain":"https://hms.media-on.de"}}
+    - Container hat Traefik-Labels: Host(`hms.media-on.de`)
+    - Kein :443, Service-Name ohne Bindestrich
+
+    MEHRERE INSTANZEN:
+    - APP_NAME und APP_DOMAIN als ENV-Variablen setzen
+    - Alles andere wird automatisch konfiguriert
+    - Beispiel: APP_NAME=leocrm-test APP_DOMAIN=https://crm-test.media-on.de
+
+    ═══════════════════════════════════════════════════════════════════════
     """
     print(f"\n{'='*60}")
     print("  LeoCRM Initial Deployment")