Sauvegarder et restaurer son instance¶
Vous hébergez votre propre instance de Kirexo et vous voulez pouvoir la retrouver intacte après une panne, une mise à jour qui tourne mal ou un changement de serveur.
Prérequis : une instance installée en suivant Installer Kirexo chez soi. Toutes les commandes se lancent depuis le répertoire d'installation, /opt/kirexo si vous avez suivi le tutoriel.
Ce qu'il faut sauvegarder, et rien d'autre¶
Un volume est un espace de stockage que Docker conserve d'un démarrage à l'autre, indépendamment des conteneurs.
| À sauvegarder | Pourquoi |
|---|---|
| Base de données PostgreSQL | Tout l'état de l'instance : comptes, articles, réglages |
Volume kirexo_caddy_data |
Certificats HTTPS et clé du compte Let's Encrypt (entrées HTTP A1 et A2). Les perdre déclenche une réémission complète, et Let's Encrypt limite le nombre de certificats émis par semaine |
Fichier .env |
Les secrets. Sans APP_SECRET et CLAUDE_API_KEY_CIPHER_KEY d'origine : sessions invalidées, clé API Claude illisible |
| Rien d'autre | Aucun stockage de médias. Les volumes kirexo_redis_data et kirexo_rabbitmq_data ne portent que de l'état passager ; kirexo_caddy_config se régénère |
compose.yaml n'est pas à sauvegarder : il se retélécharge par l'adresse de sa version, https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/compose.yaml, où X.Y.Z est la version visée, telle qu'affichée sur la page des versions.
Sauvegarder¶
Ces commandes créent un sous-dossier sauvegardes/ et y déposent trois fichiers portant la date et l'heure : la base, les certificats et une copie de .env. La deuxième commande contrôle au passage que la sauvegarde de la base est lisible.
mkdir -p sauvegardes
horodatage=$(date +%Y%m%d-%H%M%S)
docker compose exec -T database sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > "sauvegardes/kirexo-$horodatage.dump"
docker compose exec -T database pg_restore --list < "sauvegardes/kirexo-$horodatage.dump" > /dev/null && echo "dump lisible"
docker compose exec -T php tar -czf - -C /data . > "sauvegardes/caddy_data-$horodatage.tgz"
cp .env "sauvegardes/env-$horodatage"
chmod 600 sauvegardes/*
Résultat attendu : la ligne dump lisible s'affiche, et ls sauvegardes liste trois fichiers kirexo-….dump, caddy_data-….tgz et env-…, suffixés par la même date.
- L'option
-Test obligatoire : sans elle, Docker ouvre un terminal qui corrompt le fichier enregistré. - Le format
customest compressé, et l'outil de restaurationpg_restoresait le vérifier et le relire. - Copiez
sauvegardes/hors du serveur. Une sauvegarde sur le même disque ne protège pas d'une perte du serveur.
Choisir la fréquence¶
- Base : chaque jour, et systématiquement avant chaque mise à jour.
kirexo_caddy_data: chaque semaine, et après l'ajout de domaines de site (entrée HTTP A2)..env: à chaque modification.
Pour automatiser la sauvegarde quotidienne de la base, ajoutez des lignes à la crontab, la liste des tâches que le système lance à heure fixe. Ouvrez-la avec la commande crontab -e ; si docker exige sudo chez vous, utilisez plutôt la crontab de l'administrateur du système, avec sudo crontab -e.
La première ligne ci-dessous sauvegarde la base chaque jour à 3 h. La seconde, à 4 h, supprime les sauvegardes de la base de plus de 14 jours, pour que le disque ne se remplisse pas : changez 14 pour en garder plus ou moins. Dans la crontab, les % doivent être écrits \% :
0 3 * * * cd /opt/kirexo && docker compose exec -T database sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > "sauvegardes/kirexo-$(date +\%Y\%m\%d-\%H\%M\%S).dump"
0 4 * * * cd /opt/kirexo && find sauvegardes -name 'kirexo-*.dump' -mtime +14 -delete
Résultat attendu : le lendemain, ls sauvegardes liste un nouveau fichier kirexo-….dump. Ces lignes ne copient rien hors du serveur : faites-le en plus, avec l'outil de votre choix, pour qu'une panne du serveur n'emporte pas aussi ses sauvegardes.
Tester une sauvegarde¶
Une sauvegarde qui n'a jamais été relue n'est pas une sauvegarde. Ce test la restaure dans une base temporaire, sans toucher à l'instance. Remplacez kirexo-AAAAMMJJ-HHMMSS.dump par le nom du fichier à tester :
docker compose exec -T database sh -c 'createdb -U "$POSTGRES_USER" kirexo_test_restauration'
docker compose exec -T database sh -c 'pg_restore -U "$POSTGRES_USER" -d kirexo_test_restauration --no-owner' < sauvegardes/kirexo-AAAAMMJJ-HHMMSS.dump
docker compose exec -T database sh -c 'psql -U "$POSTGRES_USER" -d kirexo_test_restauration -tAc "SELECT count(*) FROM \"user\""'
docker compose exec -T database sh -c 'dropdb -U "$POSTGRES_USER" kirexo_test_restauration'
Résultat attendu : la troisième commande affiche le nombre de comptes contenus dans la sauvegarde ; il doit correspondre à celui de votre instance. La dernière commande supprime la base temporaire.
Restaurer¶
Une seule procédure, valable sur le même serveur (retour à un état antérieur) comme sur un nouveau (déménagement). Pour un déménagement, remplissez d'abord sur le nouveau serveur les prérequis d'Installer Kirexo chez soi (Docker, ports), et faites pointer le DNS de votre domaine vers lui. Sur un serveur neuf, créez d'abord le répertoire d'installation, comme à l'étape 1 de ce tutoriel, puis copiez-y le dossier sauvegardes/. Placez-vous dans le répertoire d'installation, avec le dossier sauvegardes/ à l'intérieur. Remplacez AAAAMMJJ-HHMMSS par la date et l'heure de la sauvegarde à restaurer.
-
Préparez le répertoire d'installation avec le
compose.yamlde la version sauvegardée et le.envsauvegardé. RemplacezX.Y.Zpar la version de la sauvegarde, lisible sur la ligneKIREXO_VERSIONdu.envsauvegardé :curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/compose.yaml cp sauvegardes/env-AAAAMMJJ-HHMMSS .env chmod 600 .envRésultat attendu : aucune sortie ;
compose.yamlet.envsont présents. -
Arrêtez l'application et le worker, sur un serveur existant (rien à faire sur un serveur neuf) :
Résultat attendu : Docker indique l'arrêt des deux services.
-
Démarrez la base de données seule :
Résultat attendu : la commande rend la main sans erreur.
-
Recréez une base vide, puis restaurez la sauvegarde :
docker compose exec -T database sh -c 'dropdb -U "$POSTGRES_USER" --force --if-exists "$POSTGRES_DB" && createdb -U "$POSTGRES_USER" "$POSTGRES_DB"' docker compose exec -T database sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner' < sauvegardes/kirexo-AAAAMMJJ-HHMMSS.dumpRésultat attendu : aucune erreur. La base est recréée plutôt que restaurée par-dessus l'existante : en retour à une version antérieure, les tables ajoutées par la version plus récente resteraient sinon en place.
-
Restaurez les certificats (
kirexo_caddy_data), sans démarrer l'application :docker compose run --rm --no-deps -T --entrypoint tar php -xzf - -C /data < sauvegardes/caddy_data-AAAAMMJJ-HHMMSS.tgzRésultat attendu : aucune sortie. La commande utilise la même image que l'application, donc les mêmes droits sur le volume.
-
Redémarrez tout, puis vérifiez :
Résultat attendu : le diagnostic se termine par
[OK] Installation opérationnelle.Connectez-vous ensuite avec un compte existant.
Ne lancez jamais docker compose down -v
L'option -v supprime les volumes, donc la base de données et les certificats.
Voir aussi¶
- Mettre à jour son instance — la sauvegarde y est la deuxième étape, et le retour arrière s'appuie sur cette restauration.
- Paramètres de l'instance — protéger
.env.