O que é deploy com Docker Compose e GitHub Actions

Fazer deploy de uma aplicação backend costumava ser um processo manual e sujeito a erros: conectar no servidor via SSH, puxar o código, rodar comandos, torcer para não quebrar nada. Com Docker Compose e GitHub Actions, esse processo vira um pipeline automatizado que roda toda vez que você faz um push.

Docker Compose e uma ferramenta que permite definir e rodar múltiplos containers com um único arquivo YAML. GitHub Actions e a plataforma de CI/CD integrada ao GitHub, que executa tarefas automatizadas em resposta a eventos do repositório, como um push na branch main.

Juntos, eles formam um combo poderoso para times pequenos e devs solo que precisam de um fluxo de deploy confiável sem pagar caro por plataformas de orquestração complexas.

Como funciona o pipeline

O fluxo completo funciona assim: você faz um push para a branch main do seu repositório. O GitHub Actions detecta o evento e inicia o workflow. O workflow conecta no seu VPS via SSH, puxa a versão mais recente do código e executa o Docker compose up -d para subir ou atualizar os containers.

O Docker Compose le o arquivo Docker-compose.yml e sabe exatamente quais serviços precisa subir, em qual porta, com quais variáveis de ambiente e quais volumes deve montar. Se a imagem do container mudou, ele recria o container automaticamente. Se não mudou, ele deixa como esta.

O segredo e que tudo isso acontece de forma declarativa: você descreve o estado desejado, e as ferramentas cuidam de chegar la. Sem scripts manuais, sem esquecer de rodar um comando, sem diferença entre o ambiente local e o de produção.

Principais recursos

O Docker Compose oferece recursos que facilitam muito o dia a dia em produção:

  • Múltiplos serviços em um arquivo: API, banco de dados, cache e fila todos definidos no mesmo Docker-compose.yml
  • Redes internas: os containers se comunicam pelo nome do serviço, sem expor portas desnecessárias
  • Volumes persistentes: dados do banco sobrevivem ao reinicio dos containers
  • Health checks: define quando um container esta saudável antes de aceitar tráfego
  • Profiles: grupos de serviços que sobem juntos em contextos específicos

O GitHub Actions complementa com workflows configurados em YAML, segredos criptografados para senhas e chaves SSH, e logs detalhados de cada execução para debugar problemas.

Como começar: instalação e configuração passo a passo

Para montar esse pipeline do zero, você precisa de um VPS com Docker instalado, um repositório no GitHub e algumas configurações iniciais. O processo todo leva cerca de 30 minutos na primeira vez.

Passo 1: Instale Docker e Docker Compose no seu VPS. Em sistemas Debian/Ubuntu, rode curl -fsSL https://get.Docker.com | sh e depois sudo usermod -aG Docker SEU-USUÁRIO.

Passo 2: Crie o arquivo Docker-compose.yml na raiz do projeto, definindo seus serviços. Use a versão 3.8 ou superior. Configure as variáveis de ambiente via arquivo .env que não será commitado no repositório.

Passo 3: Gere um par de chaves SSH específico para o deploy com ssh-keygen. Adicione a chave pública no arquivo authorized_keys do VPS. Adicione a chave privada como segredo no GitHub: Settings, Secrets, Actions, New repository secret.

Passo 4: Crie o arquivo .GitHub/workflows/deploy.yml no repositório com o workflow de deploy.

Exemplo prático: workflow de deploy

O workflow e acionado em push para a branch main. Ele tem um job de deploy que roda no ubuntu-latest. Os passos são: checkout do código, conexão SSH no VPS usando a ação appleboy/ssh-action, e execução dos comandos de deploy no servidor remoto.

Os comandos no servidor seguem esta sequência: cd no diretório do projeto, git pull origin main, Docker compose pull, Docker compose up -d --remove-orphans. O flag --remove-orphans remove containers de serviços que foram removidos do compose file. O pull garante que a imagem mais recente seja baixada antes de subir.

Para variáveis de ambiente sensíveis, use segredos do GitHub e passe como variáveis de ambiente no SSH action. Nunca commite senhas ou tokens no repositório.

Comparação com alternativas

Existem varias formas de fazer deploy automático de containers. Cada uma tem seu lugar:

Heroku/Render/Railway: plataformas que abstraem todo o servidor. Mais simples, mas mais caro para cargas maiores e com menos controle. Ideal para MVPs rápidos.

Kubernetes: orquestração poderosa para dezenas de serviços e alta disponibilidade. Curva de aprendizado alta e overhead operacional significativo. Indicado para times maiores.

Docker Swarm: alternativa mais simples ao Kubernetes, built-in no Docker. Menos recursos, mas mais fácil de operar que o K8s.

Docker Compose com GitHub Actions ganha na simplicidade e custo: você paga apenas pelo VPS (a partir de R$20-50/mes nos provedores brasileiros), tem controle total e o pipeline e fácil de entender e manter.

Pontos positivos e limitações

Os pontos fortes dessa abordagem são: custo baixo, controle total sobre o servidor, facilidade de debugar (você tem acesso direto aos logs), e portabilidade (o mesmo Docker-compose.yml funciona em qualquer VPS).

As limitações reais que você vai encontrar: sem escalabilidade horizontal automática (precisa de Swarm ou K8s para isso), downtime de alguns segundos durante o deploy (use rolling updates se precisar de zero downtime), e você e responsável pela segurança e atualizações do servidor.

Para a maioria dos projetos SaaS com até alguns milhares de usuários, Docker Compose em um VPS e mais do que suficiente. Muitas empresas rodam em produção com essa configuração por anos sem problemas.

Casos de uso reais

Essa configuração se encaixa muito bem em vários cenários do dia a dia de um desenvolvedor:

  • API REST com banco de dados: backend Node.js, Python ou .NET rodando junto com PostgreSQL e Redis, todos no mesmo compose
  • SaaS em fase inicial: MVP com usuários reais, onde você precisa de deploy rápido mas não quer pagar caro por plataformas gerenciadas
  • Projetos de agência: múltiplos sites ou apps de clientes em VPSs separados, cada um com seu próprio compose e pipeline
  • Ferramentas internas: sistemas de gestão, dashboards e automações que precisam rodar continuamente com deploy fácil

Dicas e boas práticas

Algumas práticas que usuários experientes adotam para evitar dores de cabeça em produção:

Use imagens com tag específica: evite a tag latest em produção. Use tags de versão como 1.2.3 ou hashes do commit para ter builds reproduzíveis. Isso evita surpresas quando uma nova versão quebra algo.

Configure restart: unless-stopped nos serviços críticos do seu compose. Isso garante que os containers reiniciem automaticamente se o servidor for reiniciado, sem precisar de configuração extra no systemd.

Separe o arquivo de segredos: crie um arquivo .env.production no servidor (fora do repositório) e referencie-o no compose com env_file. Isso mantem os segredos no servidor sem versionamento.

Teste o workflow em uma branch de homologação primeiro: crie um segundo workflow que sobe em um VPS de staging quando você faz push para a branch develop. Assim você valida o deploy antes de ir para produção.

Vale a pena?

Para devs e times pequenos que querem um deploy automatizado sem complexidade desnecessária, a resposta e sim. Docker Compose com GitHub Actions e a combinação mais custo-efetiva disponível hoje para projetos que ainda não precisam de Kubernetes.

Se você ainda faz deploy manual via SSH, esse e o próximo passo natural. O investimento de algumas horas configurando o pipeline vai economizar centenas de horas ao longo do projeto. O próximo passo: crie o Docker-compose.yml do seu projeto, configure o workflow e faca o primeiro deploy automático ainda hoje.