Directus 2026 selbst hosten: Datenbank, Uploads und öffentliche URL

Betrachten Sie Directus als kleines System und nicht als Docker-Image. Das Ziel aus Nutzersicht ist klar: eine REST- und GraphQL-API sowie eine Admin-Oberfläche für Ihre Daten. Die Bereitstellung ist erst dann akzeptabel, wenn Sie den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen können.

Diese Unterscheidung macht den Fehler sichtbar, auf den Betreiber nach lokalen Tests stoßen: Der Datenbank-Client ist falsch oder der Upload-Speicher ist nicht beschreibbar. Außerdem wird der Backup- und Upgrade-Plan dadurch konkret genug, um ihn testen zu können.

Nachweisen, dass Directus einen Austausch übersteht

Ein Container-Image kann erneut heruntergeladen werden. Datenbank, Uploads, Extensions, Flows und Schema-Snapshots hingegen nicht. Mounten Sie /directus/database vor der Initialisierung, schreiben Sie harmlose Beispieldaten und ersetzen Sie den Container, um nachzuweisen, dass dieser Pfad tatsächlich persistent ist. Prüfen Sie den tatsächlich aktiven Mount, statt sich auf einen Compose-Dateinamen zu verlassen, und stellen Sie sicher, dass der Runtime-Benutzer an dem von Directus erwarteten Ort schreiben kann.

Legen Sie die Aufbewahrungsdauer und ein Ziel außerhalb des Hosts fest und üben Sie die Wiederherstellung, ohne die Produktion zu berühren. Die Übung ist nur dann erfolgreich, wenn Schema, Rollen, Flows, Items, Extensions und Uploads wiederhergestellt werden und sowohl REST- als auch GraphQL-Probes erfolgreich sind. Für datenbankgestützte Zustände sollten Sie Storage-Snapshots mit anwendungskonsistenten Exporten kombinieren, wie unter Point-in-Time-Recovery im Vergleich zu Snapshots beschrieben.

Die Produktionsstruktur von Directus

Ziehen Sie drei Grenzen um Directus: Ingress zu Port 8055, persistenten Zustand und unterstützende Anforderungen. Der Container ist austauschbar, die beiden anderen Bereiche benötigen jedoch klar benannte Verantwortliche. Der Netzwerkvertrag für Directus umfasst Postgres sowie optional Redis und Object Storage für skalierte Deployments. Halten Sie private Endpunkte im internen DNS, erlauben Sie nur erforderliche ausgehende Verbindungen und geben Sie Directus ein eingeschränktes Service-Credential.

Das Diagramm ist vollständig, wenn ein sauberer Client den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen kann. Erfassen Sie Zeit- und Ressourcendaten für den Datenbank-Connection-Pool, die Parallelität von API-Requests, Flow-Worker, die Thumbnail-Generierung und den Upload-Speicher. Wenn die Transaktion fehlschlägt, zeigt die erste Grenze, die sich nicht wie dokumentiert verhält, ob Routing, lokale Kapazität oder ein unterstützender Service untersucht werden muss.

Das Directus-Deployment Ende zu Ende prüfen

Erstellen Sie ein kleines, verworfbares Directus-Fixture und behalten Sie es für jedes Release. Das Fixture sollte den realen Workflow abbilden: den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen. Erfassen Sie den Image-Digest, den externen Hostnamen, die Adresse der Abhängigkeit und das erwartete Ergebnis, damit ein späterer Betreiber den Test wiederholen kann, ohne diese Anleitung interpretieren zu müssen.

Führen Sie das Fixture dreimal aus. Verwenden Sie zuerst das frische Deployment. Ersetzen Sie anschließend den Container, ohne den persistenten Zustand zu verändern. Stellen Sie im dritten Schritt das Backup in einer leeren Umgebung wieder her. Der dritte Durchlauf ist nur dann erfolgreich, wenn Schema, Rollen, Flows, Items, Extensions und Uploads wiederhergestellt werden und sowohl REST- als auch GraphQL-Probes erfolgreich sind. Erfassen Sie bei jedem Durchlauf Latenz und Ressourcennutzung rund um den Datenbank-Connection-Pool, die Parallelität von API-Requests, Flow-Worker, die Thumbnail-Generierung und den Upload-Speicher. Das bildet die Grundlage für Alerts und nicht etwa ein willkürlich gewählter CPU-Prozentsatz.

Testen Sie abschließend gezielt den negativen Pfad: Verweigern Sie der Testidentität vorübergehend den Zugriff auf Postgres sowie optional Redis und Object Storage für skalierte Deployments. Stellen Sie sicher, dass Directus sichtbar fehlschlägt, ohne den Zustand zu beschädigen, stellen Sie die korrekten Bedingungen wieder her und wiederholen Sie die erfolgreiche Transaktion. Ein Release-Eintrag mit diesen vier Ergebnissen ist aussagekräftiger als Screenshots eines Dashboards oder eine einmalige curl-Antwort.

Directus mit beobachtbaren Standardeinstellungen starten

Starten Sie Directus so, dass die Route bis zum Abschluss der Initialisierung privat bleibt.

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

Wenn der Prozess in einer Schleife läuft, vergleichen Sie den erwarteten Benutzer des Images mit dem Eigentümer jedes gemounteten Pfads. Wenn der Prozess aktiv bleibt, testen Sie Port 8055 lokal und gehen Sie anschließend direkt zum Workflow über: den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen. Pinnen Sie die Image-Version erst, nachdem diese Ende-zu-Ende-Prüfung erfolgreich war, und dokumentieren Sie die exakte Konfiguration neben dem Service.

Zugangsdaten, Rollen und exponierte Oberflächen

Schließen Sie das Initialisierungsfenster, sobald der erste vertrauenswürdige Administrator existiert. Die konkrete Falle bei Directus besteht darin, das Bootstrap-Admin-Passwort nach dem ersten Login weiterzuverwenden oder SECRET unbedacht zu rotieren. Die sicherere Grenze besteht darin, die Bootstrap-Zugangsdaten zu ersetzen, Rollen nach dem Prinzip der geringsten Rechte zu verwenden und SECRET stabil zu halten, da es Anwendungssitzungen und Tokens schützt.

Generieren Sie SECRET einmal, halten Sie es aus Git heraus und bewahren Sie es zusammen mit dem Recovery-Manifest auf, da eine Änderung verschlüsselten oder signierten Anwendungszustand ungültig machen kann. Für Credentials von Abhängigkeiten sollte ein privates Netzwerk verwendet werden, und Rollen innerhalb von Directus sollten nur die jeweils kleinste sinnvolle Aktion erlauben. Halten Sie sensible Request-Bodies und Provider-Antworten aus den regulären Logs heraus.

Den öffentlichen Ursprung eindeutig festlegen

Vermeiden Sie temporäre und dauerhafte öffentliche Origins für Directus. Setzen Sie stattdessen PUBLIC_URL auf die kanonische HTTPS-Adresse, zeigen Sie den gewählten DNS-Namen auf die Plattform-Route und leiten Sie ausschließlich an Port 8055 weiter.

Führen Sie diese Aktion von außerhalb des Hosts aus: den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen. Wenn der Ingress fehlschlägt, behandelt die Anleitung zur 502-Fehlerbehebung Fehler bei Ports und Listenern. Wenn Directus die Anfrage empfängt, aber der Datenbank-Client falsch oder der Upload-Speicher nicht beschreibbar ist, deutet die Evidenz nun auf eine Ursache jenseits des Proxys hin.

Fehlerübungen für Directus

Überwachen Sie bei Directus eine Transaktion und nicht nur einen Prozess: den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen. Kombinieren Sie deren Latenz und Fehlerrate mit dem Datenbank-Connection-Pool, der Parallelität von API-Requests, Flow-Workern, der Thumbnail-Generierung und dem Upload-Speicher, damit ein Alert die begrenzende Komponente identifiziert.

Die Upgrade-Probe muss abdecken, dass Directus-Schema-Migrationen, Extensions und die Unterstützung des Datenbankanbieters als Einheit geprüft werden müssen. Stellen Sie den Zustand wieder her, führen Sie die Migration durch und führen Sie die Transaktion vor dem Austausch in der Produktion aus. Wenn der Datenbank-Client falsch oder der Upload-Speicher nicht beschreibbar ist, löschen Sie keine Daten, nur um einen erfolgreichen Start zu erzwingen. Vergleichen Sie stattdessen Version, Variablen, Mounts und die Erreichbarkeit der Abhängigkeiten in dieser Reihenfolge.

Was Dockup für Directus automatisieren sollte

Die Plattformebene für Directus umfasst Port 8055, Ingress, TLS, Runtime-Konfiguration, Storage und die Erreichbarkeit von Abhängigkeiten. Dockup kann diese Bestandteile für die eigene Infrastruktur oder einen vom Kunden angebundenen Server reproduzieren.

Anschließend vervollständigt der Betreiber die Produktebene: PUBLIC_URL auf die kanonische HTTPS-Adresse setzen; diese Zugriffsregel durchsetzen — Bootstrap-Zugangsdaten ersetzen, Rollen nach dem Prinzip der geringsten Rechte verwenden und SECRET stabil halten, da es Anwendungssitzungen und Tokens schützt; und „den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen“ ausführen. Wenn dieser Test zusammen mit dem Deployment aufgezeichnet wird, lässt sich automatisierte Provisionierung von der Anwendungsbereitschaft unterscheiden.

Häufig gestellte Fragen

Was benötigt Directus für ein Produktions-Deployment?

Routen Sie den Directus-Container über eine HTTPS-Origin auf Port 8055. Die unterstützende Netzwerkanforderung umfasst Postgres sowie optional Redis und Object Storage für skalierte Deployments. Betrachten Sie Directus erst dann als bereit, wenn Sie den Administrator initialisieren, eine Collection und eine Rolle anlegen, über REST schreiben, über GraphQL abfragen und eine Datei hochladen können.

Welche Directus-Daten gehören in ein Backup?

Persistieren Sie /directus/database und nehmen Sie Datenbank, Uploads, Extensions, Flows und Schema-Snapshots in dasselbe Recovery-Manifest auf. Eine saubere Wiederherstellung von Directus ist nur dann erfolgreich, wenn Schema, Rollen, Flows, Items, Extensions und Uploads zurückkehren und sowohl REST- als auch GraphQL-Probes erfolgreich sind.

Benötigt Directus HTTPS hinter einem Reverse Proxy?

Verwenden Sie HTTPS für die öffentliche Directus-Origin und halten Sie Port 8055 auf der internen Route. Wenden Sie die Directus-Einstellung korrekt an: Setzen Sie PUBLIC_URL auf die kanonische HTTPS-Adresse. Bei Directus schützt HTTPS Credentials und Benutzerinhalte bei der Übertragung und sorgt für ein konsistentes, Origin-sensitives Verhalten des Clients.

Wie sollte ein Directus-Upgrade getestet werden?

Stellen Sie den aktuellen Directus-Zustand in einem isolierten Deployment wieder her, wenden Sie die Kandidatenversion an und wiederholen Sie die Abnahmetransaktion. Achten Sie besonders darauf, dass Directus-Schema-Migrationen, Extensions und die Unterstützung des Datenbankanbieters als Einheit geprüft werden müssen. Behalten Sie das vorherige Directus-Image, bis die Grenzen der Datenmigration und des Rollbacks verstanden sind.