Zum Hauptinhalt springen

Backups und Upgrades

Was Sie sichern sollten​

WasWo (Beispiel-compose.yml)Wie
Die Datenbankdas Volume pgdatapg_dump, nächtlich
Hochgeladene Dateiendas Volume uploads oder Ihr S3-BucketVolume kopieren; bei S3 Bucket-Versionierung oder Replikation
Konfiguration.env und compose.ymleine Kopie in Ihrem Passwort-Manager oder Secret-Store aufbewahren

Bewahren Sie APP_ENCRYPTION_KEY getrennt von den Datenbank-Backups auf: Backup und Schlüssel zusammen legen die darin verschlüsselten Secrets offen.

Die Datenbank sichern​

Ein konsistenter Dump, während die App weiterläuft:

cd /srv/sol2flow
docker compose exec -T db pg_dump -U sol2flow -Fc sol2flow > "backup/sol2flow-$(date +%F).dump"

Führen Sie ihn nächtlich aus (cron oder ein systemd-Timer), kopieren Sie die Dumps vom Server weg und löschen Sie alte nach einiger Zeit.

Die Dateien sichern​

Mit dem lokalen Treiber archivieren Sie das Volume uploads:

docker run --rm -v sol2flow_uploads:/data:ro -v "$PWD/backup":/backup alpine \
  tar czf "/backup/uploads-$(date +%F).tar.gz" -C /data .

(Das Volume heißt <project>_uploads; docker volume ls zeigt es an.) Bei S3 schalten Sie die Versionierung für den Bucket ein oder replizieren ihn in einen anderen.

Wiederherstellen​

  1. Stoppen Sie die App, lassen Sie die Datenbank laufen: docker compose stop app.

  2. Stellen Sie die Datenbank in eine leere Datenbank wieder her:

    docker compose exec -T db dropdb -U sol2flow sol2flow
    docker compose exec -T db createdb -U sol2flow sol2flow
    docker compose exec -T db pg_restore -U sol2flow -d sol2flow --no-owner < backup/sol2flow-2026-09-27.dump

  3. Stellen Sie die Dateien im Volume uploads (oder im Bucket) vom selben Zeitpunkt wieder her und übergeben Sie sie dem Benutzer der App (uid 1001):

    docker run --rm -v sol2flow_uploads:/data -v "$PWD/backup":/backup alpine \
      sh -c 'tar xzf /backup/uploads-2026-09-27.tar.gz -C /data && chown -R 1001:1001 /data'

  4. Starten Sie mit demselben APP_ENCRYPTION_KEY und AUTH_SECRET wie zuvor: docker compose up -d.

Testen Sie ab und zu eine Wiederherstellung auf einem Ersatzrechner. Ein Backup, das Sie nie wiederhergestellt haben, ist eine Hoffnung, kein Backup.

Upgrade​

  1. Lesen Sie das Änderungsprotokoll für die Versionen zwischen Ihrer und der neuen; dort stehen alle manuellen Schritte.

  2. Sichern Sie die Datenbank.

  3. Setzen Sie die neue Version in der .env (SOL2FLOW_VERSION=1.3.0), dann:

    docker compose pull
    docker compose up -d
    docker compose logs -f app

Datenbankmigrationen laufen beim Start automatisch. Downgrades werden nicht unterstützt: Um zurückzugehen, stellen Sie das vor dem Upgrade erstellte Backup wieder her, zusammen mit der alten Image-Version.

Upgrade von einem Vorabversions-Image

Vorabversions-Images liefen als Benutzer mit einer zufälligen ID. Die App läuft jetzt als uid und gid 1001; ändern Sie daher einmalig den Besitzer der Dateien, die sie schreibt, bevor Sie die neue Version starten:

docker compose run --rm --no-deps -u root --entrypoint chown app -R 1001:1001 /data/uploads
# ein Verzeichnis des Hosts statt eines Volumes:
sudo chown -R 1001:1001 /srv/sol2flow/uploads

PostgreSQL aktualisieren​

sol2flow unterstützt PostgreSQL 16, 17 und 18; 18 wird empfohlen und läuft in der Beispiel-compose.yml. Eine Installation auf 16 oder 17 funktioniert weiter, Sie wechseln also, wann es Ihnen passt. Eine neue Hauptversion kann ein älteres Datenverzeichnis nicht öffnen: Lassen Sie Ihren db-Dienst unverändert (Image und den Mount /var/lib/postgresql/data), bis Sie die Daten per Dump und Restore umziehen.

  1. Stoppen Sie die App und erstellen Sie einen Dump der Datenbank:

    cd /srv/sol2flow
    docker compose stop app
    docker compose exec -T db pg_dump -U sol2flow -Fc sol2flow > backup/sol2flow-before-pg18.dump
    docker compose down

  2. Stellen Sie in der compose.yml den db-Dienst auf 18 um, mit einem neuen Volume, gemountet unter /var/lib/postgresql (ab 18 legt das Image seine Daten in /var/lib/postgresql/18/docker ab, nicht mehr in …/data):

      db:
        image: postgres:18-alpine
        volumes: [pgdata18:/var/lib/postgresql]
    volumes: { pgdata: {}, pgdata18: {}, uploads: {} }

  3. Starten Sie zuerst nur die Datenbank, spielen Sie den Dump ein und starten Sie dann alles:

    docker compose up -d --wait db
    docker compose exec -T db pg_restore -U sol2flow -d sol2flow --no-owner < backup/sol2flow-before-pg18.dump
    docker compose up -d

Das alte Volume pgdata bleibt unberührt: Um zurückzugehen, stellen Sie die alten db-Zeilen wieder her. Entfernen Sie es, sobald 18 zuverlässig läuft (docker volume rm sol2flow_pgdata).

  • pg_upgrade ist bei großen Datenbanken schneller, braucht aber die Programme beider Versionen. PostgreSQL 18 schaltet Datenprüfsummen für neue Cluster ein; hat der alte Cluster keine (Standard bis 17), legen Sie den neuen mit initdb --no-data-checksums an.
  • Auf einem eigenen PostgreSQL-18-Server sind MD5-Passwörter veraltet: Nutzen Sie SCRAM (password_encryption = scram-sha-256, Standard seit 14) und setzen Sie das Passwort neu, falls es als MD5 gespeichert war.

Verschlüsselungsschlüssel rotieren​

APP_ENCRYPTION_KEY schützt Secrets, die in der Datenbank gespeichert sind. Ändern Sie ihn nur, wenn er offengelegt wurde, und wissen Sie, was dann passiert:

  • Client-Secrets für Single Sign-on werden unlesbar: Geben Sie das Client-Secret jedes Providers neu ein.
  • Secrets und Wiederherstellungscodes der Zwei-Faktor-Authentifizierung werden ungültig: Betroffene Personen brauchen einen Zwei-Faktor-Reset durch Staff (Benutzer und Registrierung).
  • API-Schlüssel funktionieren nicht mehr: Die Personen legen neue an.
  • Signatur-Secrets für Webhooks werden unlesbar: Rotieren Sie sie.

So rotieren Sie den Schlüssel:

  1. Erzeugen Sie einen neuen Schlüssel: openssl rand -base64 32.
  2. Setzen Sie APP_ENCRYPTION_KEY in der .env darauf und führen Sie docker compose up -d aus.
  3. Bearbeiten Sie unter Admin → Authentifizierung jeden OIDC-Provider und geben Sie sein Client-Secret neu ein.
  4. Teilen Sie Ihren Benutzern mit, dass API-Schlüssel neu angelegt und Webhook-Secrets rotiert werden müssen, und setzen Sie die Zwei-Faktor-Authentifizierung für alle zurück, die darum bitten.

Logs​

Die App schreibt JSON-Zeilen auf die Standardausgabe: docker compose logs app. Den Detailgrad legen Sie mit LOG_LEVEL fest. Secrets wie Passwörter und Tokens werden aus Log-Einträgen entfernt.

Um das Log zusätzlich in Dateien aufzubewahren, setzen Sie LOG_FILE=/data/logs/app.log mit dem Volume logs aus dem Beispiel: Die App schreibt eine Datei pro Tag (app-2026-09-30.log, UTC-Tage) und behält die letzten zehn (Einstellungen). Verfolgen Sie es mit docker compose exec app tail -F /data/logs/app.log, oder sichern Sie das Volume wie die Uploads. Um über Fehler informiert zu werden, statt Logs zu lesen, schalten Sie die Fehlerverfolgung ein.