Sauvegarder et restaurer Forgejo

forgejo dump crée un fichier ZIP unique qui contient tout : la base de données, les dépôts Git, la configuration, les clés SSH, les avatars et les données LFS. Cette page explique comment créer, vérifier et restaurer ce backup — avec une automatisation cron pour ne plus y penser.

La procédure a été testée en lab : une instance Forgejo 14.0.3 sauvegardée, complètement détruite et restaurée depuis le ZIP. Résultat : HTTP 200, dépôts et configuration intacts.

Ce que contient un backup Forgejo

forgejo dump produit un fichier .zip dont le contenu type est :

Fichier dans le ZIP	Contenu
app.ini	Fichier de configuration principal
forgejo-db.sql	Export SQL complet de la base de données
data/	Queues, indexeurs, LFS, clés SSH, avatars, sessions
repos/	Tous les dépôts Git (format bare)

Glissez pour voir

SQLite vs PostgreSQL

Avec SQLite (base par défaut), forgejo-db.sql contient l’intégralité de la base. Avec PostgreSQL ou MySQL, ce fichier est absent du ZIP — la base doit être sauvegardée séparément avec pg_dump ou mysqldump. Planifiez les deux sauvegardes ensemble.

Préparer le répertoire de backup

sudo mkdir -p /var/lib/forgejo/backups
sudo chown git:git /var/lib/forgejo/backups
sudo chmod 750 /var/lib/forgejo/backups

Le répertoire doit appartenir à l'utilisateur git

forgejo dump s’exécute sous l’utilisateur git. Si le répertoire destination appartient à root, la commande échoue avec permission denied. Vérifiez toujours avec ls -la /var/lib/forgejo/.

Créer un backup

Backup manuel (service arrêté – recommandé)

Arrêter le service garantit la cohérence des données, notamment pour SQLite qui n’a pas de mécanisme de snapshot transactionnel externe.

# Arrêter le service
sudo systemctl stop forgejo.service

# Créer le backup
sudo -u git forgejo dump \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini \
  -f /var/lib/forgejo/backups/forgejo-dump-$(date +%Y%m%d-%H%M).zip

# Vérifier le fichier créé
ls -lh /var/lib/forgejo/backups/

# Relancer le service
sudo systemctl start forgejo.service

Un backup d’une instance vide pèse environ 2 Mo. Avec des dépôts réels, la taille correspond à la somme des dépôts + les données LFS.

Backup à chaud (service en cours)

Forgejo permet de créer un backup sans arrêter le service. Ce mode convient aux instances très actives qui ne peuvent pas tolérer une interruption, au prix d’un risque (très faible) d’incohérence des données en cours d’écriture.

sudo -u git forgejo dump \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini \
  -f /var/lib/forgejo/backups/forgejo-hot-$(date +%Y%m%d-%H%M).zip

Videz les queues avant un backup à chaud

Pour minimiser le risque de perte de données lors d’un backup à chaud, videz d’abord les queues internes :

sudo -u git forgejo manager flush-queues \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini

Vérifier le contenu d’un backup

# Lister les fichiers dans le ZIP
unzip -l /var/lib/forgejo/backups/forgejo-dump-20260328-1200.zip | head -30

# Vérifier que les éléments essentiels sont présents
unzip -l /var/lib/forgejo/backups/forgejo-dump-20260328-1200.zip | grep -E "app.ini|forgejo-db.sql|repos/"

Automatiser avec cron

Créez un script de backup et planifiez-le avec cron.

Script de backup

sudo tee /usr/local/bin/forgejo-backup.sh << 'EOF'
#!/bin/bash
set -e

BACKUP_DIR="/var/lib/forgejo/backups"
FORGEJO_WORK="/var/lib/forgejo"
FORGEJO_CONF="/etc/forgejo/app.ini"
RETENTION_DAYS=30
LOG="/var/log/forgejo-backup.log"

echo "[$(date '+%Y-%m-%d %H:%M:%S')] Début du backup Forgejo" >> "$LOG"

# Arrêt du service
systemctl stop forgejo.service

# Backup
BACKUP_FILE="${BACKUP_DIR}/forgejo-$(date +%Y%m%d-%H%M).zip"
sudo -u git forgejo dump \
  -w "$FORGEJO_WORK" \
  -c "$FORGEJO_CONF" \
  -f "$BACKUP_FILE"

# Redémarrage
systemctl start forgejo.service

# Nettoyage des anciens backups
find "$BACKUP_DIR" -name "forgejo-*.zip" -mtime "+${RETENTION_DAYS}" -delete

SIZE=$(du -sh "$BACKUP_FILE" | cut -f1)
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Backup terminé : $BACKUP_FILE ($SIZE)" >> "$LOG"
EOF

sudo chmod 750 /usr/local/bin/forgejo-backup.sh

Planification cron (toutes les nuits à 2h)

# Ouvrir le crontab root (le script utilise systemctl qui nécessite root)
sudo crontab -e

Ajoutez la ligne :

0 2 * * * /usr/local/bin/forgejo-backup.sh

Vérifier les logs de sauvegarde

cat /var/log/forgejo-backup.log

Restaurer depuis un backup

1. Préparer la restauration

   La restauration écrase les données existantes. Si votre instance est en production, assurez-vous d’avoir communiqué une fenêtre de maintenance.

   sudo systemctl stop forgejo.service

2. Extraire le backup

   Le répertoire d’extraction doit appartenir à l’utilisateur git, sinon la restauration produira des fichiers avec de mauvaises permissions.

   BACKUP_FILE="/var/lib/forgejo/backups/forgejo-20260328-1200.zip"
   RESTORE_DIR="/tmp/forgejo-restore"
   
   # Créer le répertoire avec les bons droits
   sudo rm -rf "$RESTORE_DIR"
   sudo mkdir "$RESTORE_DIR"
   sudo chown git:git "$RESTORE_DIR"
   
   # Extraire
   sudo -u git unzip -q "$BACKUP_FILE" -d "$RESTORE_DIR"
   
   # Vérifier
   ls "$RESTORE_DIR"
   # Doit afficher : app.ini  data/  repos/  forgejo-db.sql

3. Restaurer la configuration

   sudo cp "$RESTORE_DIR/app.ini" /etc/forgejo/app.ini
   sudo chown git:git /etc/forgejo/app.ini
   sudo chmod 640 /etc/forgejo/app.ini

4. Restaurer les données

   rsync -a préserve les permissions et écrase les fichiers existants :

   sudo rsync -a --chown=git:git "$RESTORE_DIR/data/" /var/lib/forgejo/data/

   Si le répertoire repos/ du backup est distinct de data/forgejo-repositories/ :

   sudo rsync -a --chown=git:git "$RESTORE_DIR/repos/" \
     /var/lib/forgejo/data/forgejo-repositories/

5. Relancer le service et vérifier

   sudo systemctl start forgejo.service
   sudo systemctl status forgejo.service
   
   # Test HTTP
   curl -o /dev/null -sw "%{http_code}" http://localhost:3000/
   # Doit afficher 200

6. Nettoyer les fichiers temporaires

   sudo rm -rf /tmp/forgejo-restore

Vérifier l'intégrité après restauration

Après la restauration, utilisez forgejo doctor pour vérifier l’instance :

sudo -u git forgejo doctor check --all \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini

Tous les contrôles doivent être marqués OK. Si certains échouent (ex. hooks manquants), la commande propose souvent une correction automatique avec --fix.

Stratégie de rétention

Volume de changements	Fréquence backup	Rétention
Petite instance, peu de commits	Quotidien	30 jours
Instance active (>10 développeurs)	2x/jour	14 jours + backup hebdo 3 mois
Instance critique	Toutes les heures (hot)	7 jours + backup quotidien 1 mois

Glissez pour voir

Externalisez les backups : copiez les ZIP vers un stockage distant (S3, NFS, autre serveur) pour vous protéger contre la perte du serveur Forgejo lui-même.

Dépannage

permission denied lors de forgejo dump

ls -la /var/lib/forgejo/backups/
# Vérifier que le répertoire appartient à git
sudo chown git:git /var/lib/forgejo/backups

unzip: cannot create file lors de la restauration

# Vérifier les droits du répertoire d'extraction
ls -la /tmp/forgejo-restore/
sudo chown git:git /tmp/forgejo-restore/

La restauration ne trouve pas les dépôts

Vérifiez que REPOSITORY_ROOT dans app.ini correspond au chemin où vous avez restauré les dépôts :

sudo grep -A5 "^\[repository\]" /etc/forgejo/app.ini
# ROOT = /var/lib/forgejo/data/forgejo-repositories

À retenir

• forgejo dump produit un ZIP complet : config, DB SQL, dépôts, LFS, avatars
• Le répertoire de destination du backup doit appartenir à l’utilisateur git
• Le service doit être arrêté pour un backup cohérent (surtout avec SQLite)
• La restauration suit le principe : extraire (en tant que git) → copier app.ini → rsync data/ → démarrer
• Avec PostgreSQL/MySQL, la base de données n’est pas dans le ZIP — sauvegardez-la séparément
• Externaliser les backups est indispensable pour se protéger d’une perte serveur

Prochaines étapes

Mettre à jour Forgejo Procédure d'upgrade avec backup pré-upgrade et vérification doctor check.

Configuration initiale Sécuriser app.ini et désactiver les inscriptions publiques.

×

📖 Voir la documentation →