# Docker-Deployment auf `100.103.83.12`

Der Compose-Stack betreibt Test-Frontend und FastAPI-Agent gemeinsam. Er startet
keinen zweiten Ollama-Container, sondern verbindet sich mit dem vorhandenen
externen Docker-Netz `ollama-default`.

## Voraussetzungen

Auf dem Zielhost müssen vorhanden sein:

- Docker Engine mit Compose-Plugin;
- das externe Netz `ollama-default`;
- ein darin erreichbarer Ollama-Container;
- die Modelle `qwen3.8:27b` und `bge-m3` in dieser Ollama-Instanz;
- `wissensbasis/` und entweder ein vorhandenes `data/index.db` oder genügend
  Zeit für den initialen Indexaufbau.

Das Netz und seine Container/Aliase prüfen:

```bash
docker network inspect ollama-default
```

Der Compose-Beispielwert nimmt den DNS-Namen `ollama` und den internen
Ollama-Port `11434` an. Das ist **nicht lokal verifiziert**, weil das Netz nur
auf dem Zielhost existiert. Falls der Container im Netz anders heißt, muss
`OLLAMA_URL` in `.env` entsprechend gesetzt werden, beispielsweise:

```text
OLLAMA_URL=http://tatsaechlicher-containername:11434
```

Die veröffentlichte Host-Portnummer `11435` ist innerhalb des gemeinsamen
Docker-Netzes normalerweise nicht relevant; Container sprechen den internen
Port des Ollama-Containers an.

## Konfiguration

```bash
cp .env.example .env
```

Dann `.env` anpassen:

1. `PV_API_KEY` durch einen starken zufälligen Wert ersetzen;
2. optional einen getrennten `PV_ADMIN_API_KEY` setzen;
3. `OLLAMA_URL` anhand des Netzwerk-Alias prüfen;
4. `PUID`/`PGID` auf den Besitzer von `data/` setzen.

`.env` ist gitignored und darf nicht committed werden. Compose verwendet die
Datei nur zur Interpolation der ausdrücklich in `compose.yaml` aufgelisteten
Variablen; sonstige lokale Secrets werden nicht pauschal in den Container
durchgereicht.

## Start mit vorhandenem Index

```bash
docker compose build
docker compose up -d
docker compose ps
docker compose logs --follow pv-agent
```

Aufruf im Tailscale-Netz:

```text
http://100.103.83.12:8080/
```

Im Frontend denselben Wert wie `PV_API_KEY` als Service-Key eingeben.

## Initialen Index im Container bauen

Falls `data/index.db` auf dem Zielhost noch fehlt:

```bash
mkdir -p data
docker compose run --rm pv-agent python -m agent.cli ingest
```

Der Lauf verwendet `bge-m3` über `OLLAMA_URL` und schreibt den Index in das
Bind-Mount `./data`. Danach den Dienst starten:

```bash
docker compose up -d
```

Der Prozess läuft als `PUID:PGID`. `data/` muss für diese IDs schreibbar sein,
insbesondere wenn `/v1/reindex` verwendet werden soll.

## Smoke-Tests

```bash
curl --fail http://100.103.83.12:8080/v1/health
curl --fail \
  -H 'Authorization: Bearer <PV_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"question":"Wie hoch ist der steuerfreie Tagesgeldsatz?","mode":"knowledge"}' \
  http://100.103.83.12:8080/v1/ask
```

`/v1/health` muss `"status":"ok"` liefern. Ein Status `degraded` bedeutet in
der Regel, dass der Index fehlt oder Ollama unter dem konfigurierten
Container-DNS-Namen nicht erreichbar ist.

## Sicherheitsprofil

- Port `8080` wird nur an die Tailscale-Adresse `100.103.83.12` gebunden.
- `PV_API_KEY` ist für den Compose-Start verpflichtend.
- Root-Dateisystem ist read-only; nur `./data` ist schreibbar.
- Alle Linux-Capabilities werden entfernt; `no-new-privileges` ist aktiv.
- `wissensbasis/` wird read-only eingebunden.
- Frontend und API sind same-origin; es ist keine CORS-Freigabe nötig.
- Außerhalb des verschlüsselten Tailnets ist TLS vor dem Dienst erforderlich.

## Aktualisierung

```bash
git pull
docker compose build --pull
docker compose up -d
docker image prune
```

Nach Änderungen an der Wissensbasis:

```bash
docker compose run --rm pv-agent python -m agent.cli ingest
docker compose up -d
```