Como fazer self-hosting do Directus em 2026: banco de dados, uploads e URL pública

Trate o Directus como um sistema pequeno, não como uma imagem Docker. O objetivo do Directus para o usuário é claro: uma API REST e GraphQL, além de uma interface de administração sobre seus dados; o deployment só é aceitável quando você consegue fazer o bootstrap do administrador, criar uma collection e uma role, gravar via REST, consultar via GraphQL e fazer upload de um arquivo.

Essa distinção identifica o modo de falha que os operadores encontram depois dos testes locais: o client de banco de dados está incorreto ou o armazenamento de uploads não permite gravação. Ela também torna o plano de backup e upgrade específico o suficiente para ser testado.

Comprove que o Directus sobrevive à substituição

Uma imagem de container pode ser baixada novamente; banco de dados, uploads, extensions, flows e snapshots do schema não podem. Monte /directus/database antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Inspecione o mount efetivo em vez de confiar no nome de um arquivo Compose e verifique se o usuário de runtime consegue gravar no local esperado pelo Directus.

Escolha a retenção e um destino externo ao host e, depois, ensaie a recuperação sem tocar na produção. O exercício só passa quando schema, roles, flows, items, extensions e uploads são restaurados e os probes de REST e GraphQL são bem-sucedidos. Para estados baseados em banco de dados, combine snapshots de storage com exports consistentes com a aplicação, conforme descrito em recuperação point-in-time versus snapshots.

A estrutura de produção do Directus

Trace três limites ao redor do Directus: ingress até a porta 8055, estado durável e requisitos de suporte. O container pode ser substituído, mas os outros dois precisam de responsáveis explícitos. O contrato de rede do Directus é Postgres, além de Redis e object storage opcionais para deployments em escala. Mantenha endpoints privados em DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Directus uma service credential com escopo limitado.

O diagrama está completo quando um client limpo consegue fazer o bootstrap do administrador, criar uma collection e uma role, gravar via REST, consultar via GraphQL e fazer upload de um arquivo. Colete dados de tempo e recursos do database connection pool, da concorrência de requests da API, dos workers do Flow, da geração de thumbnails e do upload storage. Se a transação falhar, o primeiro limite que não se comportar conforme documentado indicará se é necessário investigar o routing, a capacidade local ou um serviço de suporte.

Comprove o deployment do Directus de ponta a ponta

Crie um fixture pequeno e descartável do Directus e mantenha-o para cada release. O fixture deve exercitar o workflow real: fazer o bootstrap do administrador, criar uma collection e uma role, gravar via REST, consultar via GraphQL e fazer upload de um arquivo. Registre o digest da imagem, o hostname externo, o endereço da dependência e o resultado esperado para que outro operador possa repetir o teste sem precisar interpretar este guia.

Execute o fixture três vezes. Primeiro, use o deployment novo. Depois, substitua o container sem tocar no estado durável. Por fim, restaure o backup em um ambiente vazio. A terceira execução só passa quando schema, roles, flows, items, extensions e uploads são restaurados e os probes de REST e GraphQL são bem-sucedidos. Durante cada execução, capture latência e uso de recursos do database connection pool, da concorrência de requests da API, dos workers do Flow, da geração de thumbnails e do upload storage; isso se torna a baseline dos alertas, em vez de uma porcentagem arbitrária de CPU.

Por fim, teste deliberadamente o caminho negativo: negue temporariamente à identidade de teste o acesso ao Postgres, ao Redis e ao object storage opcionais para deployments em escala. Confirme que o Directus falha de forma visível sem corromper o estado, restaure a condição correta e repita a transação bem-sucedida. Um registro de release contendo esses quatro resultados é uma evidência mais forte do que screenshots de um dashboard ou uma resposta única de curl.

Inicie o Directus com defaults observáveis

Inicie o Directus de modo que a rota permaneça privada até a conclusão do 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 o processo entrar em loop, compare o usuário esperado pela imagem com o proprietário de cada caminho montado. Se permanecer ativo, teste a porta 8055 localmente e passe diretamente ao workflow: faça o bootstrap do administrador, crie uma collection e uma role, grave via REST, consulte via GraphQL e faça upload de um arquivo. Fixe a versão da imagem somente depois que essa verificação de ponta a ponta for aprovada e registre a configuração exata junto ao serviço.

Credenciais, roles e superfícies expostas

Feche a janela de bootstrap assim que o primeiro administrador confiável existir. A armadilha concreta do Directus é continuar usando a senha de admin do bootstrap após o primeiro login ou fazer rotate de SECRET às cegas; o limite mais seguro é substituir as credenciais de bootstrap, usar roles com least privilege e manter SECRET estável, pois ele protege sessões e tokens da aplicação.

Gere SECRET uma vez, mantenha-o fora do Git e preserve-o com o recovery manifest, pois alterá-lo pode invalidar o estado criptografado ou assinado da aplicação. A rede privada deve transportar as credenciais das dependências, e as roles dentro do Directus devem conceder a menor ação útil. Mantenha bodies sensíveis de requests e responses de providers fora dos logs de rotina.

Torne a origem pública inequívoca

Evite origens públicas temporárias e permanentes para o Directus. Em vez disso, defina PUBLIC_URL como o endereço HTTPS canônico, aponte o nome DNS escolhido para a rota da plataforma e faça proxy apenas para a porta 8055.

Execute essa ação de fora do host: faça o bootstrap do administrador, crie uma collection e uma role, grave via REST, consulte via GraphQL e faça upload de um arquivo. Se o ingress falhar, o guia de troubleshooting de 502 aborda erros de porta e listener. Se o Directus receber a request, mas o client de banco de dados estiver incorreto ou o upload storage não permitir gravação, as evidências agora apontam para além do proxy.

Exercícios de falha para o Directus

No Directus, monitore uma transação em vez de um processo: faça o bootstrap do administrador, crie uma collection e uma role, grave via REST, consulte via GraphQL e faça upload de um arquivo. Combine a latência e a taxa de erros com o database connection pool, a concorrência de requests da API, os workers do Flow, a geração de thumbnails e o upload storage para que um alerta identifique o componente sob restrição.

O ensaio de upgrade deve abranger a verificação conjunta das schema migrations, extensions e do suporte ao database vendor do Directus. Restaure, faça a migration e execute a transação antes de substituir o ambiente de produção. Se o client de banco de dados estiver incorreto ou o upload storage não permitir gravação, não apague dados para fazer o startup ficar verde; compare versão, variáveis, mounts e reachability das dependências, nessa ordem.

O que o Dockup deve automatizar para o Directus

A camada de plataforma do Directus consiste na porta 8055, ingress, TLS, configuração de runtime, storage e reachability das dependências. O Dockup pode reproduzir essas partes na própria infraestrutura ou em um servidor conectado pelo cliente.

Depois, o operador conclui a camada do produto: defina PUBLIC_URL como o endereço HTTPS canônico; aplique esta regra de acesso — substitua as credenciais de bootstrap, use roles com least privilege e mantenha SECRET estável, pois ele protege sessões e tokens da aplicação; e execute “faça o bootstrap do administrador, crie uma collection e uma role, grave via REST, consulte via GraphQL e faça upload de um arquivo”. Registrar esse teste junto ao deployment evita confundir provisionamento automatizado com prontidão da aplicação.

Perguntas frequentes

O que o Directus precisa para um deployment de produção?

Encaminhe o container do Directus na porta 8055 por uma única origem HTTPS. O requisito de rede de suporte é Postgres, além de Redis e object storage opcionais para deployments em escala. Não considere o Directus pronto até conseguir fazer o bootstrap do administrador, criar uma collection e uma role, gravar via REST, consultar via GraphQL e fazer upload de um arquivo.

Quais dados do Directus devem fazer parte de um backup?

Persista /directus/database e inclua banco de dados, uploads, extensions, flows e snapshots do schema no mesmo recovery manifest. Uma restauração limpa do Directus só passa quando schema, roles, flows, items, extensions e uploads são restaurados e os probes de REST e GraphQL são bem-sucedidos.

O Directus exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Directus e mantenha a porta 8055 na rota interna. Aplique corretamente a configuração do Directus: defina PUBLIC_URL como o endereço HTTPS canônico. Para o Directus, o HTTPS protege credenciais ou conteúdo de usuários durante o trânsito e mantém consistente o comportamento do client sensível à origem.

Como testar um upgrade do Directus?

Restaure o estado atual do Directus em um deployment isolado, aplique a versão candidata e repita a transação de acceptance. Dê atenção especial ao fato de que as schema migrations, extensions e o suporte ao database vendor do Directus precisam ser verificados em conjunto. Mantenha a imagem anterior do Directus até entender os limites de data migration e rollback.