kbcrm/Dokumentationen/Deploy-lokal-testen.md

Anleitung: Deploy-Prozess lokal auf dem Entwicklungsrechner testen

Diese Anleitung beschreibt, wie der komplette Deploy-Prozess (test-prod und Prod-Promotion) lokal auf dem Entwicklungsrechner getestet werden kann — ohne Git-Hook, ohne Remote-Server. Voraussetzung: Docker und Docker Compose sind auf dem Host installiert (nicht im Dev-Container, sondern auf dem Betriebssystem des Rechners).

---

1. Voraussetzungen

• Docker und Docker Compose auf dem Host installiert
• Git-Repo lokal vorhanden (oder Remote-URL fuer Clone)
• Freie Ports: 8080 (test-prod) und 8081 (prod)

---

2. Verzeichnisstruktur anlegen

mkdir -p /tmp/deploy-test/{test-prod/repo,scripts,test-prod/data,prod/data,test-prod/certs,prod/certs}

---

3. Repository klonen

# Entwender vom Remote-Server:
git clone https://git.everdc.eu/chmln-app-dev/kbcrm /tmp/deploy-test/test-prod/repo

# Oder vom lokalen Repo (schneller, kein Netzwerk noetig):
git clone /pfad/zum/kbcrm /tmp/deploy-test/test-prod/repo

---

4. .env fuer Test-Prod anlegen

cp /tmp/deploy-test/test-prod/repo/env-sample /tmp/deploy-test/test-prod/.env
vi /tmp/deploy-test/test-prod/.env

Minimal-Konfiguration fuer lokales Testen (SSL aus, keine Zertifikate noetig):

# NGINX-Server
NGINX_USE_SSL=false
NGINX_HOST_PORT=8080
NGINX_SERVER_NAME=localhost
# Auch bei SSL=false muessen die Variablen gesetzt sein (Compose bindet den Pfad ein)
NGINX_CERTS=/tmp/deploy-test/test-prod/certs
NGINX_CERT=placeholder
NGINX_CERT_KEY=placeholder

# Python App-Server
PYTHON_DB_DIR=/tmp/deploy-test/test-prod/data

# OIDC-Settings (ggf. anpassen oder Platzhalter fuer lokales Testen)
ZITADEL_ISSUER=https://id.vmlx.de
ZITADEL_CLIENT_ID=local-test
ZITADEL_CLIENT_SECRET=local-test
ZITADEL_REDIRECT_URI=http://localhost:8080/auth/callback
ZITADEL_SCOPES=openid,profile,email

---

5. .env fuer Prod anlegen

cp /tmp/deploy-test/test-prod/repo/env-sample /tmp/deploy-test/prod/.env
vi /tmp/deploy-test/prod/.env

NGINX_USE_SSL=false
NGINX_HOST_PORT=8081
NGINX_SERVER_NAME=localhost
NGINX_CERTS=/tmp/deploy-test/prod/certs
NGINX_CERT=placeholder
NGINX_CERT_KEY=placeholder
PYTHON_DB_DIR=/tmp/deploy-test/prod/data
ZITADEL_ISSUER=https://id.vmlx.de
ZITADEL_CLIENT_ID=local-test
ZITADEL_CLIENT_SECRET=local-test
ZITADEL_REDIRECT_URI=http://localhost:8081/auth/callback
ZITADEL_SCOPES=openid,profile,email

---

6. Deploy-Scripts und deploy.env kopieren

cp /tmp/deploy-test/test-prod/repo/scripts/deploy-kbcrm-test.sh /tmp/deploy-test/scripts/
cp /tmp/deploy-test/test-prod/repo/scripts/deploy-kbcrm-prod.sh /tmp/deploy-test/scripts/
cp /tmp/deploy-test/test-prod/repo/scripts/deploy.env.example /tmp/deploy-test/scripts/deploy.env
chmod +x /tmp/deploy-test/scripts/*.sh

deploy.env anpassen:

vi /tmp/deploy-test/scripts/deploy.env

# --- Test-Prod Umgebung ---
DEPLOY_REPO_DIR=/tmp/deploy-test/test-prod/repo
DEPLOY_ENV_FILE=/tmp/deploy-test/test-prod/.env
DEPLOY_PROJECT_NAME=kbptest
DEPLOY_HEALTH_PORT=8080

# --- Prod Umgebung ---
DEPLOY_PROD_COMPOSE_FILE=/tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml
DEPLOY_PROD_ENV_FILE=/tmp/deploy-test/prod/.env
DEPLOY_PROD_PROJECT_NAME=kbpprod
DEPLOY_PROD_TEST_PROJECT_NAME=kbptest
DEPLOY_PROD_HEALTH_PORT=8081

---

7. Test-Deploy ausfuehren

/tmp/deploy-test/scripts/deploy-kbcrm-test.sh

Das Script:

1. Pullt den aktuellen Code (falls vom Remote geklont) oder nutzt den lokalen Stand
2. Baut beide Images (NGINX mit TypeScript-Build, Python mit Anwendungscode)
3. Startet die Container
4. Fuehrt einen Health-Check durch

Erster Build dauert einige Minuten (Node.js-Stage, npm install, tsc+rollup, pip install). Folge-Builds sind durch Docker-Layer-Caching schneller.

Health-Check manuell:

curl http://localhost:8080/xhr/health-check

---

8. Prod-Promotion testen

Voraussetzung: der Test-Deploy wurde erfolgreich durchgefuehrt — die Images kbptest-pythonapp und kbptest-nginx-proxy existieren.

Die Promotion braucht kein eigenes Prod-Repo — die Compose-Datei wird aus dem test-prod-Repo gelesen.

Dann die Promotion ausfuehren:

/tmp/deploy-test/scripts/deploy-kbcrm-prod.sh

Das Script:

1. Fragt "yes/no" (mit "yes" bestaetigen)
2. Taggt die Images von kbptest-* nach kbpprod-*
3. Startet die Prod-Container (ohne Rebuild)
4. Health-Check

Health-Check manuell:

curl http://localhost:8081/xhr/health-check

---

9. Container pruefen

# Laufende Container anzeigen
docker compose -p kbptest --env-file /tmp/deploy-test/test-prod/.env \
    -f /tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml ps

docker compose -p kbpprod --env-file /tmp/deploy-test/prod/.env \
    -f /tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml ps

# Logs anzeigen
docker compose -p kbptest --env-file /tmp/deploy-test/test-prod/.env \
    -f /tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml logs

docker compose -p kbpprod --env-file /tmp/deploy-test/prod/.env \
    -f /tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml logs

---

10. Aufraeumen

Nach dem Testen alle Container und Images entfernen:

# Test-Container stoppen und entfernen
docker compose -p kbptest --env-file /tmp/deploy-test/test-prod/.env \
    -f /tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml down

# Prod-Container stoppen und entfernen
docker compose -p kbpprod --env-file /tmp/deploy-test/prod/.env \
    -f /tmp/deploy-test/test-prod/repo/docker-compose.prod.yaml down

# Images entfernen
docker rmi kbptest-pythonapp kbptest-nginx-proxy kbpprod-pythonapp kbpprod-nginx-proxy 2>/dev/null

# Verzeichnis loeschen
rm -rf /tmp/deploy-test

---

11. Typische Probleme

Problem	Ursache	Loesung
docker compose not found	Docker Compose Plugin fehlt	docker compose muss als Plugin installiert sein (nicht docker-compose)
Port bereits belegt	Anderer Dienst auf 8080/8081	Anderen Port in .env und deploy.env setzen
COPY failed im Build	.dockerignore schliesst benoetigte Dateien aus	.dockerignore im Repo-Root pruefen
Health-Check schlaegt fehl	Container braucht laenger als 10 Sek	sleep 10 im Script erhoehen oder Logs pruefen
OIDC-Login schlaegt fehl	Redirect-URI stimmt nicht	ZITADEL_REDIRECT_URI in .env an Port anpassen
git fetch schlaegt fehl	Keine Zugangsdaten konfiguriert	Lokales Repo verwenden oder Credentials einrichten