Aller au contenu

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 -T est obligatoire : sans elle, Docker ouvre un terminal qui corrompt le fichier enregistré.
  • Le format custom est compressé, et l'outil de restauration pg_restore sait 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.

  1. Préparez le répertoire d'installation avec le compose.yaml de la version sauvegardée et le .env sauvegardé. Remplacez X.Y.Z par la version de la sauvegarde, lisible sur la ligne KIREXO_VERSION du .env sauvegardé :

    curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/compose.yaml
    cp sauvegardes/env-AAAAMMJJ-HHMMSS .env
    chmod 600 .env
    

    Résultat attendu : aucune sortie ; compose.yaml et .env sont présents.

  2. Arrêtez l'application et le worker, sur un serveur existant (rien à faire sur un serveur neuf) :

    docker compose stop php worker
    

    Résultat attendu : Docker indique l'arrêt des deux services.

  3. Démarrez la base de données seule :

    docker compose up -d --wait database
    

    Résultat attendu : la commande rend la main sans erreur.

  4. 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.dump
    

    Ré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.

  5. 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.tgz
    

    Résultat attendu : aucune sortie. La commande utilise la même image que l'application, donc les mêmes droits sur le volume.

  6. Redémarrez tout, puis vérifiez :

    docker compose up -d --wait
    docker compose exec php bin/console app:install:check
    

    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