agence66-borgmatic/QUICKSTART.md

# Guide de démarrage rapide - Borgmatic

Installation et configuration en 5 minutes.

**Version requise : Borgmatic ≥ 2.0.0**

## Installation rapide

```bash
# 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 :

```bash
# 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 :

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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 :

```bash
# 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 :

```bash
# 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

```bash
# 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](README.md) pour plus de détails.