Sauvegardes et mises à niveau

Que sauvegarder

Quoi	Où (`compose.yml` d’exemple)	Comment
La base de données	le volume `pgdata`	`pg_dump`, chaque nuit
Les fichiers envoyés	le volume `uploads`, ou votre bucket S3	copier le volume ; pour S3, versionnage ou réplication du bucket
La configuration	`.env` et `compose.yml`	en garder une copie dans votre gestionnaire de mots de passe ou de secrets

Conservez APP_ENCRYPTION_KEY séparément des sauvegardes de la base : une sauvegarde et la clé réunies exposent les secrets chiffrés qu’elle contient.

Sauvegarder la base de données

Un dump cohérent pendant que l’application continue de tourner :

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

Exécutez-le chaque nuit (cron ou timer systemd), copiez les dumps hors du serveur et supprimez les anciens au bout d’un moment.

Sauvegarder les fichiers

Avec le driver local, archivez le 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 .

(Le nom du volume est <project>_uploads ; docker volume ls l’affiche.) Avec S3, activez le versionnage du bucket ou répliquez-le vers un autre.

Restaurer

Arrêtez l’application en laissant tourner la base de données : docker compose stop app.

Restaurez la base dans une base vide :

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

Restaurez les fichiers dans le volume uploads (ou le bucket) à partir du même moment, et attribuez-les à l’utilisateur de l’application (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'

Démarrez avec les mêmes APP_ENCRYPTION_KEY et AUTH_SECRET qu’avant : docker compose up -d.

Testez de temps en temps une restauration sur une machine de rechange : une sauvegarde jamais restaurée n’est qu’un espoir, pas une sauvegarde.

Mettre à niveau

Lisez les nouveautés des versions entre la vôtre et la nouvelle ; elles indiquent les éventuelles étapes manuelles.
Sauvegardez la base de données.

Indiquez la nouvelle version dans .env (SOL2FLOW_VERSION=1.3.0), puis :

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

Les migrations de base de données s’exécutent automatiquement au démarrage. Le retour à une version antérieure n’est pas pris en charge : pour revenir en arrière, restaurez la sauvegarde faite avant la mise à niveau, avec l’ancienne version de l’image.

Mise à niveau depuis une image de préversion

Les images de préversion s’exécutaient avec un utilisateur à l’identifiant aléatoire. L’application s’exécute désormais avec l’uid et le gid 1001 : changez donc une fois le propriétaire des fichiers qu’elle écrit, avant de démarrer la nouvelle version :

docker compose run --rm --no-deps -u root --entrypoint chown app -R 1001:1001 /data/uploads
# un répertoire de l’hôte au lieu d’un volume :
sudo chown -R 1001:1001 /srv/sol2flow/uploads

Mettre à niveau PostgreSQL

sol2flow prend en charge PostgreSQL 16, 17 et 18 ; la 18 est recommandée et c’est elle que lance le compose.yml d’exemple. Une installation en 16 ou 17 continue de fonctionner : changez quand cela vous convient. Une nouvelle version majeure ne peut pas ouvrir un répertoire de données plus ancien : gardez votre service db tel quel (image et montage /var/lib/postgresql/data) jusqu’à ce que vous déplaciez les données par un dump et une restauration.

Arrêtez l’application et faites un dump de la base :

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

Dans compose.yml, passez le service db en 18 avec un nouveau volume, monté sur /var/lib/postgresql (depuis la 18, l’image range ses données dans /var/lib/postgresql/18/docker, et non plus dans …/data) :
```
  db:
    image: postgres:18-alpine
    volumes: [pgdata18:/var/lib/postgresql]
volumes: { pgdata: {}, pgdata18: {}, uploads: {} }
```

Démarrez d’abord la base seule, restaurez le dump, puis démarrez le tout :

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

L’ancien volume pgdata reste intact : pour revenir en arrière, remettez les anciennes lignes du service db. Supprimez-le une fois la 18 bien en place (docker volume rm sol2flow_pgdata).

pg_upgrade est plus rapide pour les grosses bases mais demande les binaires des deux versions. PostgreSQL 18 active les sommes de contrôle des données pour les nouveaux clusters ; si l’ancien n’en a pas (le défaut jusqu’à la 17), créez le nouveau avec initdb --no-data-checksums.
Sur votre propre serveur PostgreSQL 18, les mots de passe MD5 sont dépréciés : utilisez SCRAM (password_encryption = scram-sha-256, le défaut depuis la 14) et redéfinissez le mot de passe s’il était stocké en MD5.

Changer la clé de chiffrement

APP_ENCRYPTION_KEY protège les secrets stockés dans la base de données. Ne la changez que si elle a été exposée, et sachez ce qui se passe :

Les secrets client de l’authentification unique deviennent illisibles : saisissez à nouveau le secret client de chaque fournisseur.
Les secrets d’authentification à deux facteurs et les codes de récupération deviennent invalides : les personnes concernées ont besoin d’une réinitialisation de la double authentification par le staff (Utilisateurs et inscription).
Les clés d’API cessent de fonctionner : chacun en crée de nouvelles.
Les secrets de signature des webhooks deviennent illisibles : renouvelez-les.

Pour changer la clé :

Créez une nouvelle clé : openssl rand -base64 32.
Mettez-la dans APP_ENCRYPTION_KEY dans .env et exécutez docker compose up -d.
Dans Admin → Authentification, modifiez chaque fournisseur OIDC et saisissez à nouveau son secret client.
Prévenez vos utilisateurs que les clés d’API doivent être recréées et les secrets des webhooks renouvelés, et réinitialisez l’authentification à deux facteurs de ceux qui le demandent.

Journaux

L’application écrit des lignes JSON sur la sortie standard : docker compose logs app. Réglez le niveau de détail avec LOG_LEVEL. Les secrets comme les mots de passe et les jetons sont retirés des entrées de journal.

Pour conserver aussi le journal dans des fichiers, définissez LOG_FILE=/data/logs/app.log avec le volume logs de l’exemple : l’application écrit un fichier par jour (app-2026-09-30.log, jours UTC) et garde les dix derniers (réglages). Suivez-le avec docker compose exec app tail -F /data/logs/app.log, ou sauvegardez le volume comme les fichiers envoyés. Pour être prévenu des erreurs plutôt que de lire les journaux, activez le suivi des erreurs.

Que sauvegarder​

Sauvegarder la base de données​

Sauvegarder les fichiers​

Restaurer​

Mettre à niveau​

Mettre à niveau PostgreSQL​

Changer la clé de chiffrement​

Journaux​