# Deployment – BuyingAgent

**Stand:** 2026-10-03  
**Server:** Raspberry Pi 5 (`192.168.2.49`) — gleicher Host wie Kanshō/Mitai/Shinkan/Kairo, **eigenes** Compose-Projekt  
**Runner:** Gitea Actions (`/home/lars/gitea-runner/`, Label `ubuntu-latest` → Host)  
**Repo:** `http://192.168.2.144:3000/Lars/BuyingAgent.git`

Fachliche Grundlage: `docs/buying-agent-v0.1-spec-v1.1.md`.  
Architektur: `docs/buying-agent-architecture-addendum-v1.md` (Monorepo `backend/` + `frontend/`-Platzhalter).  
v0.1 hat keine Web-UI; öffentlich wird nur die API bereitgestellt. Der Image-Build-Kontext ist `./backend`.

---

## Port- und Pfad-Übersicht

| | Production | Development |
|---|------------|-------------|
| **Git-Branch** | `main` | `develop` |
| **Server-Verzeichnis** | `~/docker/buyingagent` | `~/docker/buyingagent-dev` |
| **API-Port** | 8006 | 8095 |
| **PostgreSQL** | nur Compose-Netz, DB `buyingagent` | nur Compose-Netz, DB `buyingagent_dev` |
| **Compose** | `docker-compose.yml` | `docker-compose.dev-env.yml` |
| **Health** | `http://localhost:8006/health/ready` | `http://localhost:8095/health/ready` |
| **LAN** | `http://192.168.2.49:8006` | `http://192.168.2.49:8095` |

Lokal ohne Server: `127.0.0.1:8000` über `docker compose up --build -d` (siehe README).  
8006/8095 waren auf dem Pi frei. 8000 ist durch Paperless belegt und darf auf dem Server nicht verwendet werden.

---

## Branch-Regel

- Entwicklung nur auf `develop`.
- Push auf `develop` startet den Dev-Build auf dem Pi.
- Produktiv nur über Merge-Commit `develop` → `main`:

```bash
git checkout main
git pull origin main
git merge --no-ff develop
git push origin main
```

Kein Fast-Forward, kein direkter Commit auf `main`, kein manuelles `git pull` auf dem Prod-Checkout. Gitea (`deploy-prod.yml`) ist der einzige Prod-Schreibpfad für Code.

---

## Einmalige Server-Einrichtung

Die Workflows legen das Verzeichnis an und klonen bei Bedarf selbst. Actions sind im Repo bereits aktiv. Derselbe Pi-Runner wie die Schwesterprodukte (`ubuntu-latest`).

Nach dem ersten erfolgreichen Deploy `.env` prüfen und für Production ein eigenes `DB_PASSWORD` setzen. PostgreSQL übernimmt User/Passwort nur beim **ersten** Start des Volumes.

```bash
mkdir -p ~/docker/buyingagent ~/docker/buyingagent-dev
```

Watchtower bleibt aus.

---

## Gitea Actions

| Workflow | Trigger | Zweck |
|----------|---------|--------|
| `deploy-dev.yml` | Push `develop` | Deploy nach `~/docker/buyingagent-dev`, Health `localhost:8095` |
| `deploy-prod.yml` | Push `main` | Deploy nach `~/docker/buyingagent`, Health `localhost:8006` |
| `test.yml` | nach Dev-Deploy bzw. Push `develop` | pytest auf `buyingagent_test` (Dev-Postgres, nicht Live-DB) und read-only Smoke gegen `/health/live` und `/health/ready` |

Der API-Build nutzt `ghcr.io` (nicht Docker Hub). `COMPOSE_BAKE=0 docker compose build --pull=false` verwendet vorhandene Basis-Images und vermeidet Registry-Metadatenabrufe, die auf dem Pi per IPv6-DNS timeouten.

`test.yml` folgt Kanshō: pytest läuft in einem Einweg-Container aus dem bereits deployedten `api`-Image gegen die wegwerfbare Datenbank `buyingagent_test` auf dem bereits laufenden Dev-Postgres. Die Live-Datenbank bleibt unangetastet. Es gibt kein Frontend, daher keinen Frontend-Build-Job.

---

## Manuelles Deploy

```bash
# Development
cd ~/docker/buyingagent-dev
git fetch origin develop && git reset --hard origin/develop
docker compose -f docker-compose.dev-env.yml build --pull=false api
BUYING_AGENT_API_PORT=8095 docker compose -f docker-compose.dev-env.yml up -d --wait
curl -sf http://localhost:8095/health/ready

# Production
cd ~/docker/buyingagent
git fetch origin main && git reset --hard origin/main
BUYING_AGENT_API_BIND=0.0.0.0 BUYING_AGENT_API_PORT=8006 docker compose build --pull=false api
BUYING_AGENT_API_BIND=0.0.0.0 BUYING_AGENT_API_PORT=8006 docker compose up -d --wait
curl -sf http://localhost:8006/health/ready
```