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

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

```yaml
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/version` und `http://localhost:3097/api/version`
- Prod: `curl http://localhost:8004/api/version` und `http://localhost:3004/api/version`

---

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

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