Sauvegarder et restaurer un site auto-hébergé

S'applique à : auto-hébergé (installation manuelle ou Docker), Dokos v5. Sur Dokos Cloud, voir Sauvegardes Dokos Cloud.

Une sauvegarde n'est utile que si vous savez la restaurer. Cette page couvre les quatre règles d'une bonne sauvegarde : planifier, garder la clé, copier hors du serveur, tester.

Ce que contient une sauvegarde

Les commandes s'exécutent dans le dossier du bench. Les fichiers sont écrits dans sites/<site>/private/backups/.

Sauvegarder à la demande

bench --site dokompany.fr backup --with-files

Options utiles : --compress compresse les fichiers (extension .tgz au lieu de .tar), --backup-path <dossier> écrit la sauvegarde dans un autre dossier.

Avec Docker, préfixez la commande : docker compose run backend bench --site frontend backup --with-files --compress. Voir Installation Docker.

Planifier les sauvegardes

bench init ajoute une tâche cron qui sauvegarde la base de tous les sites toutes les 6 heures. Le journal est logs/backup.log. Si la tâche manque, recréez-la :

bench setup backups
crontab -l

Cette tâche ne sauvegarde pas les fichiers. Ajoutez une tâche cron quotidienne avec --with-files.

Le nombre de sauvegardes conservées sur le serveur se règle dans Paramètres Système, onglet Sauvegardes, champ Nombre de Sauvegardes (3 par défaut).

Garder la clé de chiffrement

La clé encryption_key du fichier site_config.json chiffre les champs de type mot de passe (comptes email, passerelles de paiement, clés d'API). Sans elle, un site restauré ne peut plus lire ces valeurs. Conservez une copie de site_config.json avec chaque sauvegarde.

Pour chiffrer aussi les fichiers de sauvegarde, cochez Crypter les sauvegardes dans Paramètres Système. La clé de chiffrement des sauvegardes est alors visible dans la page Télécharger des sauvegardes, bouton Obtenir la clé de cryptage de la sauvegarde (réservé au rôle Responsable système). Notez-la hors du serveur.

Copier les sauvegardes hors du serveur

Une sauvegarde qui reste sur le serveur disparaît avec lui. Copiez le dossier private/backups vers une autre machine ou un stockage objet, avec l'outil de votre choix. En v5, l'envoi automatique vers un stockage externe (S3, Google Drive, Dropbox) fait partie de l'application Offsite Backups, à installer à part. Voir Migrer vers la version 5.

Restaurer un site

bench --site dokompany.fr backup --with-files
bench --site dokompany.fr restore 20261029_020000-dokompany_fr-database.sql.gz \
  --with-public-files 20261029_020000-dokompany_fr-files.tar \
  --with-private-files 20261029_020000-dokompany_fr-private-files.tar
bench --site dokompany.fr migrate

• Pour une sauvegarde chiffrée, ajoutez --encryption-key <clé> si le site ne possède pas déjà cette clé.
• Sur un nouveau serveur, copiez la valeur encryption_key de l'ancien site_config.json dans le nouveau : bench --site dokompany.fr set-config encryption_key "<clé>".
• bench migrate aligne la base sur la version du code installée.

Exemple : tester une restauration chaque mois

L'administrateur de Dokompany restaure la sauvegarde de la nuit sur un site de test test.dokompany.fr, sur le même bench.

bench --site test.dokompany.fr restore /home/dokos/backups/20261029_020000-dokompany_fr-database.sql.gz \
  --with-private-files /home/dokos/backups/20261029_020000-dokompany_fr-private-files.tar
bench --site test.dokompany.fr set-config mute_emails 1
bench --site test.dokompany.fr set-config mute_notifications 1
bench --site test.dokompany.fr set-config mute_payment_gateways 1
bench --site test.dokompany.fr migrate

Il coupe les envois avant de démarrer le site. Voir Copier la production sur un site de test pour le rôle de chaque clé.

Vérifier

• Connectez-vous au site restauré et ouvrez le dernier document créé avant la sauvegarde.
• Ouvrez une pièce jointe : elle s'affiche (fichiers privés restaurés).
• Ouvrez un Compte email : aucune erreur de déchiffrement n'apparaît.

Problèmes fréquents