Shift Planner Container Runtime Contract

Tento dokument je source of truth pro zmeny v Docker image, Docker Compose a deploy skriptech v repozitari Shift Planner.

Doplňuje:

Vztah k ostatnim artefaktum:

docs/remote-server.md se porad pouziva pro server a remote deploy pravidla.
Tento dokument drzi jen projektovy runtime kontrakt pro image, Compose a deploy skripty.
Codex skill pro deploy/runtime workflow neni source of truth; jen odkazuje na dokumentaci a hlida konzistenci zmen.
Zdroj skillu muze byt verzovany v repu pod codex-skills/, ale Codex ho realne nacita az z lokalniho skill adresare ${CODEX_HOME:-$HOME/.codex}/skills/.

Scope

Plati pro moduly, ktere bezí jako kontejnery v produkci na mathbox.90.cz:

Neřeší:

Docker runtime kontrakt neni jen o image. Je rozdělen mezi tri vrstvy:

Kazda z nich musi dodrzet svou cast. Zmena jen v jedne vrstve je podezrela a musi byt vedoma.

Aplikacni proces v kontejneru musi umet bezet jako non-root uzivatel.
Image nesmi vyzadovat root-only operace pri beznem startu aplikace.
Image musi pouzivat stabilni aplikačni cesty pod /app.
Aplikace musi zapisovat jen do adresaru, ktere jsou pro to urcene mounty nebo internim tmp adresarem.
Pokud image potrebuje inicializaci souboru nebo adresaru, musi byt kompatibilni s cizim numerickym UID:GID predanym z runtime.

Produkcni modul = jeden dlouhodobe bezici kontejner.
Runtime uzivatel se predava pres HOST_UID a HOST_GID.
Compose ma explicitne nastavit runtime uzivatele tak, aby proces nebezel jako root.
Mounty musi zustat konzistentni s projektovou strukturou:
data: /home/agent/shift-planner/data -> /app/data
logs: /home/agent/shift-planner/logs -> /app/logs
conf: /home/agent/shift-planner/conf -> /app/conf
Konfiguracni mount /app/conf ma byt read-only.
Data mount muze byt read-only, pokud modul data jen cte.
Logs mount musi zustat zapisovatelny runtime uzivatelem.
Porty na hostu maji byt explicitni a v souladu s deploy dokumentaci.

Pri remote deployi se HOST_UID a HOST_GID musi odvodit z uzivatele, pod kterym bezi deploy na serveru:
id -u
id -g
Deploy skript musi tyto hodnoty predat do docker compose.
Pred startem musi zajistit existenci potrebnych host adresaru.
Deploy skript nesmi kopirovat ani prepisovat runtime konfiguraci v /home/agent/shift-planner/conf.
Bind-mounted conf/ je server-managed runtime stav; deploy ma pouze overit, ze pozadovane soubory a povinne klice na serveru existuji.
Pokud se objevi root-owned soubory v data/ nebo logs/, musi byt ownership srovnan pred dalsim startem.
Pri zmene runtime kontraktu musi deploy skript, compose a dokumentace zustat ve shode.

Kazdy modul zapisuje aktivni log do logs/<module_name>.log.
Rotace probiha po 100 MB.
Rotovane soubory maji format <module_name>.0001.log, <module_name>.0002.log, ...
Aktivni log po rotaci zustava <module_name>.log.

Kazda dlouhodobe bezici produkcni sluzba musi mit restart: unless-stopped.
HTTP sluzby, ktere spravujeme v tomto repu, musi vystavovat GET /healthz.
GET /healthz vraci JSON:
healthy: 200 {"status":"ok"}
unhealthy: 503 {"status":"unhealthy","reason":"..."}
Compose ma mit healthcheck vsude, kde je to technicky rozumne.
Probe v healthchecku je service-specific:
nepouzivej slepe curl, pokud image nema curl
pro Python image je v poradku probe pres python
pro ne-HTTP sluzby je v poradku heartbeat nebo process-based probe
Pokud jde o third-party image, je prijatelny vendor-specific endpoint nebo zdokumentovana vyjimka.
shift-planner-jobs je scheduler, ne HTTP sluzba; preferovany probe je heartbeat-based healthcheck.

Host adresare data/ a logs/ musi byt zapisovatelne runtime UID:GID.
Kontejner nesmi pri beznem startu vytvaret root-owned soubory v bind mountech.
Pokud modul zapisuje jen do logs, musi stale umet bezet pod non-root uzivatelem.

Pri zmene Dockerfile, docker-compose*.yml nebo deploy skriptu zkontroluj vzdy vsechny body:

Otevri tento dokument vzdy, kdyz: