Doku-Deployment — Build + Statisches Hosting¶

Die kora-Platform-Dokumentation läuft seit TODO-Platform-10 als vorgebauter Static-Site in einem nginx:alpine-Container. Der vorherige mkdocs serve-Betrieb wurde wegen des Inotify-Bugs (Doc-Updates landeten nicht im Container) abgelöst.

Architektur¶

Editor → docs-kora/docs/*.md
   ↓ make docs-kora-build (Throwaway mkdocs-material-Container, RW-Mount)
   ↓
docs-kora/site/  (gitignored, lokal gebaut)
   ↓ kora-platform-mkdocs (nginx:alpine, RO-Mount auf /usr/share/nginx/html)
   ↓
http://localhost:8237 / https://docs.kora.luki-net.org

Kein Live-Reload mehr. Doc-Edits werden erst nach explizitem make docs-kora-deploy sichtbar — dafür verlässlich und ohne Inotify-Race-Conditions.

Make-Targets¶

Target	Wirkung
`make docs-kora-build`	Wirft `mkdocs build --strict` über einen Throwaway-`squidfunk/mkdocs-material:latest`-Container an, schreibt nach `docs-kora/site/`.
`make docs-kora-deploy`	`docs-kora-build` + `up -d --force-recreate mkdocs`. Standard-Update-Loop nach Doc-Merge.
`make docs-kora`	Startet nur den nginx-Container (Annahme: site/ ist bereits gebaut). Bricht ab, wenn `docs-kora/site/index.html` fehlt.
`make docs-kora-clean`	`rm -rf docs-kora/site/`.

Standard-Update-Flow¶

Nach jedem Doc-Merge auf platform/v1.0.0:

cd /opt/avs-chatbot
make docs-kora-deploy

Dauer: ~5–8 Sekunden (Build ~3s + Container-Recreate ~2s).

Verzeichnis-Layout¶

docs-kora/
├── mkdocs.yml          # site_dir: site (relativ zu mkdocs.yml)
├── docs/               # Markdown-Quellen (versioniert)
└── site/               # Build-Output (gitignored)
infra/
└── docs/
    └── nginx-docs.conf  # nginx-Config: gzip + sane defaults

NPMplus-Integration (zero-touch)¶

Die NPMplus-Reverse-Proxy-Konfiguration für https://docs.kora.luki-net.org zeigt auf den Compose-Service-Namen mkdocs Port 8237. Beides bleibt im neuen Setup unverändert — nur die dahinter laufende Software (vorher mkdocs serve, jetzt nginx:alpine) wechselt. Ein NPMplus-Reload ist nicht nötig.

Healthcheck¶

Der nginx-Container exposed / für den Compose-Healthcheck:

healthcheck:
  test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 10s

Hinweis: 127.0.0.1 explizit, nicht localhost — Alpine-Resolver mappt localhost ggf. auf IPv6, nginx hört aber nur auf IPv4 (listen 80;).

Build-Container vs. Serve-Container¶

Im Compose ist nur der Serve-Container (mkdocs = nginx:alpine) registriert. Der Build-Container (squidfunk/mkdocs-material:latest) läuft pro Build einmalig über docker run --rm und verschwindet danach. Vorteile:

Kein Long-Running-Resource-Footprint für ein Build-Werkzeug.
RW-Mount nur während des Builds — der Serve-Container behält read-only-Disziplin.
Image-Updates des Build-Containers via docker pull squidfunk/mkdocs-material:latest ohne Compose-Recreate.

Troubleshooting¶

Build schlägt fehl mit --strict: mkdocs zeigt Warnungen als Fehler. Häufigste Ursachen:

Toter Markdown-Link → Pfad relativ zu docs-kora/docs/ prüfen.
Nav-Eintrag in mkdocs.yml zeigt auf nicht existierende Datei.
Page nicht in Nav → INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: ...

Build ohne --strict zur Diagnose:

docker run --rm -v $(pwd)/docs-kora:/docs -w /docs \
  squidfunk/mkdocs-material:latest build

404 nach Deploy auf einer URL, die früher funktionierte: mkdocs-Material rendert pro Page einen Ordner mit index.html. Nach einem Page-Move sollten alte Pfade aus docs-kora/site/ weg sein — prüfe via ls docs-kora/site/<alter-pfad>/. Wenn doch noch da: make docs-kora-clean && make docs-kora-deploy.

nginx liefert generisches Welcome statt der Doku: Mount-Pfad falsch. Prüfen:

docker exec kora-platform-mkdocs ls /usr/share/nginx/html/ | head

Sollte index.html, 404.html, assets/, plus jede Top-Level-Nav- Section enthalten.

make docs-kora bricht mit "site/index.html fehlt" ab: Erwartet — der Wrapper schützt davor, einen leeren nginx-Container hochzubringen. Erst make docs-kora-build oder direkt make docs-kora-deploy.

Migrations-Hinweis¶

Vor TODO-Platform-10 lief der Service als squidfunk/mkdocs-material:latest serve --no-livereload. Nach dem Switch:

docs-kora-redeploy (im offene-todos-Bonusvorschlag erwähnt) nicht als separates Target eingeführt — docs-kora-deploy deckt den Use-Case vollständig ab.
mkdocs.yml site_dir von ../site-kora auf site geändert. Build- Output liegt jetzt unter docs-kora/site/ (gitignored).
Altes Verzeichnis site-kora/ (falls auf einem System noch vorhanden) ist obsolet und kann mit rm -rf site-kora/ entfernt werden.