Comment auto-héberger Directus en 2026 : base de données, uploads et URL publique

Considérez Directus comme un petit système, et non comme une simple image Docker. L’objectif fonctionnel de Directus est clair : fournir une API REST et GraphQL ainsi qu’une interface d’administration pour vos données ; le déploiement n’est acceptable que lorsque vous pouvez initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier.

Cette distinction permet de détecter le problème que les opérateurs rencontrent après les tests locaux : le client de base de données est incorrect ou le stockage des uploads n’est pas accessible en écriture. Elle permet également de définir un plan de sauvegarde et de mise à niveau suffisamment précis pour être testé.

Vérifier que Directus survit au remplacement

Une image de conteneur peut être téléchargée à nouveau ; la base de données, les uploads, les extensions, les flows et les snapshots du schéma, eux, ne le peuvent pas. Montez /directus/database avant l’initialisation, écrivez des données d’exemple inoffensives, puis remplacez le conteneur afin de vérifier que ce chemin est réellement persistant. Inspectez le mount effectif au lieu de vous fier au nom d’un fichier Compose, et vérifiez que l’utilisateur du runtime peut écrire à l’emplacement attendu par Directus.

Définissez une politique de rétention et une destination hors hôte, puis répétez la procédure de restauration sans toucher à la production. Le test n’est réussi que lorsque le schéma, les rôles, les flows, les items, les extensions et les uploads sont restaurés, et que les probes REST et GraphQL réussissent toutes les deux. Pour les données stockées dans une base de données, associez les snapshots du stockage à des exports cohérents du point de vue de l’application, comme indiqué dans récupération à un instant donné ou snapshots.

L’architecture de production de Directus

Délimitez trois zones autour de Directus : l’ingress vers le port 8055, l’état durable et les exigences associées. Le conteneur peut être remplacé, mais les deux autres éléments doivent avoir des responsables clairement désignés. Le contrat réseau de Directus repose sur Postgres, avec Redis et un stockage objet facultatifs pour les déploiements à grande échelle. Conservez les endpoints privés sur un DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à Directus un credential de service limité.

Le diagramme est complet lorsqu’un client vierge peut initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier. Collectez les données de durée et de ressources pour le connection pool de la base de données, la concurrence des requêtes API, les workers Flow, la génération des thumbnails et le stockage des uploads. Si la transaction échoue, la première limite qui ne se comporte pas comme documenté indique s’il faut examiner le routage, la capacité locale ou un service associé.

Vérifier le déploiement Directus de bout en bout

Créez une fixture Directus réduite et jetable, puis conservez-la pour chaque release. Cette fixture doit reproduire le workflow réel : initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier. Enregistrez le digest de l’image, le hostname externe, l’adresse de la dépendance et le résultat attendu afin qu’un autre opérateur puisse répéter le test ultérieurement sans avoir à interpréter ce guide.

Exécutez la fixture trois fois. Premièrement, utilisez le déploiement vierge. Deuxièmement, remplacez le conteneur sans toucher à l’état durable. Troisièmement, restaurez la sauvegarde dans un environnement vide. Le troisième test n’est réussi que lorsque le schéma, les rôles, les flows, les items, les extensions et les uploads sont restaurés, et que les probes REST et GraphQL réussissent toutes les deux. À chaque exécution, mesurez la latence et l’utilisation des ressources autour du connection pool de la base de données, de la concurrence des requêtes API, des workers Flow, de la génération des thumbnails et du stockage des uploads ; ces données constituent la baseline des alertes, plutôt qu’un pourcentage de CPU choisi arbitrairement.

Enfin, testez volontairement le chemin négatif : refusez temporairement à l’identité de test l’accès à Postgres, ainsi qu’à Redis et au stockage objet facultatifs pour les déploiements à grande échelle. Vérifiez que Directus échoue de manière visible sans corrompre l’état, rétablissez la configuration correcte, puis répétez la transaction réussie. Un compte-rendu de release contenant ces quatre résultats fournit une preuve plus solide que des captures d’écran d’un dashboard ou qu’une réponse curl obtenue une seule fois.

Lancer Directus avec des valeurs par défaut observables

Démarrez Directus de manière à maintenir la route privée jusqu’à la fin de l’initialisation.

docker run -d \
  --name directus \
  --restart unless-stopped \
  -p 127.0.0.1:8055:8055 \
  -v directus-data:/directus/database \
  -v directus-uploads:/directus/uploads \
  -v directus-extensions:/directus/extensions \
  -e SECRET=replace-with-a-long-random-value \
  -e KEY=replace-with-a-second-long-random-value \
  -e ADMIN_EMAIL=admin@example.com \
  -e ADMIN_PASSWORD=replace-with-a-strong-bootstrap-password \
  -e DB_CLIENT=sqlite3 \
  -e DB_FILENAME=/directus/database/data.db \
  -e PUBLIC_URL=https://app.example.com \
  directus/directus:latest

Si le processus redémarre en boucle, comparez l’utilisateur attendu par l’image avec le propriétaire de chaque chemin monté. S’il reste actif, testez localement le port 8055, puis passez directement au workflow : initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier. Ne fixez la version de l’image qu’après la réussite de cette vérification de bout en bout, et consignez la configuration exacte à côté du service.

Credentials, rôles et surfaces exposées

Fermez la fenêtre d’initialisation dès qu’un premier administrateur de confiance existe. Le piège concret de Directus consiste à continuer d’utiliser le mot de passe administrateur d’initialisation après la première connexion ou à faire tourner SECRET sans précaution ; la limite la plus sûre consiste à remplacer les credentials d’initialisation, à utiliser des rôles avec le moins de privilèges possible et à conserver SECRET, car il protège les sessions et les tokens de l’application.

Générez SECRET une seule fois, ne le stockez pas dans Git et conservez-le avec le recovery manifest, car sa modification peut invalider l’état chiffré ou signé de l’application. Le réseau privé doit transporter les credentials des dépendances, et les rôles dans Directus doivent accorder uniquement les actions strictement nécessaires. Excluez des logs courants les corps de requête sensibles et les réponses des providers.

Rendre l’origine publique non ambiguë

Évitez les origines publiques temporaires et permanentes pour Directus. Définissez plutôt PUBLIC_URL sur l’adresse HTTPS canonique, faites pointer le nom DNS choisi vers la route de la plateforme et ne faites proxyfier que le port 8055.

Exécutez cette action depuis l’extérieur de l’hôte : initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier. Si l’ingress échoue, le guide de résolution des erreurs 502 couvre les erreurs de port et de listener. Si Directus reçoit la requête mais que le client de base de données est incorrect ou que le stockage des uploads n’est pas accessible en écriture, les éléments disponibles orientent désormais l’analyse au-delà du proxy.

Tests de défaillance pour Directus

Pour Directus, surveillez une transaction plutôt qu’un processus : initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier. Associez sa latence et son taux d’erreur au connection pool de la base de données, à la concurrence des requêtes API, aux workers Flow, à la génération des thumbnails et au stockage des uploads, afin qu’une alerte identifie le composant limité.

La répétition de la mise à niveau doit couvrir le fait que les migrations de schéma Directus, les extensions et la prise en charge du vendor de base de données doivent être vérifiées comme un tout. Restaurez, migrez et exécutez la transaction avant de remplacer la version en production. Si le client de base de données est incorrect ou que le stockage des uploads n’est pas accessible en écriture, n’effacez pas les données pour faire passer le démarrage au vert ; comparez dans cet ordre la version, les variables, les mounts et l’accessibilité des dépendances.

Ce que Dockup doit automatiser pour Directus

La couche plateforme de Directus comprend le port 8055, l’ingress, TLS, la configuration du runtime, le stockage et l’accessibilité des dépendances. Dockup peut reproduire ces éléments pour sa propre infrastructure ou pour un serveur connecté par le client.

L’opérateur termine ensuite la couche produit : définir PUBLIC_URL sur l’adresse HTTPS canonique ; appliquer cette règle d’accès — remplacer les credentials d’initialisation, utiliser des rôles avec le moins de privilèges possible et conserver SECRET, car il protège les sessions et les tokens de l’application ; puis exécuter « initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier ». Enregistrer ce test avec le déploiement évite de confondre le provisioning automatisé avec la disponibilité de l’application.

Questions fréquentes

De quoi Directus a-t-il besoin pour un déploiement en production ?

Faites passer le conteneur Directus sur le port 8055 via une seule origine HTTPS. L’exigence réseau associée est Postgres, avec Redis et un stockage objet facultatifs pour les déploiements à grande échelle. Ne considérez pas Directus comme prêt tant que vous ne pouvez pas initialiser le compte administrateur, créer une collection et un rôle, écrire via REST, interroger via GraphQL et envoyer un fichier.

Quelles données Directus doivent figurer dans une sauvegarde ?

Rendez /directus/database persistant et incluez la base de données, les uploads, les extensions, les flows et les snapshots du schéma dans le même recovery manifest. Une restauration Directus vierge n’est réussie que lorsque le schéma, les rôles, les flows, les items, les extensions et les uploads sont restaurés, et que les probes REST et GraphQL réussissent toutes les deux.

Directus nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de Directus et conservez le port 8055 sur la route interne. Appliquez correctement le paramètre Directus : définissez PUBLIC_URL sur l’adresse HTTPS canonique. Pour Directus, HTTPS protège les credentials et le contenu utilisateur pendant leur transit, et garantit un comportement cohérent du client vis-à-vis de l’origine.

Comment tester une mise à niveau de Directus ?

Restaurez l’état actuel de Directus dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif, car les migrations de schéma Directus, les extensions et la prise en charge du vendor de base de données doivent être vérifiées comme un tout. Conservez l’ancienne image Directus jusqu’à ce que les limites de migration des données et de rollback soient comprises.