BuyingAgent/docs/DEPLOYMENT.md

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: .specs/buying-agent-v0.1-spec.md bzw. docs/buying-agent-v0.1-spec-v1.1.md.
v0.1 hat keine Web-UI; öffentlich wird nur die API bereitgestellt.

---

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:

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.

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). docker compose build --pull=false verwendet vorhandene Basis-Images und vermeidet IPv6-Timeouts gegen auth.docker.io.

test.yml folgt Kanshō: pytest läuft in einem Einweg-Container (api-test, Compose-Profil test) 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

# 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