chmln-app-dev/kbcrm
5
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(deploy): Image-Promotion, deploy.env, Health-Check-Fix und Anleitungen

Browse Source 
- Deploy-Scripts: Image-Promotion statt Rebuild (docker tag + up -d),
  deploy.env fuer Server-Konfiguration, -p fuer Projekt-Namen,
  Health-Check mit Host-Header und /xhr/health-check
- docker-compose.prod.yaml: name-Feld entfernt (Projekt-Name per -p)
- deploy.env.example als Vorlage hinzugefuegt
- .vibe/skills/client-build/SKILL.md aus Git-Index entfernt (gitignore)
- Deployment-Anleitung: Zugangsdaten, deploy.env, Image-Promotion,
  prod ohne eigenes Repo, git-clone-Hinweis, Log-Befehle mit -p
- Deploy-lokal-testen.md: neue Anleitung fuer lokales Testen

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
gg committed 2026-09-15 17:10:18 +02:00
1 parent e824b545bb
commit efef212544
7 files changed
+440 -106
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Dokumentationen/Deploy-lokal-testen.md
+229
View File
@@ -0,0 +1,229 @@
# 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 |
Dokumentationen/Deployment-Anleitung.md
+97 -28
View File
@@ -58,6 +58,23 @@ Folgende Software muss installiert sein:
Docker Compose muss als Plugin installiert sein (Befehl: `docker compose`,
nicht `docker-compose`).
### Git-Zugangsdaten konfigurieren
Das `git clone` und `git fetch` in den Deploy-Scripts nutzen die
Git-Credentials, die auf dem Deploy-Server konfiguriert sind. Die
Zugangsdaten stehen nicht in den Scripts oder Konfigurationsdateien.
Drei Moeglichkeiten:
| Methode | Einrichtung | Wo hinterlegt |
|---|---|---|
| SSH-Key | `git clone git@git.everdc.eu:.../kbcrm` (SSH-URL verwenden) | `~/.ssh/id_rsa` auf dem Deploy-Server |
| Git-Credential-Store | `git config --global credential.helper store` | `~/.git-credentials` auf dem Deploy-Server |
| Deploy-Token (Gitea) | Token in Remote-URL: `https://token:secret@git.everdc.eu/...` | In der `origin`-URL des geklonten Repos |
Empfohlen: SSH-Key oder Deploy-Token. Der Credential-Store speichert
Passwoerter im Klartext und sollte nur fuer Test-Umgebungen verwendet werden.
---
## 3. Verzeichnisstruktur auf dem Deploy-Server
@@ -67,14 +84,14 @@ Es werden zwei Umgebungen (test-prod und prod) parallel betrieben:
```
/opt/kbcrm/
├── test-prod/
│ ├── repo/ ← git clone des Repos
│ ├── repo/ ← git clone des Repos (einziges Repo auf dem Server)
│ └── .env ← test-prod Umgebung (eigene Ports, eigene DB)
├── prod/
│ ├── repo/
│ └── .env ← prod Umgebung
│ └── .env ← prod Umgebung (kein eigenes Repo — Images per docker tag)
└── scripts/
├── deploy-kbcrm-test.sh ← aus dem Repo (scripts/)
└── deploy-kbcrm-prod.sh ← aus dem Repo (scripts/)
├── deploy-kbcrm-prod.sh ← aus dem Repo (scripts/)
└── deploy.env ← Server-spezifische Konfiguration (nicht im Repo)
```
Die SQLite-Datenbanken liegen ausserhalb des Repos in einem bind-mount
@@ -89,11 +106,16 @@ Die SQLite-Datenbanken liegen ausserhalb des Repos in einem bind-mount
```bash
sudo mkdir -p /opt/kbcrm/test-prod /opt/kbcrm/prod
# Test-Prod Repository
# Repository klonen (nur einmal — prod nutzt die Images aus test-prod)
# WICHTIG: git clone wird nur beim ersten Mal ausgefuehrt. Wenn das Verzeichnis
# bereits existiert (z.B. .env wurde bereits abgelegt), schlaegt clone fehl.
# Weitere Updates werden durch das deploy-kbcrm-test.sh Script via
# git fetch + git reset --hard durchgefuehrt — kein manueller clone mehr.
sudo git clone https://git.everdc.eu/chmln-app-dev/kbcrm /opt/kbcrm/test-prod/repo
# Prod Repository
sudo git clone https://git.everdc.eu/chmln-app-dev/kbcrm /opt/kbcrm/prod/repo
# Falls das Verzeichnis bereits existiert und aktualisiert werden soll:
# cd /opt/kbcrm/test-prod/repo && git fetch origin main && git reset --hard origin/main
# Oder einfach: /opt/kbcrm/scripts/deploy-kbcrm-test.sh
```
### 4.2. `.env`-Dateien anlegen
@@ -104,8 +126,8 @@ Kopieren Sie die Vorlage aus dem Repo und passen Sie die Werte an:
# Test-Prod
cp /opt/kbcrm/test-prod/repo/env-sample /opt/kbcrm/test-prod/.env
# Prod
cp /opt/kbcrm/prod/repo/env-sample /opt/kbcrm/prod/.env
# Prod (Vorlage aus test-prod-Repo)
cp /opt/kbcrm/test-prod/repo/env-sample /opt/kbcrm/prod/.env
```
### 4.3. `.env` fuer Test-Prod anpassen
@@ -194,12 +216,44 @@ zentralen Ort:
```bash
sudo mkdir -p /opt/kbcrm/scripts
sudo cp /opt/kbcrm/test-prod/repo/scripts/deploy-kbcrm-test.sh /opt/kbcrm/scripts/
sudo cp /opt/kbcrm/prod/repo/scripts/deploy-kbcrm-prod.sh /opt/kbcrm/scripts/
sudo cp /opt/kbcrm/test-prod/repo/scripts/deploy-kbcrm-prod.sh /opt/kbcrm/scripts/
sudo chmod +x /opt/kbcrm/scripts/*.sh
```
Passen Sie die Pfad-Variablen am Anfang der Scripts an, falls Ihre
Verzeichnisstruktur abweicht.
### 4.8. `deploy.env` anlegen (Server-spezifische Konfiguration)
Die Deploy-Scripts laden ihre Server-spezifische Konfiguration (Pfade, Ports,
Projekt-Namen) aus einer Datei `deploy.env`, die im gleichen Verzeichnis wie
die Scripts liegen muss. Diese Datei ist **nicht Teil des Repos** und wird
nicht per `git pull` ueberschrieben.
Kopieren Sie die Vorlage und passen Sie die Werte an:
```bash
cp /opt/kbcrm/test-prod/repo/scripts/deploy.env.example /opt/kbcrm/scripts/deploy.env
vi /opt/kbcrm/scripts/deploy.env
```
Inhalt der `deploy.env`:
```bash
# --- Test-Prod Umgebung (fuer deploy-kbcrm-test.sh) ---
DEPLOY_REPO_DIR=/opt/kbcrm/test-prod/repo
DEPLOY_ENV_FILE=/opt/kbcrm/test-prod/.env
DEPLOY_PROJECT_NAME=kbptest
DEPLOY_HEALTH_PORT=8443
# --- Prod Umgebung (fuer deploy-kbcrm-prod.sh) ---
DEPLOY_PROD_COMPOSE_FILE=/opt/kbcrm/test-prod/repo/docker-compose.prod.yaml
DEPLOY_PROD_ENV_FILE=/opt/kbcrm/prod/.env
DEPLOY_PROD_PROJECT_NAME=kbpprod
DEPLOY_PROD_TEST_PROJECT_NAME=kbptest
DEPLOY_PROD_HEALTH_PORT=443
```
Wenn `deploy.env` fehlt, verwenden die Scripts ihre eingebauten Defaults
(die den obigen Werten entsprechen). Die `deploy.env` ist nur noetig, wenn
Ihre Verzeichnisstruktur oder Ports abweichen.
---
@@ -291,7 +345,7 @@ Das Script fuehrt folgende Schritte aus:
Build und Python mit Anwendungscode)
3. Health-Check
### 6.2. Manuelle Promotion nach Prod
### 6.2. Manuelle Promotion nach Prod (Image-Promotion)
Nach Verifikation auf dem Test-Server:
@@ -299,8 +353,22 @@ Nach Verifikation auf dem Test-Server:
/opt/kbcrm/scripts/deploy-kbcrm-prod.sh
```
Das Script fragt eine Bestaetigung ("yes/no") und fuehrt dann den gleichen
Ablauf aus wie das Test-Script, jedoch mit der Prod-`.env`.
Das Script fragt eine Bestaetigung ("yes/no") und uebernimmt dann die
getesteten Images aus test-prod per `docker tag` — kein Rebuild, kein git pull.
Prod startet mit exakt dem Stand, der in test-prod verifiziert wurde. Nur
die `.env` unterscheidet sich (Ports, Zertifikate, DB-Pfad, OIDC).
Ablauf:
1. Sicherheitsabfrage ("yes/no")
2. `docker tag` — Images von `kbptest-*` nach `kbpprod-*` kopieren
3. `docker compose up -d` — Container starten (ohne `--build`)
4. Health-Check
**Wichtig:** Das Prod-Script fuehrt kein `git pull` aus. Eine Aenderung an
der `docker-compose.prod.yaml` zwischen test-prod und Promotion wuerde
bedeuten, dass prod mit einer anderen Konfiguration startet als verifiziert.
Bei Aenderungen an der Compose-Datei muss erst ein neues test-prod-Deploy
durchgefuehrt werden.
### 6.3. Alternative: Git-Tag-basierte Promotion
@@ -334,34 +402,34 @@ done
```bash
# Test-Prod
docker compose --env-file /opt/kbcrm/test-prod/.env \
docker compose -p kbptest --env-file /opt/kbcrm/test-prod/.env \
-f /opt/kbcrm/test-prod/repo/docker-compose.prod.yaml logs
# Prod
docker compose --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/prod/repo/docker-compose.prod.yaml logs
docker compose -p kbpprod --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/test-prod/repo/docker-compose.prod.yaml logs
# Nur Python-Container
docker compose --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/prod/repo/docker-compose.prod.yaml logs pythonapp
docker compose -p kbpprod --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/test-prod/repo/docker-compose.prod.yaml logs pythonapp
# Nur NGINX-Container
docker compose --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/prod/repo/docker-compose.prod.yaml logs nginx-proxy
docker compose -p kbpprod --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/test-prod/repo/docker-compose.prod.yaml logs nginx-proxy
```
### Container-Status pruefen
```bash
docker compose --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/prod/repo/docker-compose.prod.yaml ps
docker compose -p kbpprod --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/test-prod/repo/docker-compose.prod.yaml ps
```
### Manuell in den Container wechseln
```bash
docker compose --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/prod/repo/docker-compose.prod.yaml exec pythonapp bash
docker compose -p kbpprod --env-file /opt/kbcrm/prod/.env \
-f /opt/kbcrm/test-prod/repo/docker-compose.prod.yaml exec pythonapp bash
```
### Rollback
@@ -370,10 +438,10 @@ Bei Problemen kann auf einen frueheren Stand zurueckgekehrt werden:
```bash
# Auf dem Deploy-Server:
cd /opt/kbcrm/prod/repo
cd /opt/kbcrm/test-prod/repo
git log --oneline -10 # frueheren Commit finden
git checkout <commit-hash>
docker compose --env-file /opt/kbcrm/prod/.env \
docker compose -p kbpprod --env-file /opt/kbcrm/prod/.env \
-f docker-compose.prod.yaml up -d --build
```
@@ -425,6 +493,7 @@ docker image prune -f
- [ ] Datenbank-Verzeichnisse erstellt (`PYTHON_DB_DIR`)
- [ ] SSL-Zertifikate abgelegt (`NGINX_CERTS`)
- [ ] Deploy-Scripts kopiert und ausfuehrbar gemacht
- [ ] `deploy.env` angelegt und angepasst (Pfade, Ports, Projekt-Namen)
- [ ] Git-Hook oder Webhook eingerichtet (fuer automatisches Test-Deploy)
- [ ] Erster manueller Deploy-Test: `deploy-kbcrm-test.sh`
- [ ] Health-Check erfolgreich: `curl -k https://localhost:8443/health-check`