Come fare self-hosting di Directus nel 2026: database, upload e URL pubblico

Considera Directus come un piccolo sistema, non come una Docker image. L'obiettivo rivolto agli utenti per Directus è chiaro: API REST e GraphQL più un'interfaccia di amministrazione sui tuoi dati; il deployment è accettabile solo quando puoi eseguire il bootstrap dell'amministratore, creare una collection e un ruolo, scrivere tramite REST, interrogare tramite GraphQL e caricare un file.

Questa distinzione permette di individuare il problema che gli operatori incontrano dopo i test locali: il client del database è errato oppure lo storage degli upload non è scrivibile. Inoltre, rende il piano di backup e upgrade abbastanza specifico da poter essere testato.

Dimostra che Directus sopravvive alla sostituzione

Un container image può essere scaricato di nuovo; database, upload, estensioni, flow e snapshot dello schema no. Monta /directus/database prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è effettivamente persistente. Controlla il mount effettivo invece di fidarti del nome di un file Compose e verifica che l'utente del runtime possa scrivere dove Directus lo richiede.

Scegli la retention e una destinazione esterna all'host, quindi prova il ripristino senza toccare la produzione. La procedura è superata solo quando schema, ruoli, flow, item, estensioni e upload vengono ripristinati e i probe REST e GraphQL hanno esito positivo. Per lo stato basato sul database, affianca agli snapshot dello storage export coerenti con l'applicazione, come descritto in point-in-time recovery versus snapshots.

La struttura di Directus in produzione

Traccia tre confini intorno a Directus: l'ingress verso la porta 8055, lo stato persistente e i requisiti di supporto. Il container è sostituibile, ma gli altri due elementi devono avere responsabili espliciti. Il contratto di rete di Directus prevede Postgres più Redis e object storage opzionali per i deployment scalati. Mantieni gli endpoint privati sul DNS interno, consenti solo le chiamate in uscita necessarie e assegna a Directus una credenziale di servizio con ambito limitato.

Il diagramma è completo quando un client pulito può eseguire il bootstrap dell'amministratore, creare una collection e un ruolo, scrivere tramite REST, interrogare tramite GraphQL e caricare un file. Raccogli dati su tempi e risorse per il connection pool del database, la concorrenza delle richieste API, i worker di Flow, la generazione delle miniature e lo storage degli upload. Se la transazione fallisce, il primo confine che non si comporta come documentato indica se devi analizzare il routing, la capacità locale o un servizio di supporto.

Dimostra il deployment di Directus end to end

Crea un fixture Directus piccolo e usa-e-getta, conservandolo per ogni release. Il fixture deve eseguire il workflow reale: bootstrap dell'amministratore, creazione di una collection e di un ruolo, scrittura tramite REST, interrogazione tramite GraphQL e upload di un file. Registra il digest dell'immagine, l'hostname esterno, l'indirizzo della dipendenza e il risultato atteso, così un operatore potrà ripetere il test in seguito senza dover interpretare questa guida.

Esegui il fixture tre volte. Prima, usa il deployment appena creato. Poi, sostituisci il container senza toccare lo stato persistente. Infine, ripristina il backup in un ambiente vuoto. La terza esecuzione è superata solo quando schema, ruoli, flow, item, estensioni e upload vengono ripristinati e i probe REST e GraphQL hanno esito positivo. Durante ogni esecuzione, raccogli latenza e uso delle risorse per il connection pool del database, la concorrenza delle richieste API, i worker di Flow, la generazione delle miniature e lo storage degli upload; questo diventa la baseline per gli alert, invece di una percentuale di CPU arbitraria.

Infine, testa deliberatamente il percorso negativo: nega temporaneamente all'identità di test l'accesso a Postgres, Redis e object storage opzionali per i deployment scalati. Verifica che Directus fallisca in modo visibile senza corrompere lo stato, ripristina la condizione corretta e ripeti la transazione con esito positivo. Un record della release contenente questi quattro risultati costituisce un'evidenza più solida degli screenshot di una dashboard o di una risposta curl ottenuta una sola volta.

Avvia Directus con impostazioni predefinite osservabili

Avvia Directus in modo che il percorso rimanga privato fino al completamento del bootstrap.

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

Se il processo entra in un loop, confronta l'utente previsto dall'image con il proprietario di ogni percorso montato. Se rimane attivo, testa localmente la porta 8055 e passa subito al workflow: esegui il bootstrap dell'amministratore, crea una collection e un ruolo, scrivi tramite REST, interroga tramite GraphQL e carica un file. Fissa la versione dell'image solo dopo il superamento di questo controllo end to end e registra la configurazione esatta accanto al servizio.

Credenziali, ruoli e superfici esposte

Chiudi la finestra del bootstrap non appena esiste il primo amministratore fidato. La trappola concreta di Directus consiste nell'utilizzare la password dell'amministratore di bootstrap dopo il primo accesso o nel ruotare SECRET alla cieca; il confine più sicuro consiste nel sostituire le credenziali di bootstrap, usare ruoli con privilegi minimi e mantenere stabile SECRET, perché protegge sessioni e token dell'applicazione.

Genera SECRET una sola volta, non inserirlo in Git e conservarlo con il manifest di ripristino, perché modificarlo può invalidare lo stato applicativo cifrato o firmato. La rete privata deve trasportare le credenziali delle dipendenze e i ruoli all'interno di Directus devono concedere solo l'azione minima utile. Mantieni i body delle richieste sensibili e le risposte dei provider fuori dai log ordinari.

Rendi inequivocabile l'origine pubblica

Evita di usare origini pubbliche temporanee e permanenti per Directus. Imposta invece PUBLIC_URL sull'indirizzo HTTPS canonico, punta il nome DNS scelto alla route della piattaforma e fai il proxy solo verso la porta 8055.

Esegui questa operazione dall'esterno dell'host: esegui il bootstrap dell'amministratore, crea una collection e un ruolo, scrivi tramite REST, interroga tramite GraphQL e carica un file. Se l'ingress fallisce, la guida alla risoluzione dei problemi 502 tratta gli errori relativi a porte e listener. Se Directus riceve la richiesta ma il client del database è errato oppure lo storage degli upload non è scrivibile, ora gli elementi da analizzare sono oltre il proxy.

Test di errore per Directus

Per Directus, monitora una transazione invece di un processo: esegui il bootstrap dell'amministratore, crea una collection e un ruolo, scrivi tramite REST, interroga tramite GraphQL e carica un file. Combina latenza e tasso di errore con il connection pool del database, la concorrenza delle richieste API, i worker di Flow, la generazione delle miniature e lo storage degli upload, così un alert identifica il componente sotto pressione.

La prova dell'upgrade deve verificare insieme le migrazioni dello schema di Directus, le estensioni e il supporto del database vendor. Esegui il ripristino, la migrazione e la transazione prima di sostituire il deployment in produzione. Se il client del database è errato oppure lo storage degli upload non è scrivibile, non cancellare i dati per rendere verde l'avvio; confronta nell'ordine versione, variabili, mount e raggiungibilità delle dipendenze.

Cosa dovrebbe automatizzare Dockup per Directus

Il layer della piattaforma per Directus comprende la porta 8055, l'ingress, TLS, la configurazione del runtime, lo storage e la raggiungibilità delle dipendenze. Dockup può riprodurre questi elementi per la propria infrastruttura o per un server collegato dal cliente.

A quel punto l'operatore completa il layer del prodotto: imposta PUBLIC_URL sull'indirizzo HTTPS canonico; applica questa regola di accesso — sostituisci le credenziali di bootstrap, usa ruoli con privilegi minimi e mantieni stabile SECRET, perché protegge sessioni e token dell'applicazione; quindi esegui “bootstrap dell'amministratore, creazione di una collection e di un ruolo, scrittura tramite REST, interrogazione tramite GraphQL e upload di un file”. Registrare questo test insieme al deployment evita di confondere il provisioning automatizzato con la disponibilità dell'applicazione.

Domande frequenti

Di cosa ha bisogno Directus per un deployment in produzione?

Instrada il container Directus sulla porta 8055 attraverso un'unica origine HTTPS. Il requisito di rete di supporto è Postgres più Redis e object storage opzionali per i deployment scalati. Non considerare Directus pronto finché non puoi eseguire il bootstrap dell'amministratore, creare una collection e un ruolo, scrivere tramite REST, interrogare tramite GraphQL e caricare un file.

Quali dati di Directus devono essere inclusi in un backup?

Rendi persistente /directus/database e includi database, upload, estensioni, flow e snapshot dello schema nello stesso manifest di ripristino. Un ripristino pulito di Directus è superato solo quando schema, ruoli, flow, item, estensioni e upload vengono ripristinati e i probe REST e GraphQL hanno esito positivo.

Directus richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Directus e mantieni la porta 8055 sul percorso interno. Applica correttamente l'impostazione di Directus: imposta PUBLIC_URL sull'indirizzo HTTPS canonico. Per Directus, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come si deve testare un upgrade di Directus?

Ripristina lo stato corrente di Directus in un deployment isolato, applica la versione candidata e ripeti la transazione di accettazione. Presta particolare attenzione, perché le migrazioni dello schema di Directus, le estensioni e il supporto del database vendor devono essere verificati come un'unica unità. Conserva l'image precedente di Directus finché non avrai compreso i confini della migrazione dei dati e del rollback.