Kairo-Jinkendo/docs/DEPLOYMENT.md

Deployment – Kairo Jinkendo

Stand: 2026-07-04
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 (localhost)	5436	5437
Domain	kairo.jinkendo.de	dev.kairo.jinkendo.de

Familien-Referenz (bereits belegt):

App	Prod UI/API	Dev UI/API
Mitai	3002 / 8002	3099 / 8099
Shinkan	3003 / 8003	3098 / 8098
Kairo	3004 / 8004	3097 / 8097

---

Einmalige Server-Einrichtung

Auf dem Pi als User lars ausführen:

# Deploy-Verzeichnisse anlegen
mkdir -p /home/lars/docker/kairo
mkdir -p /home/lars/docker/kairo-dev

# Production
cd /home/lars/docker/kairo
git clone http://192.168.2.144:3000/Lars/Kairo-Jinkendo.git .
git checkout main
cp .env.example .env
# .env bearbeiten (DB_PASSWORD, SMTP, OPENROUTER, …)

# Development
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
# .env mit Dev-Werten bearbeiten (siehe Kommentare in .env.example)

Hinweis: Erstes docker compose up funktioniert erst, wenn backend/ und frontend/ mit Dockerfiles vorhanden sind.

---

Medien (optional, derzeit nicht eingerichtet)

Kairo benötigt aktuell keine Medien-Speicherung. Es sind keine Medien-Verzeichnisse auf dem Pi anzulegen.

Falls später Datei-Uploads o. Ä. nötig werden:

1. NAS-Freigabe auf dem Synology anlegen (nicht auf dem Raspberry Pi speichern).
2. Mount auf dem Pi einrichten (z. B. /mnt/nas/kairo-media bzw. /mnt/nas/kairo-media/dev).
3. docker-compose.override.yml im jeweiligen Deploy-Verzeichnis ergänzen (wird von Git ignoriert):

services:
  backend:
    environment:
      MEDIA_ROOT: /app/media
    volumes:
      - /mnt/nas/kairo-media:/app/media   # Dev: …/kairo-media/dev

4. Im Backend MEDIA_ROOT auswerten — erst wenn die App Medien unterstützt.

Analog Shinkan (SHINKAN_MEDIA_HOST), aber bewusst nicht Teil des Initial-Setups.

---

Reverse Proxy (Synology / Fritz!Box)

Analog zu Shinkan — neue Hostnamen im Proxy eintragen:

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

SSL/TLS wie bei den Schwester-Apps (Let's Encrypt über Synology).

---

Gitea Actions

Workflows unter .gitea/workflows/:

Workflow	Trigger	Aktion
deploy-dev.yml	Push auf develop	Build + Deploy nach kairo-dev/
deploy-prod.yml	Push auf main	Build + Deploy nach kairo/
test.yml	PR/Push develop, nach Deploy	pytest, Lint, Frontend-Build, k6, Playwright

Health-Checks nach Deploy:

• Dev: curl http://localhost:8097/api/health (Backend direkt); mit Frontend zusätzlich http://localhost:3097/api/health
• Prod: curl http://localhost:8004/api/health (Backend direkt); mit Frontend zusätzlich http://localhost:3004/api/health

---

Gitea Secrets (für E2E-Tests)

In Gitea unter Repository → Settings → Actions → Secrets (analog Shinkan):

Secret	Verwendung
E2E_DEV_TEST_EMAIL	Playwright Dev-Login
E2E_DEV_TEST_PASSWORD	Playwright Dev-Login
E2E_PROD_TEST_EMAIL	Playwright Prod-Login
E2E_PROD_TEST_PASSWORD	Playwright Prod-Login

---

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

---

Nächster Schritt (App-Code)

1. backend/ mit FastAPI-Skeleton (main.py, Dockerfile, migrations/)
2. frontend/ mit React/Vite-Skeleton (Dockerfile, nginx.conf)
3. Erster Push auf develop → Auto-Deploy Dev
4. Reverse-Proxy-Einträge für Domains aktivieren
5. Gitea E2E-Secrets setzen