Restaurer Paperless-ngx sur un nouveau nas (après sinistre)

Guide : Restaurer Paperless-ngx sur un Nouveau NAS avec Restic (Après Sinistre)

Ce guide décrit les étapes pour restaurer votre instance Paperless-ngx sur un nouveau NAS Synology (NAS2) en utilisant une sauvegarde Restic existante, suite à une défaillance ou une perte du NAS d’origine (NAS1). NAS2 deviendra le nouveau serveur de production pour Paperless-ngx.

Scénario :

NAS1 (Défaillant) : Le NAS hébergeant Paperless-ngx n’est plus opérationnel.
Sauvegarde Restic : Vous disposez d’une sauvegarde Restic valide des données Paperless (créée depuis NAS1), idéalement stockée sur un support externe (disque USB) ou une copie sur un autre emplacement (comme NAS2 via Hyper Backup).
NAS2 (Nouveau/Remplacement) : Un NAS Synology fonctionnel prêt à prendre le relais.
Objectif : Rétablir le service Paperless-ngx sur NAS2 en utilisant la dernière sauvegarde Restic valide.

Prérequis :

Accès SSH activé sur NAS2 avec un compte administrateur.
Docker (Container Manager) et Docker Compose installés et fonctionnels sur NAS2.
Accès au dépôt de sauvegarde Restic valide (ex: via le disque USB de sauvegarde ou une copie restaurée via Hyper Backup sur NAS2).
Connaissance du mot de passe de votre dépôt Restic.
Accès aux fichiers de configuration originaux de Paperless (docker-compose.yml, docker-compose.env / .env). Crucial : Ces fichiers auraient dû être sauvegardés séparément ou récupérés d’une manière ou d’une autre.
Connaissance du mot de passe de la base de données PostgreSQL utilisée par Paperless.
Connaissance de la PAPERLESS_SECRET_KEY utilisée par Paperless.

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

Connexion SSH à NAS2 :
```
ssh VOTRE_UTILISATEUR_ADMIN@IP_DE_NAS2
```
Installation de Restic (si nécessaire) :
- Vérifiez si Restic est installé (restic version).
- Si non, installez-le (cf. section installation dans le tutoriel précédent).

Étape 2 : Accéder au Dépôt de Sauvegarde Restic Valide

Localiser le dépôt Restic :
- Option A (Disque USB) : Connectez le disque USB contenant la sauvegarde Restic à NAS2. Identifiez son point de montage (ex: /volumeUSB1/usbshare1/). Le chemin du dépôt sera par exemple /volumeUSB1/usbshare1/restic.
- Option B (Copie Hyper Backup) : Si vous aviez une tâche Hyper Backup copiant le dépôt Restic sur NAS2, localisez le dossier où cette copie se trouve sur NAS2 (ex: /volume1/restic_backup_nas1/restic).
Notez le chemin complet vers le dossier contenant le dépôt Restic sur NAS2. C’est ce chemin que nous utiliserons.

Étape 3 : Identifier le Snapshot Restic à Restaurer

Définir les Variables d’Environnement Restic :

# Adaptez ce chemin vers VOTRE dépôt Restic sur NAS2
export RESTIC_REPOSITORY="/chemin/vers/votre/depot/restic/sur/nas2"

# Mot de passe du dépôt
export RESTIC_PASSWORD='VOTRE_MOT_DE_PASSE_RESTIC'

Lister les Snapshots :
```
restic snapshots
```
Choisir le Snapshot : Identifiez le snapshot le plus récent et pertinent que vous souhaitez restaurer (généralement latest). Notez son ID court ou utilisez latest. Vérifiez que les chemins sauvegardés correspondent bien à vos données Paperless.

Étape 4 : Préparer la Structure de Dossiers Permanente sur NAS2

Créez les dossiers sur NAS2 qui hébergeront définitivement les données et la configuration de Paperless.

# Chemin standard pour les données et la configuration Docker sur NAS2
mkdir -p /volume1/docker/paperless/data
mkdir -p /volume1/docker/paperless/media
mkdir -p /volume1/docker/paperless/consume
mkdir -p /volume1/docker/paperless/export
# Dossier pour les données de base de données (si externe)
mkdir -p /volume1/docker/paperless/pgdata
# Dossier pour les données Redis
mkdir -p /volume1/docker/paperless/redisdata
# Dossier pour la configuration Docker Compose
mkdir -p /volume1/docker/paperless/config

Adaptez /volume1/docker/paperless/ si vous utilisez une autre structure organisationnelle.

Étape 5 : Exécuter la Restauration Restic vers l’Emplacement Permanent

Restaurez les données du snapshot choisi directement dans les sous-dossiers créés à l’étape précédente. Notez que Restic va recréer le chemin /data/ à l’intérieur de la cible, nous devrons donc déplacer les fichiers ensuite.

Créer un dossier temporaire pour la restauration Restic :
```
mkdir -p /volume1/docker/paperless/restore_temp
```

Lancer la restauration Restic vers ce dossier temporaire :

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

Déplacer les données restaurées vers leurs emplacements permanents :

# Déplacer les données principales
mv /volume1/docker/paperless/restore_temp/data/paperless_data/* /volume1/docker/paperless/data/
# Déplacer les médias
mv /volume1/docker/paperless/restore_temp/data/paperless_media/* /volume1/docker/paperless/media/
# Déplacer les données Postgres
mv /volume1/docker/paperless/restore_temp/data/paperless_pgdata/* /volume1/docker/paperless/pgdata/
# Déplacer les données Redis
mv /volume1/docker/paperless/restore_temp/data/paperless_redisdata/* /volume1/docker/paperless/redisdata/

# Supprimer le dossier temporaire et le dossier /data vide
rm -rf /volume1/docker/paperless/restore_temp

Vérifier et Corriger les Permissions : C’est crucial. Vérifiez les propriétaires numériques (UID:GID) des fichiers/dossiers que vous venez de déplacer et assurez-vous qu’ils correspondent à l’utilisateur qui exécutera Paperless. Appliquez récursivement si nécessaire.

# Vérifier les propriétaires (exemple pour le dossier data)
ls -ln /volume1/docker/paperless/data
# Noter l'UID et GID (ex: 1026 et 100)

# Corriger les permissions pour tous les dossiers de données (si nécessaire)
# Remplacez UID:GID par les valeurs correctes
sudo chown -R UID:GID /volume1/docker/paperless/data
sudo chown -R UID:GID /volume1/docker/paperless/media
sudo chown -R UID:GID /volume1/docker/paperless/pgdata
sudo chown -R UID:GID /volume1/docker/paperless/redisdata
sudo chown -R UID:GID /volume1/docker/paperless/consume
sudo chown -R UID:GID /volume1/docker/paperless/export

Étape 6 : Préparer et Adapter la Configuration Docker Compose sur NAS2

Placer les Fichiers de Configuration Originaux : Copiez vos fichiers docker-compose.yml et docker-compose.env (récupérés de votre sauvegarde de configuration) dans le dossier de configuration permanent sur NAS2 : /volume1/docker/paperless/config/.
Modifier docker-compose.yml (dans /volume1/docker/paperless/config/) :
Ouvrez le fichier et adaptez-le pour l’environnement NAS2 :
- Section volumes (tous services) : Modifiez TOUS les chemins pour qu’ils pointent vers les dossiers permanents sur NAS2 (ceux créés à l’Étape 4).
  - Exemple broker: – /volume1/docker/paperless/redisdata:/data
  - Exemple db: – /volume1/docker/paperless/pgdata:/var/lib/postgresql/data
  - Exemple webserver (data): – /volume1/docker/paperless/data:/usr/src/paperless/data
  - Exemple webserver (media): – /volume1/docker/paperless/media:/usr/src/paperless/media
  - Exemple webserver (consume): – /volume1/docker/paperless/consume:/usr/src/paperless/consume
  - Exemple webserver (export): – /volume1/docker/paperless/export:/usr/src/paperless/export
- Section ports (service webserver) : Utilisez le port standard que vous souhaitez pour Paperless sur NAS2 (ex: 8000:8000 ou 8020:8000), sauf s’il y a un conflit de port sur NAS2.
- Section environment (service webserver) : Ajoutez/Modifiez USERMAP_UID et USERMAP_GID pour correspondre aux IDs numériques utilisés à l’Étape 5 pour corriger les permissions.
- Section volumes: (racine) : Supprimez ou commentez si elle existe.
Modifier docker-compose.env (dans /volume1/docker/paperless/config/) :
Ouvrez le fichier et modifiez impérativement :
- PAPERLESS_URL : Mettez l’URL permanente de Paperless sur NAS2 (avec l’IP ou le nom d’hôte de NAS2 et le port standard).
- PAPERLESS_SECRET_KEY : Assurez-vous qu’elle contient la clé secrète originale.
- PAPERLESS_DBPASS et POSTGRES_PASSWORD : Assurez-vous qu’elles contiennent le mot de passe exact de la base de données originale.
- USERMAP_UID/GID : Commentez ou supprimez ces lignes.
- Autres variables : Vérifiez (PAPERLESS_TIME_ZONE, etc.).

Étape 7 : Lancer la Nouvelle Instance Paperless sur NAS2

Naviguer vers le Dossier de Configuration Permanent :
```
cd /volume1/docker/paperless/config
```
Lancer Docker Compose :
```
docker-compose up -d
```

Étape 8 : Vérifier le Fonctionnement et Finaliser

Statut des Conteneurs : docker-compose ps (Tous doivent être Up).
Logs des Conteneurs : docker-compose logs -f webserver db (Vérifier l’absence d’erreurs).
Accès Web : Accédez via l’URL permanente définie dans PAPERLESS_URL.
Connexion : Utilisez vos identifiants originaux.
Vérification des Données : Confirmez que tout est présent (documents, tags…).

Étape 9 : Actions Post-Restauration

Mise à jour DNS/Reverse Proxy : Si vous utilisiez un nom de domaine, mettez à jour les enregistrements DNS ou la configuration de votre reverse proxy pour pointer vers la nouvelle IP de NAS2.
Configurer les Nouvelles Sauvegardes : Mettez en place une nouvelle tâche de sauvegarde Restic (ou autre) depuis NAS2 vers votre support de sauvegarde. L’ancien dépôt contient l’historique, mais les nouvelles sauvegardes doivent partir du nouvel hôte.
Considérer l’ancien matériel (NAS1) : Décidez quoi faire avec le matériel défaillant.
Noter la perte de données potentielle : Soyez conscient que les données créées entre la dernière sauvegarde Restic et la défaillance de NAS1 sont perdues.

Conclusion

Ce processus vous permet de rétablir le service Paperless-ngx sur un nouveau matériel après un incident majeur. La clé du succès réside dans la validité de la sauvegarde Restic et la récupération des fichiers de configuration originaux (docker-compose.yml et .env). N’oubliez pas de mettre en place immédiatement une nouvelle stratégie de sauvegarde pour la nouvelle instance sur NAS2.