Steuerkram/docs/update-backup.md

Update & Backup

Backup

bash scripts/backup.sh

Das Skript erstellt einen Dump der Datenbank sowie ein Archiv der Uploads im Verzeichnis backups/. Die Rotation erfolgt nach folgendem Schema:

• 7 Tages-Backups
• 4 Wochen-Backups
• 12 Monats-Backups

Ein flock-Lock verhindert parallele Läufe bei Verzögerungen.

Manuelles Backup

docker compose exec db mariadb-dump -u steuerkram -psteuerkram steuerkram \
  > ~/steuerkram_backup_$(date +%Y%m%d_%H%M).sql

---

Datenpersistenz

Pfad	Inhalt
./data/mariadb/	MariaDB-Datenbankdateien
./data/belege/	Hochgeladene Belege
./data/logo/	Firmenlogo

Alle drei Pfade liegen außerhalb des Containers und bleiben bei docker compose down erhalten. Details in data/README.md.

Ein vollständiges Backup umfasst Datenbank und Dateien gemeinsam – ohne data/belege verweisen die Beleg-Datensätze der Datenbank ins Leere. scripts/backup.sh sichert beides und warnt, wenn das Datei-Archiv leer bleibt.

Alte Datei-Backups: Archive aus der Zeit vor dem Umzug enthalten ein uploads/-Verzeichnis. scripts/restore.sh erkennt dieses Format und verteilt den Inhalt automatisch auf data/belege und data/logo – solche Backups bleiben also einspielbar.

---

Update

Für ein vollständiges Update steht scripts/update.sh bereit. Es führt alle notwendigen Schritte automatisch aus.

./scripts/update.sh

Das Script erledigt in dieser Reihenfolge:

1. Voraussetzungen – Docker, Docker Compose und Git werden geprüft
2. Backup – scripts/backup.sh wird vor jeder Änderung aufgerufen
3. git pull – Code wird aktualisiert; geänderte Dateien werden erkannt
4. Image-Rebuild – Das Docker-Image wird neu gebaut, wenn Dockerfile, composer.json, composer.lock, php/, apache/ oder docker-entrypoint.sh geändert wurden
5. Container-Neustart – docker compose down --remove-orphans + up -d
6. Healthcheck – Wartet bis die Datenbank healthy meldet (max. 120 s)
7. Migrationen – scripts/intern/migrate.php wird explizit ausgeführt (idempotent)
8. Tests als Gate – PHP-Suite und tests/e2e/run.sh werden ausgeführt; schlägt eine der beiden fehl, endet update.sh mit Exit-Code 1

Tests als Gate

Ein Fehlschlag in Schritt 9 ist kein bloßer Hinweis mehr, sondern bricht das Update mit Exit-Code 1 ab – die zuvor als „erfolgreich" gemeldete, aber ungeprüfte Version lief sonst bereits live weiter. Geprüft werden zwei Suiten:

• PHP-Suite (tests/run.php) – läuft immer.
• E2E-Suite (tests/e2e/run.sh) – läuft nur, wenn auf der Maschine ein e2e-runner-Projekt samt gepulltem Playwright-Image vorhanden ist. Fehlt eines davon (Normalfall auf Produktivmaschinen), überspringt sich run.sh selbst mit Exit-Code 0 – das zählt als bestanden, update.sh lädt dabei nichts nach.

Es gibt keinen automatischen Rollback – Migrationen sind unter Umständen nicht rückwärtskompatibel. Bei rotem Ergebnis nennt update.sh stattdessen laut die Pfade des in Schritt 3 erstellten Backups und verweist auf ./scripts/restore.sh zum manuellen Zurückspielen.

Optionen

Option	Bedeutung
--no-backup	Backup überspringen (z. B. wenn gerade erst gesichert)
--no-tests	Tests nicht ausführen – dokumentierter Notausstieg; die laufende Version bleibt dann ungeprüft
--force-rebuild	Docker-Image immer neu bauen, unabhängig von Dateiänderungen

Migrationen

Datenbankmigrationen werden von scripts/intern/migrate.php verwaltet. Das Script prüft, welche Migrations-Dateien noch nicht angewendet wurden, und führt sie der Reihe nach aus. Es wird sowohl vom Container-Entrypoint als auch von update.sh aufgerufen.

[migrate] Starte Migrations-Prüfung...
[migrate] Führe aus: NNN_beschreibung.sql
[migrate] N Migration(en) erfolgreich angewendet.

Migrationen können auch manuell ausgelöst werden:

docker compose exec web php scripts/intern/migrate.php

Diagnose bei Fehlern

docker compose ps          # Container-Status
docker compose logs web    # Web-Container-Log (PHP-Fehler, Migrationen)
docker compose logs db     # Datenbank-Log

Falls ein Update fehlschlägt und ein Rollback nötig ist, das letzte Backup einspielen:

./scripts/restore.sh

Spielt automatisch das neueste vollständige Backup-Paar (DB + Uploads) ein und führt anschließend ausstehende Migrationen aus. Ein bestimmter Zeitstempel lässt sich explizit angeben: ./scripts/restore.sh 20260517_134945.