phase: 01-core-stack
verified: 2026-04-17T22:47:00+02:00
status: human_needed
score: 7/7 must-haves verified
overrides_applied: 0
re_verification:
previous_status: gaps_found
previous_score: 5/7
gaps_closed:
- "PostgreSQL volume gemountet auf /var/lib/postgresql/data (war /var/lib/postgresql)"
- "paperless-ai hat env_file: docker-compose.env — PAPERLESS_API_TOKEN wird korrekt injiziert"
gaps_remaining: []
regressions: []
human_verification:
- test: "docker compose up -d auf frischem Debian 13 + NVIDIA Host ausfuehren"
expected: "Alle 6 Container starten und melden 'healthy' nach ca. 2 Minuten; docker compose ps zeigt Status healthy fuer alle"
why_human: "Kann nicht ohne laufenden Debian 13 Host mit nvidia-container-toolkit verifiziert werden"
- test: "GPU-Zugriff im Ollama-Container pruefen: docker exec paperless-ollama-1 nvidia-smi"
expected: "nvidia-smi gibt GPU-Informationen aus (kein 'command not found', kein Fehler)"
why_human: "Benoetigt NVIDIA-Hardware und nvidia-container-toolkit auf dem Host"
- test: "Gitea-Webinterface aufrufen: http://localhost:3001"
expected: "Gitea-Setup-Seite oder Login-Seite laedt ohne Fehler"
why_human: "Benoetigt laufende Container-Umgebung"
- test: "Paperless-ngx UI aufrufen: http://localhost:8000"
expected: "Login-Seite laedt; kein 502/503"
why_human: "Benoetigt laufende Container-Umgebung"
deferred:
- truth: "POSTGRES_PASSWORD nicht als Klartext in docker-compose.yml"
addressed_in: "Phase 3"
evidence: "REQUIREMENTS.md SCRIPT-03: 'Bash script generates initial config (docker-compose.env from template)'; Kommentar Zeilen 52-54 in docker-compose.yml und docker-compose.env.template Zeilen 49-52 dokumentieren den Aufschub explizit"
Phase 1: Core Stack — Verification Report
Phase Goal: The complete 6-service stack starts healthy on Debian 13 with a single command and no host-side dependencies.
Verified: 2026-04-17T22:47:00+02:00
Status: human_needed
Re-verification: Yes — after gap closure (previous: gaps_found 5/7, now: 7/7)
Re-Verification Summary
| Gap (previous) | Fix Applied | Verified |
|---|---|---|
pgdata:/var/lib/postgresql — falscher Pfad |
pgdata:/var/lib/postgresql/data |
FIXED — Zeile 48 bestaetigt |
paperless-ai ohne env_file |
env_file: docker-compose.env ergaenzt |
FIXED — Zeile 94 bestaetigt |
Keine Regressionen in den 5 zuvor verifizierten Truths gefunden.
Goal Achievement
Observable Truths
| # | Truth | Status | Evidence |
|---|---|---|---|
| 1 | Alle 6 Dienste sind in docker-compose.yml definiert | VERIFIED | broker (L28), db (L42), webserver (L62), paperless-ai (L90), ollama (L126), gitea (L150) |
| 2 | Ollama laeuft als Container mit NVIDIA GPU-Passthrough | VERIFIED (strukturell) | deploy.resources.reservations.devices: driver nvidia, count all, capabilities [gpu] — Zeilen 136-142 |
| 3 | paperless-ai erreicht Ollama via http://ollama:11434 | VERIFIED | OLLAMA_API_URL=http://ollama:11434 Zeile 112; depends_on ollama: service_healthy Zeilen 100-101 |
| 4 | paperless-ai authentifiziert sich am Paperless API (API-Token) | VERIFIED | env_file: docker-compose.env Zeile 94 — PAPERLESS_API_TOKEN aus Template wird jetzt korrekt geladen |
| 5 | PostgreSQL-Daten persistieren korrekt ueber Restarts hinweg | VERIFIED | pgdata:/var/lib/postgresql/data Zeile 48 — korrekter Mount-Punkt fuer PostgreSQL 18 Daten-Cluster |
| 6 | Gitea laeuft als Container, ist im Docker-Netz und auf Port 3001 | VERIFIED | gitea/gitea:latest, Port 3001:3000, paperless-net, Healthcheck — Zeilen 150-172 |
| 7 | Explizites Netz paperless-net; alle 6 Dienste eingebunden | VERIFIED | networks: paperless-net: driver: bridge Zeilen 183-185; alle 6 Services haben networks: [paperless-net] |
Score: 7/7 truths verified
Deferred Items
Items not yet met but explicitly addressed in later milestone phases.
| # | Item | Addressed In | Evidence |
|---|---|---|---|
| 1 | POSTGRES_PASSWORD nicht als Klartext in docker-compose.yml | Phase 3 | REQUIREMENTS.md SCRIPT-03; Kommentar docker-compose.yml Zeilen 52-54; docker-compose.env.template Zeilen 49-52 |
Required Artifacts
| Artifact | Expected | Status | Details |
|---|---|---|---|
docker-compose.yml |
6-Dienste-Stack mit Healthchecks, Netz, GPU-Passthrough | VERIFIED | 185 Zeilen, 6 Dienste, paperless-net, 6 Healthchecks (L35/55/83/119/143/167), nvidia deploy-Block, env_file auf beiden Verbrauchern |
docker-compose.env.template |
Konfigurationstemplate mit PAPERLESS_SECRET_KEY | VERIFIED | 53 Zeilen, PAPERLESS_SECRET_KEY, PAPERLESS_API_TOKEN, SCAN_INTERVAL, OLLAMA_API_URL, CHANGE_ME-Marker |
.gitignore |
docker-compose.env nicht in Git | VERIFIED | docker-compose.env in .gitignore Zeile 2 |
Key Link Verification
| From | To | Via | Status | Details |
|---|---|---|---|---|
| paperless-ai environment | ollama service | OLLAMA_API_URL=http://ollama:11434 |
WIRED | Zeile 112; depends_on ollama: service_healthy (L100-101) |
| ollama service | NVIDIA GPU | nvidia container runtime deploy | WIRED (strukturell) | deploy.resources.reservations.devices korrekt; GPU-Zugriff nur mit nvidia-container-toolkit verifizierbar |
| paperless-ai | PAPERLESS_API_TOKEN | env_file: docker-compose.env |
WIRED | Zeile 94 bestaetigt; Token aus Template wird jetzt in Container geladen (Gap 2 geschlossen) |
| alle 6 Dienste | paperless-net | networks: [paperless-net] |
WIRED | L32/46/66/96/131/155; paperless-net: bridge deklariert L183-185 |
| webserver | db + broker | depends_on: service_healthy | WIRED | Zeilen 68-71: db condition: service_healthy, broker condition: service_healthy |
| docker-compose.env.template | docker-compose.env (nicht in Git) | cp-Anweisung im Template-Header | WIRED (dokumentiert) | Template-Header Zeilen 2-3; .gitignore schuetzt .env |
Data-Flow Trace (Level 4)
Nicht anwendbar — Docker Compose Orchestrierungsprojekt ohne Quellcode. Datenfluss-Verifikation erfolgt durch Healthcheck-Konfiguration und Umgebungsvariablen-Wiring (Key Links oben).
Behavioral Spot-Checks
Step 7b: SKIPPED — Kein laufender Debian 13 + NVIDIA Host verfuegbar. Alle Runtime-Pruefungen unter "Human Verification Required" gelistet.
Requirements Coverage
| Requirement | Source Plan | Description | Status | Evidence |
|---|---|---|---|---|
| STACK-01 | 01-02 | Docker Compose file runs the full stack on Debian 13 with a single docker compose up -d |
VERIFIED (strukturell) | Alle 6 Dienste definiert, Healthchecks vorhanden, env_file korrekt — Runtime-Test braucht Ziel-Host |
| STACK-02 | 01-01 | Ollama runs inside a container with NVIDIA GPU passthrough via nvidia-container-toolkit | VERIFIED (strukturell) | deploy.resources.reservations.devices: nvidia korrekt konfiguriert (L136-142) |
| STACK-03 | 01-01 | Gitea runs as a container in the same Compose network | VERIFIED | gitea/gitea:latest in paperless-net, Port 3001 (L150-172) |
| STACK-04 | 01-01 | Paperless-ngx, PostgreSQL, Redis, paperless-ai remain as current services | VERIFIED | Alle 4 Dienste unveraendert vorhanden (L28/42/62/90) |
| STACK-05 | 01-01/01-02 | All services communicate via Docker internal network (no host-side dependencies) | VERIFIED | paperless-net bridge; Ollama containerisiert; OLLAMA_API_URL intern; kein host.docker.internal |
Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
|---|---|---|---|---|
docker-compose.yml |
54 | POSTGRES_PASSWORD: paperless (Klartext) |
WARNING | Bekannte Schwachstelle; explizit auf Phase 3 / SCRIPT-03 aufgeschoben (deferred) |
docker-compose.yml |
160-161 | Gitea Ports ohne 127.0.0.1-Binding | WARNING | 3001:3000 und 222:22 auf allen Interfaces — inkonsistent mit Privacy-first Threat Model (ME-03) |
docker-compose.yml |
120 | Healthcheck fuer paperless-ai hardcoded auf Port 3000 | WARNING | Bricht wenn PAPERLESS_AI_PORT geaendert wird; Port wird per Variable gesetzt (L109, L116), HC nicht |
docker-compose.yml |
63/127/151 | :latest Tags fuer paperless-ngx, ollama, gitea |
INFO | Floating Tags koennen bei docker compose pull unbemerkt breaking changes einziehen (LO-02) |
Keine Blocker-Anti-Patterns mehr vorhanden. Die zwei frueher als BLOCKER eingestuften Findings (falscher pgdata-Pfad, fehlendes env_file) sind behoben.
Human Verification Required
1. Stack-Start auf Debian 13 mit NVIDIA GPU
Test: Auf einem frischen Debian 13 System mit installiertem nvidia-container-toolkit: docker compose up -d, dann nach 2 Minuten docker compose ps.
Expected: Alle 6 Container im Status healthy — broker, db, webserver, paperless-ai, ollama, gitea.
Why human: Benoetigt physische oder virtuelle Debian 13 Maschine mit NVIDIA GPU und nvidia-container-toolkit.
2. GPU-Sichtbarkeit im Ollama-Container
Test: docker exec paperless-ollama-1 nvidia-smi
Expected: GPU-Informationen (Modell, Treiber-Version, VRAM) werden ausgegeben; kein "command not found".
Why human: Benoetigt NVIDIA-Hardware und korrekt installierten nvidia-container-toolkit auf dem Host.
3. Paperless-ngx UI Erreichbarkeit
Test: Browser oeffnen: http://localhost:8000
Expected: Paperless-ngx Login-Seite laedt; HTTP 200, kein 502/503.
Why human: Benoetigt laufende Container-Umgebung.
4. Gitea Web-UI Erreichbarkeit
Test: Browser oeffnen: http://localhost:3001
Expected: Gitea Initial-Setup oder Login-Seite laedt ohne Fehler.
Why human: Benoetigt laufende Container-Umgebung.
Gaps Summary
Keine strukturellen Gaps mehr. Beide Blocker aus der initialen Verifikation sind behoben:
- Gap 1 geschlossen:
pgdata:/var/lib/postgresql/datakorrekt (L48) — kein Datenverlust-Risiko bei Restart. - Gap 2 geschlossen:
env_file: docker-compose.envbei paperless-ai (L94) — PAPERLESS_API_TOKEN wird korrekt in den Container injiziert.
Die Phase ist strukturell vollstaendig. Verbleibende Offene Punkte sind ausschliesslich Runtime-Tests, die Hardware und eine laufende Debian 13 Umgebung benoetigen (Human Verification Required, Punkte 1-4).
Verified: 2026-04-17T22:47:00+02:00
Verifier: Claude (gsd-verifier)