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

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)
-    2. Redis service (redis:7-alpine)
-    3. API application (from Git repo)
-    4. Worker service (same image as API)
-    5. Sets all ENV variables
-    6. Deploys API (builds image + runs migrations)
-    7. Deploys Worker
+    ═══════════════════════════════════════════════════════════════════════
+    ⚠️  KI / AGENT HINWEISE — BITTE VOR ÄNDERUNGEN LESEN  ⚠️
+    ═══════════════════════════════════════════════════════════════════════
+
+    ARCHITEKTUR: Einzelner docker-compose Stack (NICHT 4 separate Ressourcen!)
+    ─────────────────────────────────────────────────────────────────────
+    Dieses Script erstellt EINE Coolify Application mit build_pack=dockercompose.
+    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")