Kairo-Jinkendo/docs/DEPLOYMENT.md

Deployment – Kairo Jinkendo

Stand: 2026-07-04 (AP0.1)
Server: Raspberry Pi 5 (192.168.2.49) — gleicher Host wie Shinkan/Mitai
Runner: Gitea Actions (/home/lars/gitea-runner/)

---

Port- und Pfad-Übersicht

	Production	Development
Git-Branch	main	develop
Server-Verzeichnis	/home/lars/docker/kairo	/home/lars/docker/kairo-dev
Frontend-Port	3004	3097
Backend-Port	8004	8097
PostgreSQL	nur im Container-Netz (Prod optional localhost:5436)	nur im Container-Netz
Domain	kairo.jinkendo.de	dev.kairo.jinkendo.de

---

Einmalige Server-Einrichtung

mkdir -p /home/lars/docker/kairo /home/lars/docker/kairo-dev

cd /home/lars/docker/kairo-dev
git clone http://192.168.2.144:3000/Lars/Kairo-Jinkendo.git .
git checkout develop
cp .env.example .env
# DB_PASSWORD setzen

cd /home/lars/docker/kairo
git clone http://192.168.2.144:3000/Lars/Kairo-Jinkendo.git .
git checkout main
cp .env.example .env
# Prod-DB_PASSWORD setzen

---

Gitea Actions – Checkliste

1. Actions aktiviert (Repository → Settings → Actions)
2. Pi-Runner registriert — derselbe wie Shinkan/Mitai (ubuntu-latest)
3. Push develop → deploy-dev.yml → curl http://localhost:8097/api/health
4. Merge main → deploy-prod.yml → curl http://localhost:8004/api/health
5. Push main → deploy-prod.yml + test.yml (Prod pytest/k6/Playwright auf localhost 8004/3004)

Workflow	Trigger	Zweck
deploy-dev.yml	Push develop	Deploy nach /home/lars/docker/kairo-dev
deploy-prod.yml	Push main	Deploy nach /home/lars/docker/kairo
test.yml	Push develop/main, PR develop	lint, pytest, k6, Playwright gegen deployte Instanz
test.yml → compose-smoke	Pull Request	Eigener Stack auf CI-Ports 18197/13197

Struktur wie Shinkan: Deploy und Test Suite sind getrennte Workflows in Gitea.

Bei Push auf develop oder main starten Deploy und Test Suite parallel; pytest wartet auf den Backend-Container (Dev: 8097/3097, Prod: 8004/3004).

---

Medien (optional)

Aktuell keine Medien-Speicherung. Bei Bedarf: NAS-Mount + docker-compose.override.yml (siehe frühere Doku-Version im Git-Verlauf).

---

Reverse Proxy (optional)

Hostname	Ziel (Pi)
kairo.jinkendo.de	http://192.168.2.49:3004
dev.kairo.jinkendo.de	http://192.168.2.49:3097

---

Datenbank-Passwort (Dev & Prod)

PostgreSQL im Compose-Stack initialisiert User/Passwort nur beim ersten Start des Volumes.
Wenn DB_PASSWORD in .env nicht mehr zum Volume passt, scheitert das Backend mit
password authentication failed for user "kairo_user" — der Container bleibt unhealthy.

Prod (Daten behalten): Passwort in der laufenden DB an .env anpassen:

cd /home/lars/docker/kairo
set -a && source .env && set +a
docker compose exec -T postgres psql -U kairo_user -d kairo \
  -c "ALTER USER kairo_user WITH PASSWORD '${DB_PASSWORD}';"
docker compose restart backend
curl -sf http://localhost:8004/api/health

Dev (Volume neu, inkl. Testdaten): Volume löschen und neu starten (dev-kairo-db-data).
Wenn du DB_NAME, DB_USER oder DB_PASSWORD in .env änderst, muss das Volume neu angelegt werden:

cd /home/lars/docker/kairo-dev
docker compose -f docker-compose.dev-env.yml down -v
docker compose -f docker-compose.dev-env.yml up -d --wait
curl -sf http://localhost:8097/api/health

Danach laufen Migrationen und Dev-Seeds automatisch (u. a. lars@stommer.com).

---

Manuelles Deploy

# Development
cd /home/lars/docker/kairo-dev
git fetch origin develop && git reset --hard origin/develop
docker compose -f docker-compose.dev-env.yml build --no-cache
docker compose -f docker-compose.dev-env.yml up -d

# Production
cd /home/lars/docker/kairo
git fetch origin main && git reset --hard origin/main
docker compose build --no-cache
docker compose up -d

Health: curl http://localhost:8097/api/health (Dev) bzw. http://localhost:8004/api/health (Prod)