agence66-borgmatic/README.md

# Borgmatic Backup

Configuration Borgmatic pour le backup automatique de serveur.

## Vue d'ensemble

Ce dépôt contient la configuration complète pour effectuer des backups automatiques quotidiens à 3h du matin via Borgmatic et BorgBackup.

**Version Borgmatic requise : ≥ 2.0.0** (pour l'interpolation des variables d'environnement)

### Caractéristiques

- **Backup quotidien automatique** à 3h du matin via systemd timer
- **Compression** zstd pour un bon ratio performance/compression
- **Rétention intelligente** : 7 daily, 4 weekly, 6 monthly
- **Notifications** via ntfy pour succès/échec
- **Compatible** avec les backups Borg existants
- **Sécurisé** : chiffrement, exclusions de fichiers sensibles
- **Déploiement automatique** via Gitea Actions lors d'un push Git

## Dossiers sauvegardés

- `/var/www` - Sites web
- `/srv/*` - Services applicatifs personnalisés
- `/etc` - Configurations système
- `/opt/*` - Applications tierces (Nextcloud, Traefik, Docker, etc.)
- `/home` - Répertoires utilisateurs

## Installation

### Prérequis

- Système Linux (Debian/Ubuntu/Arch/Fedora)
- Accès root
- Git installé
- **Borgmatic ≥ 2.0.0** (pour l'interpolation des variables d'environnement)

### Installation rapide

```bash
# Cloner le dépôt
git clone <url-du-repo>
cd agence66-borgmatic

# Copier et configurer les variables d'environnement
cp .env.example .env
nano .env  # Éditer avec vos valeurs

# Éditer la configuration si nécessaire
nano config.yaml  # Ajuster le repository Borg

# Exécuter l'installation
sudo ./install.sh
```

### Configuration manuelle

Si vous préférez installer manuellement :

```bash
# Installer Borgmatic ≥ 2.0.0 via pipx (recommandé)
sudo apt install pipx
sudo pipx install borgmatic

# Créer les liens symboliques
sudo ln -sf /root/.local/bin/borgmatic /usr/local/bin/borgmatic
sudo ln -sf /root/.local/bin/generate-borgmatic-config /usr/local/bin/generate-borgmatic-config

# Installer BorgBackup
sudo apt install borgbackup  # Debian/Ubuntu
# ou
sudo pacman -S borg          # Arch Linux

# Copier les fichiers
sudo mkdir -p /etc/borgmatic/hooks
sudo cp config.yaml /etc/borgmatic/
sudo cp hooks/*.sh /etc/borgmatic/hooks/
sudo chmod +x /etc/borgmatic/hooks/*.sh

# Copier les variables d'environnement
sudo cp .env /etc/borgmatic/
sudo chmod 600 /etc/borgmatic/.env

# Installer les services systemd
sudo cp systemd/borgmatic.service /etc/systemd/system/
sudo cp systemd/borgmatic.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable borgmatic.timer
sudo systemctl start borgmatic.timer
```

## Déploiement Automatique

Ce repository inclut un workflow Gitea Actions pour déployer automatiquement les modifications sur le serveur lors d'un push Git.

### Configuration du déploiement automatique

1. **Générer une clé SSH de déploiement**
   ```bash
   ssh-keygen -t ed25519 -C "gitea-deploy-borgmatic" -f ~/.ssh/gitea-deploy-borgmatic
   ```

2. **Installer la clé publique sur le serveur**
   ```bash
   ssh-copy-id -i ~/.ssh/gitea-deploy-borgmatic.pub user@server
   ```

3. **Configurer les secrets dans Gitea**

   Allez dans **Settings → Secrets** de votre repository et ajoutez :
   - `SERVER_HOST` : adresse du serveur
   - `SERVER_USER` : utilisateur SSH
   - `SSH_PRIVATE_KEY` : contenu de `~/.ssh/gitea-deploy-borgmatic` (clé privée complète)
   - `SSH_PORT` : port SSH (optionnel, 22 par défaut)

4. **Activer Gitea Actions**

   Vérifiez que Gitea Actions est activé dans votre instance Gitea (`app.ini` : `[actions] ENABLED = true`)

### Utilisation

Une fois configuré, chaque push sur `main` déclenche automatiquement :
```bash
cd /opt/borgmatic
git pull origin main
make install
```

Consultez l'onglet **Actions** dans votre repository Gitea pour voir le statut du déploiement.

### Documentation détaillée

Pour plus d'informations sur la configuration du déploiement automatique, consultez [docs/GITEA-ACTIONS.md](docs/GITEA-ACTIONS.md).

## Configuration

### Variables d'environnement (.env)

Éditez `/etc/borgmatic/.env` avec vos valeurs :

```bash
# Repository Borg
BORG_REPO=/path/to/your/repository
# ou pour un repo distant:
BORG_REPO=ssh://user@backup.server.com/path/to/repo

# Passphrase de chiffrement
BORG_PASSPHRASE=your-secure-passphrase

# Configuration ntfy
NTFY_URL=https://ntfy.sh/your-topic
NTFY_USER=username:password
```

### Configuration Borgmatic (config.yaml)

Le fichier `/etc/borgmatic/config.yaml` contient la configuration principale.

Points importants à vérifier :

1. **Repository** : Décommentez et configurez votre repository dans la section `location.repositories`
2. **Chemins** : Ajustez `source_directories` si nécessaire
3. **Exclusions** : Personnalisez `exclude_patterns` selon vos besoins

### Configuration de l'authentification SSH (repository distant)

Si vous utilisez un repository distant via SSH, configurez l'authentification par clé :

```bash
# 1. Générer une clé SSH pour root (si elle n'existe pas)
sudo ssh-keygen -t ed25519 -C "borgmatic-backup"
# Appuyez sur Entrée pour accepter l'emplacement par défaut
# Laissez la passphrase vide pour l'automatisation

# 2. Afficher la clé publique
sudo cat /root/.ssh/id_ed25519.pub

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

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

**Alternative manuelle** (si ssh-copy-id ne fonctionne pas) :

```bash
# Se connecter au serveur distant
ssh -p PORT user@backup-server.com

# Ajouter la clé publique
echo "VOTRE_CLE_PUBLIQUE" >> ~/.ssh/authorized_keys
exit
```

### Initialisation du repository Borg

Si vous utilisez un nouveau repository :

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

# Repository distant
borg init --encryption=repokey-blake2 ssh://user@server/path/to/repo
```

**IMPORTANT** : Sauvegardez la clé de chiffrement !

```bash
borg key export /path/to/repo backup-key.txt
# Conservez ce fichier en lieu sûr !
```

## Utilisation

### Tester la configuration

```bash
# 1. Valider la syntaxe du fichier de configuration
sudo borgmatic config validate

# 2. Tester sans exécuter de backup (dry-run)
sudo borgmatic --dry-run --verbosity 2

# 3. Lister les fichiers qui seront sauvegardés
sudo borgmatic list --json
```

**Note :** `borgmatic config validate` vérifie uniquement la syntaxe YAML et la structure du fichier. Le dry-run teste la connexion au repository et simule un backup complet.

### Exécuter un backup manuel

```bash
# Backup avec verbosité normale
sudo borgmatic --verbosity 1

# Backup avec verbosité détaillée
sudo borgmatic --verbosity 2
```

### Vérifier le timer systemd

```bash
# Statut du timer
systemctl status borgmatic.timer

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

# Logs du dernier backup
journalctl -u borgmatic.service -n 100
```

### Lister les backups

```bash
# Lister toutes les archives
borgmatic list

# Informations détaillées
borg list /path/to/repo
```

### Restaurer des fichiers

```bash
# Monter une archive pour explorer
mkdir /tmp/restore
borg mount /path/to/repo::backup-20250116-0300 /tmp/restore
cd /tmp/restore
# ... copier les fichiers nécessaires ...
cd /
borg umount /tmp/restore

# Extraire directement
borg extract /path/to/repo::backup-20250116-0300 path/to/file

# Avec borgmatic
borgmatic extract --archive backup-20250116-0300 --path path/to/file
```

## Maintenance

### Vérifier l'intégrité

```bash
# Vérification complète du repository
borgmatic check --verbosity 2

# Vérification rapide
borg check /path/to/repo
```

### Nettoyer l'espace disque

Le nettoyage automatique (prune) est déjà configuré avec :

- 7 backups quotidiens
- 4 backups hebdomadaires
- 6 backups mensuels

Pour forcer un nettoyage manuel :

```bash
borgmatic prune --verbosity 1
```

### Compacter le repository

Pour libérer réellement l'espace disque après prune :

```bash
borg compact /path/to/repo
```

## Notifications

Les notifications sont envoyées via ntfy :

- ✅ **Succès** : notification normale avec le nom de l'archive
- ❌ **Échec** : notification haute priorité avec le message d'erreur

Testez manuellement les notifications :

```bash
# Test notification de succès
/etc/borgmatic/hooks/ntfy-success.sh "test-archive" ""

# Test notification d'erreur
/etc/borgmatic/hooks/ntfy-error.sh "Erreur de test"
```

## Sécurité

- Les fichiers `.env` et les clés ne sont **jamais** commités (voir `.gitignore`)
- Les permissions des fichiers sensibles sont restrictives (600)
- Le service systemd utilise `ProtectSystem=strict`
- Les logs sont dans le journal systemd, accessible uniquement en root

## Troubleshooting

### Valider la configuration

Avant tout, vérifiez que votre configuration est valide :

```bash
# Valider la syntaxe
sudo borgmatic config validate

# Si erreur, vérifier les détails
sudo borgmatic config validate --verbosity 2
```

Erreurs courantes :

- `repositories' is a required property` : Manque la section repositories
- `Additional properties are not allowed` : Propriété invalide pour cette version
- Erreurs YAML : Vérifier l'indentation (utiliser des espaces, pas des tabs)

### Le backup ne démarre pas

```bash
# Vérifier le timer
systemctl status borgmatic.timer

# Vérifier le service
systemctl status borgmatic.service

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

### Erreur de connexion au repository

```bash
# Tester la connexion SSH (si distant)
sudo ssh -p PORT user@backup-server

# Vérifier les clés SSH
sudo ls -la /root/.ssh/

# Vérifier les variables d'environnement
sudo cat /etc/borgmatic/.env

# Tester Borg directement
sudo bash -c 'source /etc/borgmatic/.env && borg list $BORG_REPO'
```

### Demande de mot de passe SSH

Si borgmatic demande le mot de passe du serveur distant :

```bash
# 1. Vérifier que la clé SSH existe
sudo ls /root/.ssh/id_ed25519

# 2. Si pas de clé, en générer une
sudo ssh-keygen -t ed25519 -C "borgmatic-backup"

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

# 4. Tester
sudo ssh -p PORT user@backup-server.com
# Ne doit PAS demander de mot de passe
```

### Problème de permissions

```bash
# Vérifier les permissions des fichiers
ls -la /etc/borgmatic/
ls -la /etc/borgmatic/hooks/

# Corriger si nécessaire
sudo chmod 600 /etc/borgmatic/.env
sudo chmod 600 /etc/borgmatic/config.yaml
sudo chmod +x /etc/borgmatic/hooks/*.sh
```

### Notifications ntfy ne fonctionnent pas

```bash
# Tester manuellement
curl -u "$NTFY_USER" \
  -H "Title: Test" \
  -d "Message de test" \
  "$NTFY_URL"

# Vérifier les variables
source /etc/borgmatic/.env
echo $NTFY_URL
echo $NTFY_USER
```

## Ressources

- [Documentation Borgmatic](https://torsion.org/borgmatic/)
- [Documentation BorgBackup](https://borgbackup.readthedocs.io/)
- [ntfy.sh](https://ntfy.sh/)

## Support

Pour tout problème :

1. Consultez la section Troubleshooting
2. Vérifiez les logs : `journalctl -u borgmatic.service -n 100`
3. Testez en mode verbeux : `borgmatic --verbosity 2`

## Licence

Configuration personnalisée pour usage personnel/professionnel.