Como hospedar aplicações Docker em uma VPS

Prepare o servidor e os acessos

Você precisa de uma VPS nova, acesso root para a instalação, um domínio que possa editar e as instruções de implantação da aplicação. Antes de criar o serviço, identifique a porta interna, variáveis obrigatórias, banco de dados e diretórios graváveis. Mantenha as credenciais do repositório ou registry disponíveis caso o código seja privado.

Siga a documentação de instalação do Easypanel. A instalação por script exige Ubuntu novo, pelo menos 2 GB de RAM e as portas 80 e 443 livres. Esse é o mínimo da plataforma; dimensione a máquina para aplicações, bancos e builds com o guia de escolha de VPS.

Defina quem cuidará das atualizações do sistema operacional, SSH, firewall, disco e incidentes. Restrinja o acesso administrativo. As regras de publicação de portas do Docker podem expor um serviço além da rede do contêiner. Mantenha bancos privados, exceto quando houver uma necessidade controlada de acesso externo.

Em uma agência, registre o cliente responsável por cada aplicação e quem pode acessá-la. Projetos ajudam a organizar os serviços, mas um servidor compartilhado continua sendo uma fronteira de falha compartilhada.

Escolha a forma de implantação

Escolha de acordo com a forma como a aplicação é mantida. Um projeto pode ter vários serviços de aplicação ou um serviço Compose com vários contêineres.

Serviço de aplicação: repositório ou imagem

Use um serviço de aplicação para site, API ou worker implantado individualmente. Com GitHub ou Git, selecione repositório, branch, caminho de build e builder. Um Dockerfile existente deixa as instruções explícitas. Com Docker Image, forneça a referência da imagem e as credenciais do registry; o Easypanel baixa a imagem em vez de compilá-la.

Serviço Compose: vários contêineres

Use um serviço Compose quando o projeto já fornece um arquivo Compose. Cole o YAML ou conecte o repositório. Confira caminho e nome do arquivo. Resolva avisos sobre nomes fixos de contêiner e portas publicadas; configure o acesso HTTP público na seção de domínios do Easypanel.

Template: receita pronta

Procure a aplicação no diretório de templates. Revise serviços, versões das imagens, credenciais e armazenamento criado. Depois, complete as verificações de funcionamento e recuperação deste guia.

Para código privado, siga as instruções de token do GitHub ou Git por SSH. Conceda somente o acesso necessário. Registre uma versão ou digest da imagem para saber exatamente o que está em execução.

Configure segredos e dados persistentes

Use as variáveis documentadas pela aplicação para URL pública, banco, e-mail e outras dependências. Insira as credenciais reais na seção Environment. Mantenha uma cópia de recuperação com acesso controlado e não inclua segredos em Git, capturas de tela ou mensagens de suporte.

Os valores de ambiente de um serviço de aplicação ficam disponíveis no build e no contêiner. Garanta que o build não imprima credenciais nem incorpore segredos em arquivos enviados ao navegador. Em Compose, diferencie variáveis usadas para interpolar o YAML das variáveis entregues ao processo. Consulte as instruções de ambiente do Compose e faça um novo deploy após alterações.

Liste tudo o que a aplicação grava: registros do banco, uploads, arquivos gerados e estado local. Para um serviço de aplicação, configure os volumes em Storage. Em Compose, declare volumes nomeados ou bind mounts. O destino precisa corresponder ao diretório realmente utilizado pelo processo, com permissões para o usuário correto.

Um volume persistente sobrevive à substituição do contêiner, mas continua dependendo do disco da VPS. Configure um backup externo antes de aceitar dados de produção.

Faça o deploy e conecte o domínio

Salve a configuração e selecione Deploy. Acompanhe o build ou download da imagem e depois os logs de execução. Se a aplicação exige migração ou criação do administrador, siga suas instruções antes de liberar o acesso. Alterar configurações normalmente exige um novo deploy.

Aponte o DNS do hostname para a VPS. Na seção Domains, configure o hostname, HTTPS e a porta interna em que a aplicação escuta. O processo normalmente precisa escutar em 0.0.0.0. Para Compose, selecione também o serviço interno que recebe as requisições web. Deixe banco e fila sem domínio público.

Consulte domínios de App ou domínios de Compose para os campos exatos. Confirme que a URL pública configurada na aplicação corresponde ao endereço HTTPS, inclusive callbacks de autenticação e webhooks.

Valide a aplicação de ponta a ponta

Execute estes testes em homologação antes de direcionar clientes:

1. Abra a URL HTTPS de fora do servidor e confira certificado e redirecionamentos.
2. Entre com um usuário de teste, crie um registro e leia-o novamente. Execute um job em segundo plano se houver worker.
3. Envie um arquivo, implante novamente a mesma versão e confirme que registro e arquivo continuam disponíveis.
4. Examine logs de deploy e runtime procurando migrações com falha, erros de banco ou reinicializações repetidas.
5. Meça memória, CPU e disco durante o build e durante o uso normal, considerando as outras aplicações do host.

Configure um monitor externo de disponibilidade e defina quem receberá o alerta. Um contêiner “em execução” ainda pode responder com erro, e um monitor na mesma VPS não consegue avisar sobre a própria perda de rede.

Faça backup e teste uma restauração

Defina quanto trabalho recente pode ser perdido e quanto tempo a recuperação pode levar. Use essas respostas para escolher frequência e arquitetura. Mantenha backups fora da VPS e uma pasta separada para cada ambiente.

Os backups de banco geram dumps lógicos para os serviços compatíveis. Confirme se seu plano inclui agendamento. Um backup de volume sincroniza o volume com o destino e pode substituir arquivos ou propagar exclusões; use versionamento no destino quando precisar de pontos históricos. A recuperação do volume é manual.

Bind mounts, File mounts e volumes definidos dentro do Compose precisam de plano próprio. Para bancos executados via Compose, use um processo compatível com o banco; copiar o diretório de dados enquanto há gravações pode gerar uma cópia inconsistente.

Execute cada backup manualmente, confira os logs e examine os arquivos de destino. Depois, recupere em outro serviço ou servidor. Recrie a configuração, restaure banco e uploads e repita os testes de login, leitura e gravação. Confirme o alvo antes de restaurar, pois a operação pode substituir dados existentes.

Documente os passos e o tempo necessário. O acesso ao provedor de backup, DNS, código-fonte e segredos deve continuar disponível mesmo que a VPS original desapareça.

Torne a próxima atualização repetível

Registre a revisão do código ou digest da imagem em execução e mantenha a versão anterior. Teste a atualização em um ambiente com a mesma configuração da produção. Leia as notas de versão sobre migrações, variáveis e armazenamento; faça um backup verificado antes de mudanças que alteram dados.

Faça o deploy, acompanhe logs e repita os testes da aplicação. Ative deploy automático somente depois de decidir qual branch ou pipeline pode publicar em produção. Trate a URL de Deployment Trigger como um segredo.

Pratique o retorno à revisão conhecida. Isso reverte o código, mas não desfaz uma migração de banco nem recupera arquivos excluídos. Se o código antigo não aceita o novo schema, a recuperação pode exigir correção ou restauração com perda das gravações posteriores ao backup.

Encontre a etapa que falhou

A imagem não compila ou não é baixada

Leia a saída do deploy. Verifique credenciais, referência da imagem, arquitetura da CPU, contexto de build e Dockerfile. Reproduza o build com a mesma revisão sempre que possível.

O contêiner inicia e reinicia

Confira comando de inicialização, porta, variáveis, permissões e conexão com dependências. Leia o primeiro erro nos logs, não apenas as últimas reinicializações.

O domínio não responde corretamente

Confirme DNS, portas 80 e 443, porta interna, 0.0.0.0, serviço correto do Compose e URL pública configurada. Teste também do lado de fora da sua rede.

Os dados somem após um deploy

Verifique se o diretório gravável está realmente montado e se o processo utiliza esse caminho. Depois de corrigir o volume, teste novamente redeploy e restauração antes de produção.

Próximos passos