Migration de Directus Local Storage vers S3 MinIO

Migrer le stockage local de Directus vers S3 MinIO est une étape essentielle pour améliorer les performances et la scalabilité de vos systèmes. MinIO est un serveur de stockage compatible S3 qui offre une solution puissante et flexible pour gérer vos fichiers.

Les avantages d’une telle migration sont nombreux. Avec MinIO vous pouvez bénéficier d’une solution performante et économique, idéale pour les déploiements locaux ou on-prime. Contrairement à un stockage purement local MinIO offre une meilleure résilience et facilite les sauvegardes centralisées.

Qu'est-ce que MinIO ?

MinIO est une alternative open-source à AWS S3. Il est spécialement conçu pour les environnements locaux et offre une compatibilité complète avec l’API S3. Cela signifie que les applications conçues pour S3 peuvent fonctionner sans modification majeure.

Configuration initiale de MinIO

Préparer l'environnement Docker

Pour utiliser MinIO l'une des premières étapes consiste à configurer un environnement Docker. Voici un exemple de configuration dans un fichier docker-compose.yml :

services:
  minio:
    user: root
    image: bitnami/minio:2023.8.29-debian-11-r0
    environment:
      BITNAMI_DEBUG: "true"
      MINIO_ROOT_USER: "minio"
      MINIO_ROOT_PASSWORD: "passer123"
    ports:
      - '9002:9000'  # Port API S3
      - '9003:9001'  # Port Console Web
    volumes:
      - 'minio_data:/bitnami/minio/data'

volumes:
  minio_data:

Dans cet exemple MinIO est configuré avec un utilisateur et un mot de passe racine. Ces informations seront nécessaires pour se connecter à la console et créer un bucket.

Explications des paramètres critiques :

• BITNAMI_DEBUG : Active les journaux détaillés pour aider au dépannage.
• Ports exposés : Le port 9000 est utilisé pour l’API S3, tandis que le port 9001 permet d’accéder à la console web.
• Volumes : Ils garantissent la persistance des données même après un redémarrage des conteneurs.

Configuration de base de MinIO

Une fois que MinIO est opérationnel, connectez-vous à la console web via http://HOST:9003. Identifiez-vous avec les informations configurées (utilisateur : minio, mot de passe : passer123).

Étapes supplémentaires :

1. Créer un nouveau bucket : Ce bucket servira à stocker les fichiers de Directus. Donnez-lui un nom pertinent, comme directus-bucket.
2. Générer des clés d'accès : Naviguez dans les paramètres de sécurité pour obtenir une clé d’accès et une clé secrète. Elles seront essentielles pour l’intégration avec Directus.

Configuration de Directus pour l'intégration avec S3

Ajout des variables d'environnement

Pour permettre à Directus d'utiliser MinIO, vous devez ajouter des variables spécifiques à la section environment de son service dans docker-compose.yml :

services:
  directus:
    environment:
      STORAGE_S3_DRIVER: "s3"
      STORAGE_S3_KEY: "<votre_access_key>"
      STORAGE_S3_SECRET: "<votre_secret_key>"
      STORAGE_S3_BUCKET: "directus-bucket"
      STORAGE_S3_REGION: "us-east-1"
      STORAGE_S3_ENDPOINT: "http://minio:9000"
      STORAGE_S3_ROOT: "directus"
      STORAGE_S3_ACL: "public-read"
      STORAGE_LOCATIONS: "s3,local"

Ces variables configurent Directus pour envoyer automatiquement les nouveaux fichiers vers le bucket MinIO.

Points importants :

• STORAGE_S3_KEY et STORAGE_S3_SECRET : Ces clés proviennent de la console MinIO.
• STORAGE_S3_ENDPOINT : Utilisez l'URL interne Docker (ici, http://minio:9000) pour une meilleure connectivité.
• STORAGE_LOCATIONS : En conservant local, vous maintenez un accès parallèle au stockage local.

Tests de connectivité entre Directus et MinIO

Pour confirmer que la connexion est fonctionnelle :

1. Monitorez les logs : Utilisez docker logs directus pour vérifier les erreurs liées à S3.
2. Téléversez un fichier test : Assurez-vous qu’il apparaît dans le bucket MinIO.

Migration des fichiers existants

Préparation avant migration

Avant de migrer vos fichiers, prenez les précautions suivantes :

• Sauvegardez la base de données : Effectuez une sauvegarde complète pour éviter toute perte accidentelle.

Identifiez les fichiers locaux : Utilisez cette commande SQL pour compter les fichiers stockés localement :

SELECT COUNT(*) 
FROM public.directus_files 
WHERE storage = 'local';

Cela permet de mesurer l’ampleur de la migration.

Processus de migration

Une fois prêt, suivez ces étapes :

1. Copiez les fichiers locaux vers le bucket MinIO : Utilisez un outil comme aws-cli configuré pour MinIO ou un simple script.

Mettez à jour la base de données :

UPDATE public.directus_files 
SET storage = 's3' 
WHERE storage = 'local';

Ce script redirige tous les fichiers vers leur nouveau stockage S3.

Automatisation de la migration

Pour les grandes quantités de fichiers, un script Python ou Node.js peut être utile. Ces scripts peuvent automatiser la copie et la mise à jour SQL.

Vérification post-migration

Tests de validation

Après la migration, assurez-vous que tout fonctionne comme prévu :

• Accessibilité des fichiers : Vérifiez que les fichiers existants sont toujours accessibles via Directus.
• Téléversements futurs : Téléversez un nouveau fichier pour confirmer qu’il est correctement dirigé vers S3.

Gestion des erreurs

En cas de problème, les fichiers locaux restent accessibles. Vérifiez les logs pour diagnostiquer les problèmes courants, comme des erreurs de permissions ou des configurations incorrectes.

Conseils pour une migration réussie

Importance des sauvegardes

Une migration est une opération délicate. Même avec les meilleures pratiques, des problèmes imprévus peuvent survenir. Avant toute chose :

1. Sauvegardez les fichiers locaux : Copiez tous les fichiers stockés localement dans un emplacement sécurisé.
2. Sauvegardez la base de données Directus : Utilisez un outil comme pg_dump pour PostgreSQL ou l'équivalent pour votre base de données.

Pourquoi ? Ces sauvegardes vous permettront de revenir à l’état initial si une erreur se produit durant la migration.

Planification pendant les périodes creuses

La migration peut prendre du temps, surtout si vous gérez une grande quantité de fichiers. Idéalement, exécutez le processus durant une période de faible activité pour minimiser l’impact sur vos utilisateurs :

• Analysez l’utilisation de votre système : Identifiez les heures creuses.
• Informez vos utilisateurs : Planifiez une maintenance, si nécessaire, pour éviter toute confusion.

Tests dans un environnement de développement

Ne migrez jamais directement en production sans tests préalables. Mettez en place un environnement de test identique pour :

• Vérifier la configuration de MinIO et Directus.
• Simuler la migration avec des fichiers fictifs.
• Identifier et résoudre d’éventuelles erreurs avant de toucher les données réelles.

Dépannage

Résolution des problèmes de connectivité

Les erreurs de connectivité entre Directus et MinIO sont fréquentes si la configuration n’est pas correcte. Voici comment les résoudre :

1. Vérifiez les logs :
   • Pour Directus : docker logs directus.
   • Pour MinIO : docker logs minio.
2. Assurez-vous que les variables d’environnement sont correctes :
   • Confirmez que STORAGE_S3_KEY et STORAGE_S3_SECRET correspondent aux clés générées dans MinIO.
   • Vérifiez que STORAGE_S3_ENDPOINT pointe bien vers http://minio:9000.
3. Testez l’accès avec un client comme aws-cli :

Testez la connexion :

aws s3 ls --endpoint-url=http://localhost:9000

Configurez aws-cli pour MinIO :

aws configure set aws_access_key_id <votre_access_key>
aws configure set aws_secret_access_key <votre_secret_key>
aws configure set default.region us-east-1

Restauration en cas d'échec

Si une erreur majeure survient :

1. Revenez aux fichiers locaux : Étant donné que vous avez conservé les fichiers dans leur emplacement d'origine, la restauration est immédiate.
2. Réinitialisez la base de données : Restaurez la sauvegarde réalisée avant la migration.
3. Identifiez la cause de l’échec :
   • Vérifiez les permissions ACL dans MinIO.
   • Reprenez chaque étape pour détecter les erreurs.

Migrer Directus vers S3 MinIO est un projet qui offre de nombreux avantages, notamment en termes de scalabilité et de gestion centralisée des fichiers. Bien que le processus demande une planification minutieuse, les efforts en valent la peine. En suivant les étapes décrites dans cet article, vous pouvez assurer une transition fluide et sécurisée. Avec MinIO vous profitez d'une solution locale puissante tout en conservant la compatibilité avec l'API S3.

TakkJokk,