# 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

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

---

## 3. Repository klonen

```bash
# 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

```bash
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):

```bash
# 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

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

```bash
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

```bash
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:

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

```bash
# --- 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

```bash
/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:

```bash
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:

```bash
/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:

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

---

## 9. Container pruefen

```bash
# 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:

```bash
# 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 |