agence66-borgmatic/QUICKSTART.md

Guide de démarrage rapide - Borgmatic

Installation et configuration en 5 minutes.

Version requise : Borgmatic ≥ 2.0.0

Installation rapide

# 1. Installer Borgmatic 2.0+ (si pas déjà fait)
sudo apt install pipx
sudo pipx install borgmatic
sudo ln -sf /root/.local/bin/borgmatic /usr/local/bin/borgmatic

# 2. Vérifier la version
borgmatic --version  # Doit être ≥ 2.0.0

# 3. Cloner le dépôt (si pas déjà fait)
git clone <url-du-repo>
cd agence66-borgmatic

# 4. Configurer les variables d'environnement
cp .env.example .env
nano .env  # Éditer avec vos valeurs (voir ci-dessous)

# 5. Installer
sudo ./install.sh

Configuration .env

Éditez .env avec vos valeurs :

# Repository Borg
BORG_REPO=/chemin/vers/votre/repo
# ou pour un repo distant:
# BORG_REPO=ssh://user@backup-server.com/path/to/repo

# Passphrase de chiffrement
BORG_PASSPHRASE=votre-passphrase-securisee

# Notifications ntfy
NTFY_URL=https://ntfy.sh/votre-topic
NTFY_USER=username:password

Configuration SSH (repository distant)

Si votre repository est distant, configurez d'abord les clés SSH :

# Générer une clé SSH
sudo ssh-keygen -t ed25519 -C "borgmatic-backup"
# Appuyez sur Entrée 3 fois (emplacement par défaut, pas de passphrase)

# Copier la clé sur le serveur
sudo ssh-copy-id -p PORT user@backup-server.com

# Tester (ne doit pas demander de mot de passe)
sudo ssh -p PORT user@backup-server.com

# Si ssh-copy-id ne fonctionne pas, méthode manuelle :
# 1. Afficher la clé : sudo cat /root/.ssh/id_ed25519.pub
# 2. Se connecter : ssh -p PORT user@backup-server.com
# 3. Ajouter : echo "VOTRE_CLE" >> ~/.ssh/authorized_keys

Initialiser le repository (si nouveau)

# Repository local
borg init --encryption=repokey-blake2 /path/to/repo

# Repository distant (SSH doit être configuré d'abord)
borg init --encryption=repokey-blake2 ssh://user@server/path/to/repo

# IMPORTANT: Sauvegarder la clé !
borg key export /path/to/repo backup-key.txt

Tests

# 1. Valider la configuration
sudo borgmatic config validate

# 2. Tester les notifications
./scripts/test-notifications.sh

# 3. Vérifier la santé du système
sudo ./scripts/healthcheck.sh

# 4. Test à vide (dry-run)
sudo borgmatic --dry-run --verbosity 2

# 5. Premier backup réel
sudo borgmatic --verbosity 1

Explications des commandes de test

• borgmatic config validate : Vérifie la syntaxe YAML et la structure de config.yaml
• test-notifications.sh : Envoie des notifications de test via ntfy
• healthcheck.sh : Vérifie l'installation, la config, le timer, le repository
• --dry-run : Simule un backup complet sans rien modifier (teste la connexion au repo)
• Sans --dry-run : Exécute un vrai backup

Vérifier le timer

# Vérifier que le timer est actif
systemctl status borgmatic.timer

# Voir quand le prochain backup aura lieu
systemctl list-timers | grep borgmatic

Commandes utiles

# Lister les backups
borgmatic list

# Voir les logs
journalctl -u borgmatic.service -f

# Exécuter un backup manuel
sudo borgmatic

# Restaurer des fichiers
./scripts/restore.sh

# Vérifier l'intégrité
sudo borgmatic check

Compatibilité avec ancien script

Si vous migriez depuis l'ancien script Borg :

1. Votre repository existant est compatible
2. Les archives existantes restent accessibles
3. Le format de nommage est identique
4. Aucune migration n'est nécessaire

Pour vérifier :

# Lister les anciennes archives
borg list $BORG_REPO

# Tester avec borgmatic
borgmatic list

Migration depuis ancien repository

Si vous avez un repository Borg existant, il suffit de :

# 1. Pointer BORG_REPO vers votre repository existant dans .env
BORG_REPO=/path/to/existing/repo

# 2. Utiliser la même passphrase
BORG_PASSPHRASE=votre-ancienne-passphrase

# 3. Tester
borgmatic list  # Devrait afficher vos anciennes archives

En cas de problème

# 1. Valider d'abord la configuration
sudo borgmatic config validate

# 2. Vérifier la santé du système
sudo ./scripts/healthcheck.sh

# 3. Voir les logs
journalctl -u borgmatic.service -n 50

# 4. Tester avec dry-run
sudo borgmatic --dry-run --verbosity 2

# 5. Mode debug (très verbeux)
sudo borgmatic --verbosity 2 --list --log-file-verbosity 2

Erreurs courantes

repositories' is a required property

• Vérifiez que repositories: est présent dans config.yaml
• Vérifiez que BORG_REPO est défini dans .env

Additional properties are not allowed

• Vous utilisez une vieille structure de config pour Borgmatic 1.x
• Mettez à jour vers Borgmatic 2.0+ : sudo pipx install borgmatic --force

command not found: borgmatic

• Créez les liens symboliques : sudo ln -sf /root/.local/bin/borgmatic /usr/local/bin/borgmatic

Support

Consultez le README.md pour plus de détails.