Zum Inhalt

Docker Build-Cache-Hygiene

Symptom

Nach einem strukturellen Refactoring oder einem Major-Dependency-Update verhält sich der Container nach docker compose up -d --build so, als wäre der alte Code noch aktiv: alter CMD, alter Modul-Import-Pfad, alter Hash in der version-Endpoint, etc.

Ursache

Docker BuildKit-Layer-Caching hält Zwischenstände lokal in /var/lib/docker. Bei einem normalen --build werden Layer wiederverwendet, sobald die Cache-Eingaben (COPY-Quellen, RUN-Kommandos) gleich aussehen — was bei Refactorings, die nur Strings wie Paketnamen ändern, schnell zu einem stillen Stale-Image führt: das pip install-Layer kann scheinbar identisch sein, in Wahrheit aber einen alten Wheel oder einen alten Builder-Stub gecached haben.

Vorfall (K-Q4-Fix-A, 2026-05-04)

Beim Modul-Rename avs_chatbot.api.app → kora_platform.main blieb das kora-platform-api:latest-Image nach --build auf dem alten CMD uvicorn avs_chatbot.api.app:app hängen. Symptom: API startete in den Crashloop mit ModuleNotFoundError: avs_chatbot.api. Diagnose erst nach docker inspect kora-platform-api --format '{{.Config.Cmd}}' — der CMD zeigte den Pre-Rename-String. --no-cache rebuild hat den Drift behoben.

Lösung

make kora-rebuild SVC=<service> (siehe compose-invocations.md) macht:

$(KORA_COMPOSE) build --no-cache <service>
$(KORA_COMPOSE) up -d --force-recreate <service>

--no-cache invalidiert den gesamten Layer-Cache für den Build, der force-recreate ersetzt zusätzlich den laufenden Container, damit das neue Image auch wirklich aktiv wird (sonst läuft das alte Image weiter, bis es planmäßig gestoppt wird).

Wann pflicht

  • Modul-Renamings (Python: import-Pfade; JS/TS: package names)
  • Major-Dependency-Updates (z.B. Python-Major-Version, PyTorch-Major)
  • Image-Base-Updates (Python:3.11 → 3.12, node:18 → node:20)
  • Crashloop nach --build ohne erkennbare Code-Änderung

Wann genügt der normale Build

  • Reine Code-Änderungen ohne Imports/Modul-Struktur-Änderungen
  • Kleinere Dependency-Bumps innerhalb derselben Major-Version
  • Konfigurations-Änderungen außerhalb der RUN-Layer (z.B. Env-Vars)

Builder-Stubs in Dockerfile.platform

Beim pyproject.toml-packages.find-Setup deklariert das Repo zwei findbare Pakete: kora_platform und avs_chatbot (Legacy-Demo-Modul). Der Builder erstellt für beide einen __init__.py-Stub vor dem pip install .-Schritt — sonst scheitert die Auto-Discovery. Das ist kein Drift; die Stubs werden im Source-Layer (Z. 82 von Dockerfile.platform) durch den echten src/-Tree überschrieben.

Wenn avs_chatbot in einer späteren Phase aus dem Repo entfernt wird (siehe docs-kora/docs/konzepte/multitenancy-fundament.md §15a.4 Go-Live-Modell), muss auch der Stub aus dem Dockerfile-Builder entfernt werden.