Guide de Migration

Ce guide explique comment effectuer une mise à niveau entre les versions de duplistatus. Les migrations sont automatiques : le schéma de la base de données se met à jour automatiquement quand vous démarrez une nouvelle version.

Les étapes manuelles ne sont requises que si vous avez personnalisé les modèles de notification (la version 0.8.x a modifié les variables de modèle) ou les intégrations d'API externes qui nécessitent une mise à jour (la version 0.7.x a modifié les noms de champs API, la version 0.9.x nécessite une authentification).

Vue d'ensemble

duplistatus migre automatiquement votre schéma de base de données lors de la mise à niveau. Le système :

1. Crée une sauvegarde de votre base de données avant d'apporter des modifications
2. Met à jour le schéma de la base de données vers la dernière version
3. Préserve tous les données existantes (serveurs, sauvegardes, configuration)
4. Vérifie que la migration s'est terminée avec succès

Sauvegarde de votre base de données avant la migration

Avant de mettre à niveau vers une nouvelle version, il est recommandé de créer une sauvegarde de votre base de données. Cela vous permet de restaurer vos données en cas de problème lors du processus de migration.

Si vous exécutez la Version 1.2.1 ou ultérieure

Utilisez la fonction de sauvegarde de la base de données intégrée :

1. Accédez à Paramètres → Maintenance de la base de données dans l'interface web
2. Dans la section Sauvegarde de la base de données, sélectionnez un format de sauvegarde :
   • Fichier de base de données (.db) : format binaire — sauvegarde la plus rapide, préserve exactement toute la structure de la base de données
   • Sauvegarde SQL (.sql) : format texte — instructions SQL lisibles par un humain
3. Cliquez sur Télécharger la sauvegarde
4. Le fichier de sauvegarde sera téléchargé sur votre ordinateur avec un nom de fichier horodaté

Pour plus de détails, voir la documentation Maintenance de la base de données.

Si vous exécutez une version antérieure à 1.2.1

Sauvegarde

Vous devez sauvegarder manuellement la base de données avant de continuer. Le fichier de base de données est situé à /app/data/backups.db à l'intérieur du conteneur.

Pour les utilisateurs Linux

Si vous êtes sous Linux, ne vous inquiétez pas de la mise en place de conteneurs auxiliaires. Vous pouvez utiliser la commande native cp pour extraire la base de données directement du conteneur en cours d'exécution vers votre hôte.

Utilisation de Docker ou Podman :

# Replace 'duplistatus' with your actual container name if different
docker cp duplistatus:/app/data/backups.db ./duplistatus-backup-$(date +%Y%m%d).db

(Si vous utilisez Podman, remplacez simplement docker par podman dans la commande ci-dessus.)

Pour les utilisateurs Windows

Si vous exécutez Docker Desktop sur Windows, vous disposez de deux moyens simples pour gérer cela sans utiliser la ligne de commande :

Option A : Utiliser Docker Desktop (le plus simple)

1. Ouvrez le tableau de bord de Docker Desktop.
2. Accédez à l'onglet Conteneurs et cliquez sur votre conteneur duplistatus.
3. Cliquez sur l'onglet Fichiers.
4. Accédez à /app/data/.
5. Cliquez avec le bouton droit sur backups.db et sélectionnez Enregistrer sous... pour le télécharger dans vos dossiers Windows.

Option B : Utiliser PowerShell

Si vous préférez le terminal, vous pouvez utiliser PowerShell pour copier le fichier sur votre Bureau :

docker cp duplistatus:/app/data/backups.db $HOME\Desktop\duplistatus-backup.db

Si vous utilisez des montages de liaison

Si vous avez initialement configuré votre conteneur à l'aide d'un montage de liaison (par exemple, vous avez mappé un dossier local comme /opt/duplistatus au conteneur), vous n'avez besoin d'aucune commande Docker. Copiez simplement le fichier à l'aide de votre gestionnaire de fichiers :

• Linux : cp /path/to/your/folder/backups.db ~/backups.db
• Windows : Copiez simplement le fichier dans l'Explorateur de fichiers à partir du dossier que vous avez désigné lors de la configuration.

Restauration de vos données

Si vous devez restaurer votre base de données à partir d'une sauvegarde précédente, suivez les étapes ci-dessous en fonction de votre système d'exploitation.

IMPORTANT

Arrêtez le conteneur avant de restaurer la base de données pour éviter la corruption des fichiers.

Pour les utilisateurs Linux

La méthode la plus simple pour restaurer consiste à « pousser » le fichier de sauvegarde vers le chemin de stockage interne du conteneur.

Utilisation de Docker ou Podman :

# stop the container
docker stop duplistatus

# Replace 'duplistatus-backup.db' with your actual backup filename
docker cp ./duplistatus-backup.db duplistatus:/app/data/backups.db

# Restart the container
docker start duplistatus

Pour les utilisateurs Windows

Si vous utilisez Docker Desktop, vous pouvez effectuer la restauration via l'interface graphique ou PowerShell.

Option A : Utiliser Docker Desktop (interface graphique)

1. Assurez-vous que le conteneur duplistatus est en cours d'exécution (Docker Desktop exige que le conteneur soit actif pour pouvoir transférer des fichiers via l'interface graphique).
2. Allez dans l'onglet Fichiers des paramètres de votre conteneur.
3. Accédez à /app/data/.
4. Cliquez avec le bouton droit sur le fichier backups.db existant et sélectionnez Supprimer.
5. Cliquez sur le bouton Importer (ou cliquez avec le bouton droit dans la zone du dossier) et sélectionnez votre fichier de sauvegarde depuis votre ordinateur.

Renommez le fichier importé en exactement backups.db s'il contient un horodatage dans le nom.

Redémarrez le conteneur.

Option B : Utiliser PowerShell

# Copy the file from your Desktop back into the container
docker cp $HOME\Desktop\duplistatus-backup.db duplistatus:/app/data/backups.db

# Restart the container
docker start duplistatus

Si vous utilisez des montages liés (bind mounts)

Si vous utilisez un dossier local mappé vers le conteneur, vous n'avez pas besoin de commandes spéciales.

1. Arrêter le conteneur.
2. Copier manuellement votre fichier de sauvegarde dans votre dossier mappé (par exemple, /opt/duplistatus ou C:\duplistatus_data).
3. Vérifier que le fichier est nommé exactement backups.db.
4. Démarrer le conteneur.

docker logs <container-name>

note

Si vous restaurez la base de données manuellement, vous pouvez rencontrer des erreurs de permissions.

Vérifiez les journaux du conteneur et ajustez les permissions si nécessaire. Consultez la section Troubleshooting ci-dessous pour plus d'informations.

Processus de migration automatique

Quand vous démarrez une nouvelle version, les migrations s'exécutent automatiquement :

1. Création de sauvegarde : Une sauvegarde horodatée est créée dans votre répertoire de données
2. Mise à jour du schéma : Les tables et champs de la base de données sont mis à jour selon les besoins
3. Migration des données : Tous les données existantes sont préservées et migrées
4. Vérification : Le succès de la migration est enregistré

Surveillance de la migration

Vérifiez les journaux Docker pour surveiller la progression de la migration :

Recherchez des messages comme :

• « Found X pending migrations »
• « Running consolidated migration X.0... »
• « Migration X.0 completed successfully »
• « Database backup created: /path/to/backups-copy-YYYY-MM-DDTHH-MM-SS.db »
• « All migrations completed successfully »

Notes de migration spécifiques à la version

Mise à niveau vers la version 0.9.x ou ultérieure (schéma v4.0)

avertissement

L'authentification est maintenant requise. Tous les utilisateurs doivent se connecter après la mise à niveau.

Qu'est-ce qui change automatiquement

• Le schéma de base de données migre de v3.1 à v4.0
• Nouvelles tables créées : users, sessions, audit_log
• Compte admin par défaut créé automatiquement
• Tous les sessions existantes invalidées

Ce que vous devez faire

1. Connectez-vous avec les identifiants administrateur par défaut :
   • Nom d'utilisateur : admin
   • Mot de passe : Duplistatus09
2. Changez le mot de passe lorsque vous y êtes invité (obligatoire lors de la première connexion)
3. Créez des comptes utilisateurs pour les autres utilisateurs (Paramètres → Utilisateurs)
4. Mettez à jour les intégrations API externes pour inclure l'authentification (voir les Changements d'API non rétrocompatibles)
5. Configurez la rétention des journaux d'audit si nécessaire (Paramètres → Journal d'audit)

Si vous êtes verrouillé

Utilisez l'outil de récupération Admin :

docker exec -it duplistatus /app/admin-recovery admin NewPassword123

Consultez le Guide de récupération Admin pour plus de détails.

Mise à niveau vers la Version 0.8.x

Ce qui change automatiquement

• Schéma de base de données mis à jour vers v3.1
• Clé maître générée pour le chiffrement (stockée dans .duplistatus.key)
• Sessions invalidées (nouvelles sessions protégées par CSRF créées)
• Mots de passe chiffrés à l'aide du nouveau système

Ce que vous devez faire

1. Mettez à jour les modèles de notification si vous les avez personnalisés :
   • Remplacez {backup_interval_value} et {backup_interval_type} par {backup_interval}
   • Les modèles par défaut sont mis à jour automatiquement

Notes de Sécurité

• Assurez-vous que le fichier .duplistatus.key est sauvegardé (dispose des permissions 0400)
• Les sessions expirent après 24 heures

Mise à niveau vers la Version 0.7.x

Ce qui change automatiquement

• table machines renommée en servers
• champs machine_id renommés en server_id
• Nouveaux champs ajoutés : alias, notes, created_at, updated_at

Ce que vous devez faire

1. Mettez à jour les intégrations API externes :
   • Remplacez totalMachines → totalServers dans /api/summary
   • Remplacez machine → server dans les objets de réponse API
   • Remplacez backup_types_count → backup_jobs_count dans /api/lastbackups/{serverId}
   • Mettez à jour les chemins des points de terminaison de /api/machines/... à /api/servers/...
2. Mettez à jour les modèles de notification :
   • Remplacez {machine_name} par {server_name}

Voir Modifications incompatibles avec les versions antérieures de l'API pour les étapes détaillées de migration de l'API.

Liste de contrôle post-migration

Après la mise à niveau, vérifier :

• Tous les serveurs apparaissent correctement dans le tableau de bord
• L'historique des sauvegardes est complet et accessible
• Les notifications fonctionnent (testez NTFY/e-mail)
• Les intégrations API externes fonctionnent (le cas échéant)
• Les paramètres sont accessibles et corrects
• La surveillance des sauvegardes fonctionne correctement
• Connexion réussie (0.9.x+)
• Mot de passe administrateur par défaut modifié (0.9.x+)
• Comptes utilisateurs créés pour les autres utilisateurs (0.9.x+)
• Intégrations d'API externes mises à jour avec authentification (0.9.x+)

Dépannage

La migration échoue

1. Vérifier l'espace disque (la sauvegarde nécessite de l'espace)
2. Vérifier les permissions d'écriture sur le répertoire de données
3. Examiner les journaux du conteneur pour les erreurs spécifiques
4. Restaurer à partir de la sauvegarde si nécessaire (voir Rollback ci-dessous)

Données manquantes après la migration

1. Vérifier que la sauvegarde a été créée (vérifier le répertoire de données)
2. Examiner les journaux du conteneur pour les messages de création de sauvegarde
3. Vérifier l'intégrité du fichier de base de données

Problèmes d'authentification (0.9.x+)

1. Vérifier que le compte admin par défaut existe (vérifier les journaux)
2. Essayer les identifiants par défaut : admin / Duplistatus09
3. Utiliser l'outil de récupération admin si verrouillé
4. Vérifier que la table users existe dans la base de données

Erreurs API

1. Examinez Modifications incompatibles avec les versions antérieures de l'API pour les mises à jour des points de terminaison
2. Mettez à jour les intégrations externes avec les nouveaux noms de champs
3. Ajoutez l'authentification aux requêtes API (0.9.x+)
4. Testez les points de terminaison API après la migration

Problèmes de clé maître (0.8.x+)

1. Assurez-vous que le fichier .duplistatus.key est accessible
2. Vérifier que les permissions du fichier sont 0400
3. Vérifier les journaux du conteneur pour les erreurs de génération de clé

Configuration DNS de Podman

Si vous utilisez Podman et rencontrez des problèmes de connectivité réseau après une mise à niveau, vous devrez peut-être configurer les paramètres DNS pour votre conteneur. Consultez la section Configuration DNS du guide d'installation pour plus de détails.

Procédure de Restauration

Si vous devez revenir à une version précédente :

1. Arrêtez le conteneur : docker stop <container-name> (ou podman stop <container-name>)
2. Localisez votre sauvegarde :
   • Si vous avez créé une sauvegarde via l'interface web (version 1.2.1+), utilisez ce fichier de sauvegarde téléchargé
   • Si vous avez créé une sauvegarde manuelle du volume, extrayez-la d'abord
   • Les sauvegardes automatiques de migration se trouvent dans le répertoire de données (fichiers horodatés .db)
3. Restaurer la base de données :
   • Pour les sauvegardes via l'interface web (version 1.2.1+) : Utilisez la fonction de restauration dans Settings → Database Maintenance (voir Maintenance de la base de données)
   • Pour les sauvegardes manuelles : Remplacez backups.db dans votre répertoire ou volume de données par le fichier de sauvegarde
4. Utilisez la version précédente de l'image : Téléchargez et exécutez l'ancienne version de l'image du conteneur
5. Démarrez le conteneur : Lancez-le avec la version précédente

avertissement

La restauration à une version antérieure peut entraîner une perte de données si le schéma plus récent est incompatible avec la version antérieure. Assurez-vous toujours de disposer d'une sauvegarde récente avant de tenter une restauration.

Dépannage de votre restauration / restauration antérieure

Si l'application ne démarre pas ou que vos données n'apparaissent pas après une restauration ou une restauration antérieure, vérifiez les problèmes courants suivants :

1. Autorisations des fichiers de base de données (Linux/Podman)

Si vous avez restauré le fichier en tant qu'utilisateur root, l'application à l'intérieur du conteneur pourrait ne pas avoir la permission de le lire ou d'y écrire.

• Le symptôme : Les journaux affichent « Permission Denied » ou « Read-only database ».
• La solution : Réinitialisez les permissions du fichier à l'intérieur du conteneur pour assurer son accessibilité.

# Set ownership (usually UID 1000 or the app user)
docker exec -u 0 duplistatus chown 1000:1000 /app/data/backups.db
# Set read/write permissions
docker exec -u 0 duplistatus chmod 664 /app/data/backups.db

2. Nom de fichier incorrect

L'application recherche spécifiquement un fichier nommé backups.db.

• Le symptôme : L'application démarre mais semble « vide » (comme une nouvelle installation).
• La solution : Vérifier le répertoire /app/data/. Si votre fichier s'appelle duplistatus-backup-2024.db ou possède une extension .sqlite, l'application l'ignorera. Utilisez la commande mv ou l'interface graphique de Docker Desktop pour le renommer exactement en backups.db.

3. Conteneur non redémarré

Sur certains systèmes, l'utilisation de docker cp alors que le conteneur est en cours d'exécution peut ne pas actualiser immédiatement la connexion de l'application à la base de données.

• La Solution : Effectuez toujours un redémarrage complet après une restauration :

docker restart duplistatus

4. Incompatibilité de version de base de données

Si vous restaurez une sauvegarde d'une version beaucoup plus récente de duplistatus dans une version plus ancienne de l'application, le schéma de la base de données pourrait être incompatible.

• La Solution : Assurez-vous toujours que vous exécutez la même version (ou une version plus récente) de l'image duplistatus que celle qui a créé la sauvegarde. Vérifiez votre version avec :

docker inspect duplistatus --format '{{.Config.Image}}'

Versions du schéma de base de données

Version de l'application	Version du schéma	Modifications principales
0.6.x et versions antérieures	v1.0	Schéma initial
0.7.x	v2.0, v3.0	Ajout de configurations, renommage des machines → serveurs
0.8.x	v3.1	Champs de sauvegarde améliorés, prise en charge du chiffrement
0.9.x, 1.0.x, 1.1.x, 1.2.x, 1.3.x	v4.0	Contrôle d'accès utilisateur, authentification, journalisation d'audit

Aide

• Documentation : Guide de l'utilisateur
• Référence API : Documentation API
• Modifications API : Modifications API non rétrocompatibles
• Notes de version : Vérifier les notes de version spécifiques pour les modifications détaillées
• Communauté : Discussions GitHub
• Problèmes : Problèmes GitHub