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:

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:

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

cp .env.example .env

Dann .env anpassen:

PV_API_KEY durch einen starken zufälligen Wert ersetzen;
optional einen getrennten PV_ADMIN_API_KEY setzen;
OLLAMA_URL anhand des Netzwerk-Alias prüfen;
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

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

Aufruf im Tailscale-Netz:

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:

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:

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

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

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

Nach Änderungen an der Wissensbasis:

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

3.7 KiB Raw Blame History

Docker-Deployment auf 100.103.83.12