Como levar um Docker Compose existente para o Coolify na VPS (sem reinstalar o painel)

Fala aí, beleza? Teu docker-compose.yml já roda redondo e o Coolify já está de pé na VPS, agora falta juntar os dois sem reinstalar nada 🙂

A boa notícia: a definição do Compose controla imagens, builds, comandos, referências de ambiente, volumes, health checks, depends_on e a rede do Compose, então a migração é muito mais ajustar o arquivo que já existe do que reescrever o projeto do zero

O foco aqui é importação, persistência e variáveis, sem repetir a instalação do painel

O que você precisa antes de importar o Compose no Coolify

Você precisa de três coisas: o Coolify já instalado, um servidor que aguente ele e um repositório Git com o Compose

Se liga nos requisitos, segundo a documentação oficial do Coolify:

• Servidor Linux com acesso SSH (o Coolify só roda em sistemas baseados em Linux)
• Mínimo de 2 núcleos de CPU, 2 GB de RAM e 10 GB de disco livre
• Espaço extra além disso para imagens Docker, volumes e backups (e é aqui que muita gente se aperta)
• Arquitetura amd64 ou arm64
• Repositório Git, público ou privado, com o arquivo docker-compose.yml ou docker-compose.yaml

Ainda não tem o painel? Só pra referência, o script oficial roda em Ubuntu LTS (20.04, 22.04 ou 24.04) e em outras distros suportadas pela documentação (Debian, família Red Hat, SUSE, Arch, Alpine, Raspberry Pi OS 64-bit), com este comando:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

Outro caminho é o template Ubuntu 24.04 with Coolify, que já vem com o painel pré-instalado: tu acessa http://IP-da-VPS:3000 e cria a conta de administrador no primeiro acesso

Aviso rápido: este artigo contém links de afiliado da Hostinger

Para este cenário, a recomendação da Hora de Codar é a VPS da Hostinger, e o motivo é bem prático

A hospedagem Coolify da Hostinger já entrega o painel pré-instalado com acesso root completo, então tu pula direto pra importação, sem precisar rodar o script de instalação

Fora da oferta específica de Coolify, nos planos de VPS da Hostinger em geral (KVM 1, KVM 2, KVM 4 e KVM 8) você encontra processadores AMD EPYC e armazenamento em SSD NVMe, o que conversa bem com build de imagem e banco escrevendo em volume. Tem também backups semanais restauráveis pelo painel e gerenciamento de firewall, duas coisas que fazem diferença quando você começa a manter dados persistentes e expor serviços

Na hora de escolher o plano, confira as especificações dele contra os mínimos do Coolify (2 núcleos, 2 GB de RAM e 10 GB de disco) e some uma folga real para imagens e volumes

Passo a passo: importar um Docker Compose existente no Coolify

O fluxo é: ajustar o arquivo, criar o recurso, apontar o Compose, preencher variáveis, conferir volumes, expor o serviço e fazer o deploy

Por que ajustar o arquivo primeiro? Porque o Compose controla imagens, builds, comandos, referências de ambiente, volumes, health checks, depends_on e rede, ou seja, o que estiver errado nele vai errado pro servidor

1. Prepare o arquivo e tire os segredos fixos

Troque senhas e chaves escritas direto no environment por referências de variável

O Coolify entende três sintaxes:

• ${VAR}: cria a variável sem valor, editável na UI
• ${VAR:-padrao}: cria a variável já com valor padrão, também editável
• ${VAR:?}: marca como obrigatória, e o Coolify impede o deploy enquanto ela estiver vazia

Exemplo didático com app e banco (adapte ao teu projeto):

services:
  app:
    build: .
    environment:
      DATABASE_URL: postgres://${DB_USER:-app}:${DB_PASSWORD:?}@db:5432/${DB_NAME:-app}
      APP_SECRET: ${APP_SECRET:?}
    depends_on:
      - db

  db:
    image: postgres
    environment:
      POSTGRES_USER: ${DB_USER:-app}
      POSTGRES_PASSWORD: ${DB_PASSWORD:?}
      POSTGRES_DB: ${DB_NAME:-app}
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Se o teu Compose nasceu de algo como uma API NestJS com Docker Compose, a lógica é a mesma: o que é segredo vira ${VAR}

O erro comum deste passo: deixar a senha fixa no environment

Um valor fixo chega ao container, mas não vira variável editável no Coolify. Como este guia parte de um repositório Git, a correção é editar o valor direto no arquivo do repositório e fazer o redeploy; o painel não cria um campo de edição pra esse valor

2. Crie o recurso no Coolify

Abra o projeto e o ambiente de destino, depois clique em + New

Escolha repositório público, via deploy key, ou via um Git App suportado

No caso de repositório público, cole a URL HTTPS e clique em Check Repository

Na tela seguinte, vá em General > Build pipeline e, em Build strategy, selecione Compose

O erro comum deste passo: deixar a build strategy padrão, e o Coolify tentar montar a aplicação do jeito dele em vez de usar o teu Compose

3. Aponte Base Directory e Docker Compose Location

No Base Directory, informe a pasta do repositório que contém a aplicação

O Docker Compose Location é o caminho do arquivo relativo ao Base Directory, e o Coolify junta os dois valores pra localizar o arquivo

O erro comum deste passo: caminho que não bate com a estrutura real do repositório, fazendo o Coolify não encontrar o arquivo

Se o Base Directory e o Docker Compose Location, somados, não apontam pro arquivo certo, o Coolify não encontra o Compose. Vale confirmar o caminho exato (incluindo nome do arquivo) direto no repositório antes de salvar

4. Preencha as variáveis de ambiente

O Coolify detecta as ${VAR} citadas no Compose e mostra todas na seção Environment Variables

Preencha DB_PASSWORD, APP_SECRET e o que mais estiver vazio, e ajuste os padrões se precisar

O erro comum deste passo: esquecer uma ${VAR:?} vazia, que bloqueia o deploy (e ainda bem, melhor travar do que subir banco sem senha)

E se você não quiser inventar senha na mão? Aí entram as variáveis mágicas

O Coolify reconhece nomes no padrão SERVICE_<TIPO>_<ID> e gera o valor sozinho:

• SERVICE_PASSWORD_<ID>: senha gerada sem símbolos, com 32 caracteres
• SERVICE_PASSWORD_64_<ID>: senha gerada sem símbolos, com 64 caracteres
• SERVICE_USER_<ID>: usuário alfanumérico gerado, com 16 caracteres
• SERVICE_URL_<ID>: URL a partir do domínio wildcard
• SERVICE_FQDN_<ID>: o domínio sem esquema

    environment:
      POSTGRES_USER: ${SERVICE_USER_POSTGRES}
      POSTGRES_PASSWORD: ${SERVICE_PASSWORD_POSTGRES}

Os valores gerados persistem entre deploys, aparecem em Environment Variables e o mesmo nome completo devolve o mesmo valor em todo o recurso, então dá pra reaproveitar a senha no app e no banco

Tome cuidado com o nome do serviço: em variáveis de URL e FQDN, hífens e pontos do nome do serviço viram underscore, então um serviço meu-app vira algo como SERVICE_FQDN_MEU_APP. Já no caso de senhas e usuários, o <ID> precisa ser um token único sem underscore (ex.: SERVICE_PASSWORD_DBPASSWORD)

5. Declare a persistência no próprio Compose

Volume nomeado (como o db-data do exemplo) e bind mount ficam no arquivo, não no painel

Eles aparecem em Persistent Storage, mas os campos vindos do Compose ficam somente leitura ali, porque a mudança é feita na definição do Compose

  app:
    volumes:
      - ./config:/app/config

Esse mesmo cuidado com volume vale pra qualquer stack com dados, tipo um WordPress com Docker Compose 😀

O erro comum deste passo: tentar mudar o volume pela UI

Não vai rolar, a mudança é no Compose

6. Libere o acesso externo do serviço certo

Para expor um serviço publicamente, vá em Domains, clique em Add domain, escolha o Service que deve receber o tráfego e informe protocolo, hostname, porta interna e, se precisar, um caminho: por exemplo, https://app.example.com:3000

No exemplo deste guia, atribua domínio ao app e deixe o db sem domínio, pra ele ficar só na rede interna do Compose

A requisição pública continua passando pelas portas HTTP/HTTPS normais, mesmo que a porta interna informada seja outra

O erro comum deste passo: configurar o domínio no serviço errado (por exemplo, no db em vez do app), misturando o que deveria ficar público com o que deveria ficar só na rede interna do Compose

7. Faça o deploy e confira tudo

Clique em Deploy e acompanhe os Deployment Logs

Quando terminar, faça a checagem final:

• Abra cada domínio público que você configurou e veja a aplicação responder
• Em Environment Variables, confira se as variáveis estão preenchidas e se as mágicas ganharam valor
• Em Persistent Storage, confira se os volumes do Compose estão listados
• Se algum serviço não subir ou não ficar healthy, consulte os Runtime Logs dele

Tudo ali? Massa, o projeto está rodando no Coolify com o teu próprio arquivo 🙂

Problemas comuns ao migrar o Compose para o Coolify e como resolver

A maioria dos tropeços vem de três lugares: variável, caminho do arquivo e domínio do serviço

Deploy não inicia

Causa: alguma variável ${VAR:?} está vazia, e o Coolify bloqueia o deploy

Solução: preencha o valor em Environment Variables e rode de novo

Como prevenir: antes do primeiro deploy, passe a lista inteira de variáveis e use ${VAR:-padrao} no que realmente tem um padrão seguro

Arquivo Compose não encontrado

Causa: Base Directory ou Docker Compose Location não apontam pro caminho real do arquivo no repositório

Solução: confira a pasta e o nome exato do arquivo direto no repositório, e ajuste os dois campos

Como prevenir: lembre que o caminho do Docker Compose Location é somado ao Base Directory, então não repita a subpasta nos dois campos

Domínio não configurado para o serviço público

Causa: o serviço que deveria receber tráfego do Coolify ainda não tem um domínio associado em Domains

Solução: vá em Domains, clique em Add domain, escolha o Service público e informe protocolo, hostname e porta interna dele

Como prevenir: decida ainda no Compose quem é público (app) e quem fica interno (banco, cache), e configure domínio apenas para os serviços que devem ter tráfego roteado pelo Coolify

Não dá para mudar o volume na UI

Causa: campos vindos do Compose ficam somente leitura em Persistent Storage

Solução: edite o volume no Compose e faça novo deploy

Como prevenir: trate o arquivo como o lugar certo pra mudança de persistência

Vídeo complementar

Se quiser complementar este tutorial com mais conteúdo do canal sobre deploy em VPS, dá uma olhada no vídeo abaixo

Próximo passo depois do primeiro deploy

Agora o jogo é manutenção: trate o Compose versionado no Git como o lugar certo pra mudanças de volume e de configuração do serviço, e edite os valores fixos direto no repositório antes de fazer o redeploy

Assim o painel e o repositório não ficam desalinhados, e qualquer pessoa do time sabe onde olhar

Outra coisa: reserve disco de verdade, porque imagens acumuladas, volumes crescendo e backups comem espaço rapidinho, bem além dos 10 GB mínimos

Se ainda vai escolher onde hospedar, vale conferir a VPS para este projeto: os backups semanais restauráveis pelo painel entram como uma camada extra de proteção do servidor

Só não confunda: eles não substituem o backup dos dados dos volumes da tua aplicação, então planeja os dois

Até o próximo post! 😉

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.