Tester la restauration Paperless avec Restic – nas vers nas

by  on  in Accueil

 

Ce tutoriel décrit le processus de restauration d’une sauvegarde Paperless-ngx, effectuée avec Restic sur un NAS Synology (NAS1), vers un autre NAS Synology (NAS2) à des fins de test. L’objectif est de valider que la sauvegarde est fonctionnelle et que le processus de restauration est maîtrisé, sans impacter l’instance de production sur NAS1.

Scénario :

  • NAS1 (Source) : Héberge l’instance Paperless-ngx active et effectue des sauvegardes Restic des volumes Docker importants (data, media, pgdata, redisdata) vers un dépôt situé sur un disque USB externe (/volumeUSB1/usbshare1/restic/).

  • NAS2 (Cible) : Un autre NAS sur lequel nous allons simuler une restauration complète.

  • Objectif : Lancer une instance Paperless-ngx temporaire sur NAS2 en utilisant les données restaurées depuis la sauvegarde Restic de NAS1.

Prérequis :

  • Accès SSH activé sur les deux NAS avec un compte administrateur.

  • Docker (Container Manager) et Docker Compose installés et fonctionnels sur NAS2.

  • Connaissance de l’adresse IP de NAS1 et NAS2.

  • Connaissance du mot de passe de votre dépôt Restic.

  • Connaissance du mot de passe de la base de données PostgreSQL utilisée par Paperless sur NAS1.

  • Connaissance de la PAPERLESS_SECRET_KEY utilisée sur NAS1.

Étape 1 : Préparation de l’environnement sur NAS2 (NAS Cible)

  1. Connexion SSH à NAS2 :

    ssh VOTRE_UTILISATEUR_ADMIN@IP_DE_NAS2

    (Remplacez avec vos informations).

  2. Installation de Restic (si nécessaire) :

    • Vérifiez si Restic est installé :

      restic version

    • Si la commande échoue, installez-le (adaptez le numéro de version si besoin et l’architecture si NAS2 n’est pas amd64) :

      # Téléchargement (ici pour amd64)
wget https://github.com/restic/restic/releases/download/v0.16.4/restic_0.16.4_linux_amd64.bz2

# Décompression
bunzip2 restic_*.bz2

# Rendre exécutable
chmod +x restic_*_linux_amd64

# Déplacer vers un chemin système (nécessite sudo)
sudo mv restic_*_linux_amd64 /usr/local/bin/restic

# Vérifier l'installation
restic version

Étape 2 : Rendre les Données de Sauvegarde Restic Accessibles sur NAS2

Plusieurs méthodes sont possibles. Nous documentons ici la méthode utilisée : copier localement le dépôt Restic sur NAS2. C’est souvent plus simple et plus fiable pour un test ponctuel.

  1. Connecter le Disque USB de NAS1 à NAS2 : Physiquement débrancher le disque USB contenant le dépôt Restic de NAS1 et le brancher sur un port USB de NAS2.

  2. Identifier le Point de Montage sur NAS2 : Via File Station ou SSH (df -h ou ls /volumeUSB*), identifiez où le disque externe est monté sur NAS2 (ex: /volumeUSB1/usbshare1/).

  3. Créer un Dossier Cible sur NAS2 : Créez un dossier sur un volume interne de NAS2 pour héberger la copie du dépôt Restic. Choisissez un emplacement avec suffisamment d’espace libre.

    # Adaptez /volume1/ si nécessaire
mkdir -p /volume1/restic_repo_copy

  4. Copier le Dépôt Restic : Utilisez la commande cp ou rsync pour copier le contenu du dossier Restic du disque USB vers le dossier cible créé.

    • Identifiez le chemin source exact sur le disque USB (ex: /volumeUSB1/usbshare1/restic).

    • Lancez la copie (exemple avec cp, rsync est plus robuste pour les gros volumes) :

      # Syntaxe: cp -rpv /chemin/source/* /chemin/destination/
# L'option -p préserve les permissions et dates, -r récursif, -v verbose
sudo cp -rpv /volumeUSB1/usbshare1/restic/* /volume1/restic_repo_copy/

    • Cette opération peut prendre du temps selon la taille du dépôt.

  5. (Optionnel) Démonter et Débrancher le Disque USB : Une fois la copie terminée, vous pouvez démonter proprement le disque USB via l’interface DSM ou sudo umount /volumeUSB1/usbshare1 et le débrancher.

Étape 3 : Identifier le Snapshot Restic à Restaurer

  1. Définir les Variables d’Environnement Restic :

    # Chemin vers la COPIE LOCALE du dépôt sur NAS2
export RESTIC_REPOSITORY="/volume1/restic_repo_copy"

# Mot de passe du dépôt (alternative: Restic le demandera)
export RESTIC_PASSWORD='VOTRE_MOT_DE_PASSE_RESTIC'

    (Attention à la sécurité du mot de passe dans l’historique du shell)

  2. Lister les Snapshots :

    restic snapshots

  3. Analyser la Sortie : Repérez le snapshot que vous voulez restaurer (généralement le plus récent, marqué latest). Notez son ID court (ex: f3873301) ou utilisez latest. Vérifiez que les chemins sauvegardés (Paths) incluent bien les données Paperless (/data/paperless_data, /data/paperless_media, /data/paperless_pgdata, /data/paperless_redisdata).

Étape 4 : Préparer le Dossier Cible pour la Restauration sur NAS2

Créez un dossier vide dédié où Restic placera les fichiers restaurés.

# Adaptez /volume1/docker/ si besoin
mkdir -p /volume1/docker/paperless-restore-target

Étape 5 : Exécuter la Restauration Restic (Fichiers Paperless)

Utilisez la commande restic restore avec l’option –include pour n’extraire que les répertoires spécifiques à Paperless.

restic restore latest \
    --target /volume1/docker/paperless-restore-target \
    --include /data/paperless_data \
    --include /data/paperless_media \
    --include /data/paperless_pgdata \
    --include /data/paperless_redisdata

  • latest : Utilise le dernier snapshot. Remplacez par un ID si nécessaire.

  • –target … : Dossier où les fichiers seront restaurés. Restic recréera la structure /data/ à l’intérieur.

  • –include … : Spécifie les chemins exacts à extraire du snapshot.

Attendez la fin de la restauration.

Vérification Post-Restauration :

# Doit afficher un dossier "data"
ls -l /volume1/docker/paperless-restore-target/

# Doit afficher les dossiers paperless_data, paperless_media, etc.
ls -l /volume1/docker/paperless-restore-target/data/

# Très important : noter les propriétaires numériques (UID:GID) des fichiers restaurés
ls -ln /volume1/docker/paperless-restore-target/data/
# Exemple de sortie: drwxrwxrwx 1 1026 100 170 Apr 20 19:50 paperless_data --> UID=1026, GID=100

Étape 6 : Préparer l’Environnement Docker Compose sur NAS2

  1. Créer un Dossier pour la Configuration :

    mkdir -p /volume1/docker/paperless-restore-compose
cd /volume1/docker/paperless-restore-compose

  2. Copier les Fichiers de Configuration Originaux : Copiez les fichiers docker-compose.yml et docker-compose.env de votre installation Paperless originale (depuis NAS1) dans ce dossier /volume1/docker/paperless-restore-compose sur NAS2.

  3. Modifier docker-compose.yml (sur NAS2) :
    Ouvrez /volume1/docker/paperless-restore-compose/docker-compose.yml avec un éditeur (nano, vim). Apportez les modifications suivantes :

    • Services broker, db, webserver – Section volumes : Modifiez TOUS les chemins de volumes pour qu’ils pointent vers les données restaurées dans /volume1/docker/paperless-restore-target/data/.

      • Exemple broker : – /volume1/docker/paperless-restore-target/data/paperless_redisdata:/data

      • Exemple db : – /volume1/docker/paperless-restore-target/data/paperless_pgdata:/var/lib/postgresql/data

      • Exemple webserver (data) : – /volume1/docker/paperless-restore-target/data/paperless_data:/usr/src/paperless/data

      • Exemple webserver (media) : – /volume1/docker/paperless-restore-target/data/paperless_media:/usr/src/paperless/media

    • Service webserver – Section volumes (Consume/Export) : Paperless a besoin de ces dossiers. Faites-les pointer vers des sous-dossiers à créer dans la zone de restauration :

      • – /volume1/docker/paperless-restore-target/consume:/usr/src/paperless/consume

      • – /volume1/docker/paperless-restore-target/export:/usr/src/paperless/export

    • Service webserver – Section ports : Changez le port hôte pour éviter les conflits sur NAS2 (ex: 8001:8000 au lieu de 8000:8000 ou 8020:8000).

    • Service webserver – Section environment : Ajoutez/Modifiez les variables USERMAP_UID et USERMAP_GID pour correspondre aux IDs numériques notés à la fin de l’Étape 5 (ls -ln).

      environment:
  # ... autres variables ...
  USERMAP_UID: 1026 # Remplacez par votre UID numérique
  USERMAP_GID: 100  # Remplacez par votre GID numérique

    • Section volumes: (à la racine) : Si vous aviez des volumes nommés définis à la racine du fichier (comme data:, media:, etc.), supprimez ou commentez cette section car nous utilisons des bind mounts directs vers les dossiers restaurés.

  4. Créer les Dossiers consume et export et ajuster les permissions :

    mkdir -p /volume1/docker/paperless-restore-target/consume
mkdir -p /volume1/docker/paperless-restore-target/export

# Appliquer les mêmes UID/GID que ceux des données restaurées
sudo chown 1026:100 /volume1/docker/paperless-restore-target/consume
sudo chown 1026:100 /volume1/docker/paperless-restore-target/export
# (Remplacez 1026:100 par vos IDs numériques)

  5. Modifier docker-compose.env (sur NAS2) :
    Ouvrez /volume1/docker/paperless-restore-compose/docker-compose.env avec un éditeur. Vérifiez et modifiez impérativement :

    • PAPERLESS_URL : Mettez l’URL complète pour accéder à Paperless sur NAS2, avec l’IP de NAS2 et le nouveau port défini dans docker-compose.yml. Exemple : PAPERLESS_URL=http://192.168.1.X:8001 (Utilisez l’IP réelle de NAS2).

    • PAPERLESS_SECRET_KEY : Décommentez la ligne si elle l’était et collez la clé secrète exacte de votre installation originale sur NAS1.

    • PAPERLESS_DBPASS et POSTGRES_PASSWORD : Définissez ces deux variables avec le mot de passe exact de votre base de données PostgreSQL originale sur NAS1. C’est crucial pour que le service db démarre avec les données pgdata restaurées et que webserver puisse s’y connecter.

    • USERMAP_UID/GID : Commentez ou supprimez ces lignes si elles existent dans ce fichier, car nous les avons définies dans docker-compose.yml.

    • Autres variables (PAPERLESS_TIME_ZONE, PAPERLESS_OCR_LANGUAGE, etc.) : Assurez-vous qu’elles correspondent à votre configuration originale ou à vos besoins pour le test.

Étape 7 : Lancer l’Instance Paperless Restaurée

  1. Naviguer vers le Dossier de Configuration :

    cd /volume1/docker/paperless-restore-compose

  2. Lancer Docker Compose en mode détaché :

    docker-compose up -d

    Docker va télécharger les images si elles ne sont pas présentes localement, puis créer et démarrer les conteneurs.

Étape 8 : Vérifier le Fonctionnement

  1. Statut des Conteneurs : Attendez une minute ou deux, puis vérifiez que tous les conteneurs sont bien démarrés :

    docker-compose ps

    Tous les services doivent être Up ou running. Le statut healthy pour le webserver est un excellent signe.

  2. Logs des Conteneurs : Vérifiez l’absence d’erreurs majeures au démarrage, notamment pour la base de données et le serveur web :

    docker-compose logs -f webserver db

    Cherchez des erreurs de connexion BDD, de permissions, etc. (Ctrl+C pour arrêter).

  3. Accès Web : Ouvrez un navigateur et allez à l’URL définie dans PAPERLESS_URL (ex: http://<IP_DE_NAS2>:8001). La page de connexion Paperless doit s’afficher.

  4. Connexion : Connectez-vous avec les identifiants (utilisateur/mot de passe) que vous utilisiez sur NAS1. Ne recréez pas d’utilisateur.

  5. Vérification des Données : Naviguez dans l’interface. Vérifiez que vos documents, tags, correspondants, types de documents, etc., sont présents et conformes à l’état de la dernière sauvegarde. Testez l’affichage d’un document.

Étape 9 : Nettoyage (Après Validation du Test)

Une fois que vous avez validé que la restauration fonctionne, il est recommandé de nettoyer l’environnement de test sur NAS2 pour éviter la confusion et libérer les ressources.

  1. Arrêter et Supprimer les Conteneurs de Test :

    cd /volume1/docker/paperless-restore-compose
docker-compose down # Ajoutez -v si vous voulez supprimer des volumes anonymes (normalement pas le cas ici)

  2. Supprimer les Données Restaurées :

    sudo rm -rf /volume1/docker/paperless-restore-target

  3. (Optionnel) Supprimer le Dossier de Configuration Docker Compose de Test :

    # Attention: assurez-vous d'être au bon endroit avant de lancer rm -rf
cd /volume1/docker/
sudo rm -rf paperless-restore-compose

  4. (Optionnel mais recommandé si la copie était temporaire) Supprimer la Copie du Dépôt Restic :

    sudo rm -rf /volume1/restic_repo_copy

    (Ne supprimez PAS ce dossier si vous suivez le plan de garder une copie du dépôt Restic sur NAS2 via Hyper Backup ou autre).

Conclusion

Suivre ces étapes vous permet de tester de manière fiable votre processus de sauvegarde et de restauration Restic pour Paperless-ngx. Avoir effectué ce test avec succès vous donne une grande confiance dans votre capacité à récupérer vos données en cas de problème sur votre NAS principal. N’oubliez pas de réaliser ce test périodiquement (ex: tous les 6 mois ou après des changements majeurs) pour maintenir cette confiance.