Reproduzierbare Anleitung
Aufsetzen. Prüfen.
Kaputtmachen. Verstehen.
Diese Anleitung startet Kurswebsite, Lern-API und Orthanc als einen Compose-Stack. Sie enthält Voraussetzungen, erwartete Ergebnisse, Healthchecks, automatisierte Tests, Logs, Stoppen und einen ausdrücklich markierten Reset.
Nur ein Port verlässt den Stack
Versionen und Ressourcen prüfen
Benötigt werden Docker Engine oder Docker Desktop mit Compose v2, das entpackte Projekt, curl, Python 3 für die Testskripte und OpenSSL zur lokalen Secret-Erzeugung. Für den vollständigen Orthanc-Stack sollten ungefähr 2 GB freier Arbeitsspeicher und mehrere GB freier Plattenspeicher vorhanden sein.
docker version
docker compose version
python3 --version
curl --version
openssl version
docker system df
df -h .docker compose version zeigt v2.x. Bei knappem Speicher nicht blind docker system prune ausführen – zuerst klären, welche Images und Volumes noch gebraucht werden.Internes Orthanc-Passwort erzeugen
Das Passwort liegt nur in der nicht versionierten Datei .env und wird sowohl für Orthanc als auch für den internen Adapter verwendet. Der Browser erhält es nicht. Das Skript überschreibt keine vorhandene Datei.
cd teko-integrationslabor
chmod +x scripts/init-env.sh scripts/smoke-test.sh
./scripts/init-env.sh
test -s .env
docker compose config --quiet.env in Git committen, per Screenshot teilen oder unter den Webroot kopieren. docker compose config ohne --quiet kann aufgelöste Werte anzeigen.Images bauen und auf Health warten
docker compose build --pull
docker compose up -d --wait
docker compose psBeim ersten Start wird das Orthanc-Image geladen. Der Ablauf ist absichtlich gestaffelt: Orthanc wird gesund, der einmalige Seeder legt drei synthetische DICOM-Studien an, die Lern-API startet und prüft Orthanc, danach wird das Web-Gateway gesund. --wait endet ungleich 0, wenn ein Healthcheck nicht rechtzeitig grün wird.
| Service | Erwarteter Zustand | Öffentlich? |
|---|---|---|
course-web | Up (healthy), 127.0.0.1:3190→8080 | nur über lokalen Port/Host-Reverse-Proxy |
orthanc-lab | Up (healthy), kein Hostport | nur ausgewählte Routen via Gateway |
orthanc | Up (healthy), kein Hostport | nein |
orthanc-seed | Exited (0) | nein; einmaliger Initialisierer |
Jede Schicht gezielt prüfen
# Website-Gateway
curl -i http://localhost:3190/healthz
# Lern-API lebt unabhängig von Orthanc
curl -s http://localhost:3190/lab/healthz
# Readiness prüft den internen Orthanc-Aufruf
curl -s http://localhost:3190/lab/api/v1/pacs/status
# Nur synthetische, öffentliche Referenzen
curl -s http://localhost:3190/lab/api/v1/demo-studiesstatus: ok. Der PACS-Status nennt Orthanc und eine Version, aber keine Credentials oder interne URL. Die Studienliste enthält keine StudyInstanceUID und keine Patientendaten.Unit, HTTP, Docker-E2E und Link-Crawl
# API-/Orthanc-Integrationstests mit Fake-Orthanc
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
# Vollständiger laufender Stack: Seiten, Health, Seed, Async,
# Idempotenz, Datenschutz-Negativtest und private Pfade
./scripts/smoke-test.sh
# Alle internen HTML-Links, Assets und Fragmente
python3 tests/site_crawl.py http://localhost:3190Der Smoke-Test startet keinen neuen Stack, sondern prüft den bereits laufenden. Für die öffentliche Installation wird exakt dasselbe Skript mit anderer Basis-URL ausgeführt:
BASE_URL=https://teko.algorithma.app ./scripts/smoke-test.sh
python3 tests/site_crawl.py https://teko.algorithma.app/tools/find gefunden; Wiederholung liefert denselben Job; ein Patientendatenfeld wird abgelehnt; Builddateien, .env, Python-Quellcode, Tests und Orthanc-Pfade antworten mit 404.Fehler kontrolliert beobachten
Temporärer Fehler
Im Live-Labor „Temporärer Orthanc-Fehler“ wählen. Erwartet: retrying, steigender Versuchszähler, danach completed.
Fachfehler
„Fachfehler“ wählen. Erwartet: ohne sinnlose technische Retries nach dead_letter; Eintrag ist über die DLQ-Route sichtbar.
Echter Dienststopp
Lokal Orthanc stoppen, Job senden und später starten. Readiness wird 503; API-Liveness bleibt 200. Nach Retry-Limit endet der Job nachvollziehbar.
docker compose stop orthanc
curl -i http://localhost:3190/lab/healthz
curl -i http://localhost:3190/lab/readyz
docker compose start orthanc
docker compose psZuerst Zustand, dann Logs, dann Konfiguration
docker compose ps
docker compose logs --tail=100 course-web
docker compose logs --tail=100 orthanc-lab
docker compose logs --tail=100 orthanc
docker compose logs orthanc-seed
docker compose config --quiet
ss -ltn | grep 3190| Symptom | Wahrscheinliche Ursache | Prüfung |
|---|---|---|
| Compose verlangt Passwort | .env fehlt | ./scripts/init-env.sh |
3190 already allocated | Hostport belegt | ss -ltnp | grep 3190 |
| API 200, Readiness 503 | Orthanc nicht bereit/Fehlauthentisierung | Orthanc- und Lab-Logs vergleichen |
| Seeder Exit 1 | Create-DICOM oder Credential fehlgeschlagen | docker compose logs orthanc-seed |
| Website 502 | Lern-API nicht gesund | docker compose ps und Gatewaylog |
| Job matchCount 0 | synthetische Studie fehlt | Seeder erneut ausführen |
Erhalten oder bewusst löschen
Stoppen, Daten behalten
docker compose downContainer und Netze werden entfernt; das Orthanc-Volume bleibt. Beim nächsten up sind synthetische Studien weiterhin vorhanden.
Neu starten
docker compose up -d --waitDer Seeder ist idempotent. Bereits vorhandene synthetische Instanzen werden nicht fachlich verdoppelt.
docker compose down -vLokal und öffentlich gleich aufgebaut
| Zweck | Lokal | Öffentlich |
|---|---|---|
| Kurs | http://localhost:3190/ | teko.algorithma.app/ |
| Async-Lektion | /lessons/03-async.html | /lessons/03-async.html |
| Fallstudie | /cases/orthanc-spital.html | /cases/orthanc-spital.html |
| Live-Labor | /lab/orthanc.html | /lab/orthanc.html |
| Liveness | /lab/healthz | /lab/healthz |
| Orthanc-Status | /lab/api/v1/pacs/status | /lab/api/v1/pacs/status |
| OpenAPI | /lab/openapi.json | /lab/openapi.json |
Diese Komponenten bleiben im Kurs als optionale Cloud-/Fremdsystem-Labore dokumentiert. Der mitgelieferte Stack benötigt dafür keine Zugangsdaten und behauptet keine erfolgreiche Live-Prüfung gegen fremde Konten.