# Update & Backup

## Backup

```bash
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

```bash
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`](../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.

```bash
./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:

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

### Diagnose bei Fehlern

```bash
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:

```bash
./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`.