Backups & Schema-Migrations

🇬🇧 English

Mesh persistiert seine ganze Konfiguration in einer einzigen JSON-Datei und schützt sie automatisch vor Schema-Änderungen.

Wo liegt die Konfiguration?

Im Container: /data/config.json — das wird über das Volume-Mount auf den Host durchgereicht.

Standard auf Unraid: /mnt/user/appdata/itsweber-mesh/config.json.

Schema-Migrations-Chain

Mesh hat eine Migration-Chain (apps/web/src/server/config/migrations.ts). Beim Container-Start läuft runMigrations:

1. Liest aktuelle Config-Version aus dem JSON
2. Wenn Version < CURRENT_VERSION: Migration für jeden Schritt durchlaufen
3. Bei Erfolg: persistierte Config hat neue Version
4. Bei Fehler: Container startet nicht — Logs zeigen genau welcher Schritt

Aktuelle Version: v17 (Stand 2026-04-29).

Automatisches Backup VOR jedem Bump

Vor jedem Schema-Bump legt der Store ein Backup an:

/data/config.json.pre-vN

Beispiele aus dem Live-System:

config.json
config.json.pre-v15
config.json.pre-v16
config.json.pre-v17

Bestehende Backups werden nie überschrieben — wenn pre-v17 schon existiert (z. B. weil der Container schonmal von 16→17 migriert hat), wird ein neuer Bump das Backup nicht ersetzen.

Manuelle Backups

Empfohlen: täglicher rsync auf einen anderen Host:

rsync -av --delete /mnt/user/appdata/itsweber-mesh/ backup-host:/path/to/mesh-backup/

Oder alle paar Tage einen Snapshot des kompletten appdata-Pfads — das ist Unraid-Standard via Appdata-Backup-Plugin.

Restore

docker stop itsweber-mesh


cp config.json.pre-v17 config.json


docker start itsweber-mesh

Beim Start läuft die Migration nochmal — wenn das die selbe Version war, ist es ein No-op.

Was bei einem korrupten Backup tun?

Mesh kann auf einer leeren /data starten — der First-Run-Wizard läuft dann durch und legt eine fresh Config an. Ist also kein Datenverlust möglich, nur Konfigurations-Verlust.

Wenn die config.json zu sehr beschädigt ist:

mv config.json config.json.broken

docker restart itsweber-mesh

Schema-Versionen-Historie

Vollständige Liste: apps/web/src/server/config/migrations.ts.

Pre-Release-Validation

Bei Major-Schema-Bumps testen wir:

1. Live-Config kopieren in eine isolierte Test-Instanz
2. Container mit neuem Image starten → Migration läuft
3. UI manuell durchklicken → keine 500er, keine fehlenden Daten

Erst dann wird :latest aktualisiert.