Como instalar Dify com Docker em uma VPS

Objetivo: organizar uma instalação do Dify com Docker Compose em VPS, domínio, TLS, banco, fila e recuperação. Tempo: não medido pelo Runzos, pois este roteiro não foi executado nem restaurado por nossa equipe. Custo: varia com VPS, domínio, backup, tráfego e modelo. Você precisa de VPS, Docker, Docker Compose, DNS e acesso administrativo. Só chame o ambiente de reproduzível após executar os testes indicados.

O que você vai conseguir no final

Ao terminar, você terá um roteiro para preparar uma VPS para o Dify. Ele cobre o domínio, TLS, .env, serviços, worker e worker_beat, validação e recuperação. Não é um laudo de uma instalação do Runzos.

A documentação oficial apresenta Docker Compose como ponto de partida do deploy. O mínimo publicado é CPU com pelo menos 2 cores e 4 GiB de RAM. Veja o quick start do Dify com Docker Compose. Esse mínimo inicia a instalação. Ele não dimensiona RAG, muitos documentos, concorrência alta ou modelos locais.

Pré-requisitos

Antes de começar, reúna estes itens:

• Uma VPS que atenda ao mínimo oficial e tenha espaço para dados e backups.
• Um domínio ou subdomínio com registro DNS apontado para o IP da VPS.
• Docker Engine e o plugin Docker Compose instalados conforme sua distribuição.
• Acesso administrativo por SSH, protegido por uma política de acesso adequada.
• Um destino de backup separado da VPS.
• Decisão sobre o provedor de modelo, plugins, webhooks e armazenamento vetorial.

Não publique PostgreSQL, Redis, sandbox ou serviços de depuração na internet. O proxy web e o acesso administrativo são os pontos que normalmente precisam de regra de rede. A documentação do Docker sobre portas publicadas alerta que uma porta pode ficar acessível em endereços roteáveis do host.

Passo 1: fixe uma release antes de copiar arquivos

Não trate a branch principal como versão de produção. A pesquisa canônica registrou a release 1.17.0 em 2026-09-04. Use uma tag escolhida e registrada no seu procedimento. Antes de atualizar, compare o novo .env.example com seu .env. Uma release pode incluir serviços ou variáveis novos.

git clone --branch 1.17.0 --depth 1 https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

O comando acima é um roteiro baseado na documentação e na tag registrada. O Runzos não executou essa instalação. Confirme a tag disponível e leia o guia oficial antes de rodá-lo no seu servidor.

Passo 2: configure DNS e TLS sem ampliar a exposição

Aponte o domínio ao IP público da VPS. Aguarde o DNS resolver antes da emissão ou validação do certificado. Depois, escolha uma arquitetura: usar o Nginx incluído pelo Dify ou colocar um proxy de borda na frente dele.

Misturar os dois sem definir onde o TLS termina pode causar redirecionamentos, cabeçalhos e renovação confusos. O Compose oficial contempla Nginx, TLS e desafio Certbot opcional. Após a configuração, abra o domínio em janela privada. O navegador deve usar HTTPS e não mostrar aviso de certificado.

Não considere uma tela de login como prova de produção. Ela apenas mostra que o acesso web respondeu. Fila, persistência e recuperação exigem testes separados.

Passo 3: preencha o .env e proteja os segredos

Abra o .env no servidor. Ajuste URLs públicas, domínios, banco, Redis e integrações conforme a arquitetura escolhida. Gere valores secretos novos. Nunca reutilize chaves, senhas ou tokens de exemplo.

Use o .env.example oficial do Dify como referência direta para as variáveis disponíveis. Ele é uma referência de configuração, não um arquivo seguro para copiar sem revisão.

Quando frontend e backend usam subdomínios diferentes, revise a variável COOKIE_DOMAIN. Ela deve corresponder ao domínio de topo necessário para o compartilhamento de cookies. Não a defina por hábito. A mesma referência oficial de .env.example documenta essa configuração.

Evite estes atalhos:

• Não versionar .env em repositório público.
• Não mostrar tokens em tickets, capturas de tela ou logs.
• Não reutilizar a senha do banco para Redis ou SSH.
• Não liberar CIDRs privados no proxy SSRF apenas para resolver um teste.
• Não substituir um Compose antigo sem comparar arquivos e variáveis.

Passo 4: suba a pilha e confira seus serviços

Dentro de dify/docker, valide a interpolação antes de iniciar a pilha:

docker compose config
docker compose up -d
docker compose ps

O primeiro comando revela erro de sintaxe ou variável ausente. O segundo inicia os containers. O terceiro permite conferir os serviços declarados e o estado de cada um.

O Compose do Dify reúne mais que uma página web. A arquitetura inclui API, worker, banco, Redis, web, sandbox, proxy SSRF, plugin daemon e componentes de agente. Os serviços e opções podem variar conforme a release e a configuração. Não afirme que todas as opções de vector store estão ativas ao mesmo tempo.

Esta ilustração é editorial. Não é captura de uma instância do Runzos nem prova de execução.

Passo 5: confirme worker, beat e uma tarefa assíncrona

O worker processa tarefas em fila. O worker_beat agenda tarefas periódicas. Desligar esses serviços para economizar recursos pode deixar uma ação aparentemente aceita na interface sem conclusão real.

Faça a validação abaixo na sua VPS e registre o resultado internamente:

1. Abra o domínio em HTTPS e faça login com uma conta de teste.
2. Rode docker compose ps e confira API, worker e beat.
3. Execute uma tarefa que gere trabalho assíncrono.
4. Consulte os logs do serviço envolvido.
5. Reinicie a pilha de forma controlada.
6. Confirme login, dados e nova tarefa após o reinício.

O Runzos não executou esses testes nesta versão. Portanto, não há tempo medido, saída esperada verificada ou screenshot operacional para publicar. Se você registrar uma captura, oculte domínio administrativo, e-mail, tokens, prompts e documentos de clientes.

Privacidade por Percurso: o dado não para na VPS por mágica

Chamamos esse critério de Privacidade por Percurso. Self-hosting pode manter aplicação, banco, fila e arquivos na infraestrutura escolhida. Isso não define o destino de cada chamada.

Mapeie o caminho entre navegador, proxy, Dify, worker, Redis, PostgreSQL, storage e vector store. Depois, mapeie as saídas para API de modelo, embedding, plugin, ferramenta ou webhook. Só então decida quais documentos podem entrar em cada fluxo.

Esta ilustração também é editorial. Ela não substitui uma auditoria da sua infraestrutura ou uma captura sanitizada após teste real.

Passo 6: planeje backup, storage e restore isolado

Backup precisa cobrir PostgreSQL, arquivos persistidos, a cópia protegida do .env e o armazenamento vetorial selecionado. Um dump de banco não contém automaticamente volumes de storage nem dados do vector store. Faça cópias coordenadas conforme cada serviço e envie-as a um destino separado da VPS.

O Runzos não validou pg_dump nem restore na release 1.17.0. Por isso, este artigo não fornece um comando copiável para exportar PostgreSQL. O nome do serviço, o usuário, o banco e as permissões dependem do .env e da configuração efetivamente instalada.

Antes de adotar um procedimento, execute a exportação e o restore em uma VPS ou diretório isolado. Recupere também arquivos, vector store aplicável e configuração necessária. Suba a pilha sem tocar no ambiente ativo. Só considere o processo aprovado após conferir login, um dado esperado e uma tarefa assíncrona.

Só depois de testar docker compose config, docker compose ps, tarefa em fila, reinício e restore isolado você pode afirmar que o roteiro foi reproduzido na sua instalação. Guarde os resultados, a tag usada e os tempos medidos. Não exponha valores de segredo no relatório.

Problemas comuns e soluções

docker compose config acusa variável ausente

Confira o .env da release escolhida. Compare-o com o .env.example correspondente. Não preencha valores de exemplo sem entender a função da variável.

A interface abre, mas a tarefa não termina

Confira docker compose ps, os logs do worker e a conectividade com Redis. Verifique se o worker e o beat estão ativos. Não conclua que o problema é da interface antes de observar a fila.

HTTPS mostra aviso ou entra em loop

Confirme DNS, certificado, URLs públicas e o ponto onde TLS termina. Escolha apenas uma camada responsável pelo proxy e pela renovação.

O restore trouxe o banco, mas documentos ou busca vetorial falharam

Revise o backup de storage e do vector store. O dump PostgreSQL sozinho não recompõe todos os dados persistidos da aplicação.

Um modelo externo recebeu dados que deveriam ficar locais

Revise o mapa de Privacidade por Percurso. Confira provider, plugin, ferramenta e webhook usados pelo workflow. Hospedar o Dify não elimina saídas para integrações externas.

Custo: o mínimo de VPS não é a conta inteira

Não há preço único confiável para este tutorial. O custo depende de VPS, domínio, backup, tráfego, observabilidade, armazenamento, embeddings e chamadas de modelo. Também existe o tempo de operação para atualizar, revisar segredos e recuperar incidentes.

Dify não exige GPU apenas para hospedar a aplicação. A GPU entra no dimensionamento quando o projeto escolhe inferência ou embeddings locais.

Para comparar infraestrutura, use a rota Runzos para VPS com Docker e domínio próprio. Uma alternativa é avaliar a VPS brasileira com suporte em português. Confirme preço, recursos, backup e suporte no dia da contratação.

Checklist antes de chamar de produção

• DNS resolve para a VPS e o login funciona em HTTPS.
• Apenas proxy web e acesso administrativo necessário estão expostos.
• PostgreSQL, Redis, sandbox e depuração não têm porta pública.
• Segredos de exemplo foram substituídos e o .env está protegido.
• API, worker e worker_beat aparecem ativos em docker compose ps.
• Uma tarefa assíncrona terminou após o login.
• Banco, arquivos, vector store e configuração entram no backup.
• Restore foi validado em ambiente isolado.
• Compose e .env.example foram comparados na release escolhida.
• Cada API de modelo, plugin e webhook tem destino e dados revisados.

Perguntas frequentes

Dify precisa de GPU?

Não para hospedar a aplicação. GPU pode ser necessária se você escolher inferência ou embeddings locais. O tamanho depende do modelo e da carga.

Quanta CPU e RAM uma VPS precisa?

O mínimo publicado é 2 cores e 4 GiB de RAM. Use-o como baseline de instalação, não como capacidade de produção para RAG ou uso concorrente.

O que fica local no Dify self-hosted?

Aplicação, banco, Redis, filas e arquivos podem ficar na VPS. APIs de modelo, plugins, conectores e webhooks podem enviar dados para outros destinos.

Posso abrir PostgreSQL ou Redis na internet?

Não é a configuração recomendada aqui. Prefira rede Docker privada, SSH, VPN ou bind local para administração, conforme sua arquitetura.

Como atualizo sem perder dados?

Teste backup e restore antes. Depois compare o .env.example da release nova com seu .env e reaplique as customizações necessárias.

Próximos passos

Comece pelo mínimo oficial. Depois valide a pilha completa antes de receber dados sensíveis ou tráfego real. Uma demonstração acessível é o começo. Uma operação recuperável depende de teste, evidência e responsável definido para cada componente.