124 lines
4.5 KiB
Markdown
124 lines
4.5 KiB
Markdown
# 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`.
|