restart-condition in container-services

docs/betrieb.md

@@ -152,6 +152,64 @@ Clients die alte Fassung.
 geänderten Werte aus der `.env`. Das hat in diesem Projekt schon mehrfach für
 Verwirrung gesorgt.
 
+## Wenn ein Container verschwindet
+
+```bash
+docker compose ps -a
+docker inspect einkaufsapp_api --format \
+  'Status={{.State.Status}} Exit={{.State.ExitCode}} OOM={{.State.OOMKilled}} Ende={{.State.FinishedAt}}'
+docker compose logs --tail=50 api
+```
+
+Die letzten Zeilen im Log verraten den Grund:
+
+| Im Log | Bedeutung |
+|---|---|
+| `Shutting down` → `Application shutdown complete` → `Stopping reloader process` | Geordnetes Beenden. Jemand hat den Container gestoppt – SIGTERM an PID 1 |
+| Nichts, `OOMKilled=true` | Vom Kernel wegen Speichermangels abgeschossen |
+| Traceback, `Exit=1` | Startfehler, meist Konfiguration oder Migration |
+
+### Geordnetes Beenden aufspüren
+
+```bash
+journalctl --since "yesterday 22:00" --until "today 07:00" | grep -iE "docker|compose|borg"
+grep -rniE "docker (compose )?(stop|down)" /etc/cron* /root /opt 2>/dev/null
+```
+
+Häufigster Verursacher ist ein Sicherungsskript, das Container anhält. **Für
+die Datenbanksicherung ist das nicht nötig:** `mariadb-dump
+--single-transaction` liefert einen konsistenten Stand im laufenden Betrieb.
+
+### Was `restart: unless-stopped` leistet – und was nicht
+
+Der `api`-Container startet jetzt nach Abstürzen und nach einem Neustart des
+Hosts von selbst wieder.
+
+**Nach einem ausdrücklichen `docker compose stop` aber nicht.** Das ist die
+Bedeutung von „unless-stopped": Docker merkt sich, dass der Stopp gewollt war.
+Wenn dein Sicherungsskript Container anhält, muss es sie danach selbst wieder
+starten:
+
+```bash
+docker compose stop
+# ... sichern ...
+docker compose start
+```
+
+Ein Skript, das nur stoppt und sich auf die Neustartregel verlässt, hinterlässt
+eine tote Anwendung – genau das ist hier passiert.
+
+### Kehrseite der Neustartregel
+
+Bricht der Container beim Start ab, etwa wegen einer fehlgeschlagenen
+Migration, versucht Docker es endlos erneut und das Log füllt sich mit
+Wiederholungen. Dann hilft:
+
+```bash
+docker compose stop api
+docker compose logs --tail=60 api      # in Ruhe lesen
+```
+
 ## Speicherplatz im Blick behalten
 
 ```bash