Análise do Doco CD: GitOps para Docker Compose sem a sobrecarga do Kubernetes

Cada push repete o mesmo ritual: entrar por SSH, atualizar o repositório, subir o stack do Compose de novo, torcer para nada ter quebrado e tentar lembrar se você rodou a migração. Esse ciclo manual funciona até você precisar de implantações repetíveis, de um registro claro do que está rodando ou de recuperação de desvios.

O Doco CD é uma resposta direta. É um pequeno serviço em Go que observa seu repositório Git e aplica as mudanças do Compose quando você faz push: webhook ou polling, você escolhe. ArgoCD e Flux fazem isso para Kubernetes, mas o Doco CD dispensa o Kubernetes, já que não precisa de um control plane.

Esta análise cobre o que o Doco CD faz, o que não faz e como ele se compara ao Komodo, ao modo GitOps do Portainer, ao Dokploy e a um simples script de GitHub Actions + SSH. No final você saberá se ele serve para o seu ambiente e o que escolher se não servir.

TL;DR

• O Doco CD é um agente GitOps minúsculo e nativo do Compose: ele observa um repositório Git (GitHub, GitLab, Gitea, Forgejo e outros) e reconcilia seu stack quando algo muda.
• O suporte nativo a provedores externos de segredos, somado à criptografia baseada em SOPS, é o diferencial em relação a escrever seu próprio script de deploy.
• Segundo o próprio README, ele se apresenta como "uma alternativa simples ao Portainer ou ao ArgoCD para Docker". O enquadramento está mais ou menos certo.
• Limites reais: um único dono do código, versionamento anterior ao 1.0, ausência de interface para gerenciar uma frota e um estado de reconciliação que só é reconstruído após o próximo poll ou evento de webhook.
• Escolha-o quando você roda um ou poucos hosts com Compose e quer o Git como fonte da verdade, sem interface. Prefira o Komodo para frotas, o Portainer quando quiser uma interface, o Dokploy para uma sensação de PaaS, ou GitHub Actions + SSH quando for mesmo um serviço em um host.

A lacuna que o Doco CD tenta preencher

Existe um meio-termo estranho para quem roda Docker Compose em 2026. Grandes ferramentas GitOps como Argo CD e Flux miram no Kubernetes, enquanto o modelo do Watchtower, que consulta o registro, reage a mudanças de imagem em vez de aplicar um estado Compose versionado. O repositório foi arquivado em 17 de dezembro de 2025 e agora informa que o projeto não recebe mais manutenção.

GitHub Actions com um passo de deploy por SSH funciona. Para um serviço em um host, é a escolha certa. O problema aparece quando você acrescenta um segundo host, ou um segundo stack, ou quer saber qual commit está implantado agora. Você continua com os logs do workflow, mas sem reconciliação nativa do Compose, sem recuperação de desvios e sem uma visão persistente de o host ainda corresponder ao repositório.

A proposta do Doco CD, tirada direto do README, é "uma alternativa simples ao Portainer ou ao ArgoCD para Docker". Esse enquadramento é justamente o ponto: pequeno, nativo do Compose, sem Kubernetes, sem interface para manter, sem control plane central para vigiar. Se você não roda K8s e nem queria, essa é a categoria que você procurava.

Como o Doco CD funciona de verdade

O Doco CD é um único binário em Go que roda dentro de um contêiner Docker, observa um repositório Git e aplica as mudanças do Compose quando o estado do repositório muda. Esse é todo o conceito. O que interessa está nos padrões e nas integrações.

Gatilhos. Dois modos: webhook ou polling. O webhook é quase instantâneo, mas exige uma porta exposta, ou mais realisticamente um proxy reverso na frente do Doco CD. O polling é uma busca periódica: um pouco atrasada, sem precisar de porta de entrada. O polling é o padrão mais simples e, segundo a documentação oficial , os dois são de primeira classe. Escolha conforme o seu host tenha ou não um endpoint público acessível e conforme a rapidez de deploy que você precisa.

Configuração por repositório. Um arquivo .doco-cd.yaml (ou .doco-cd.yml) fica na raiz do repositório, ao lado do seu arquivo do Compose. O único campo obrigatório é o nome da implantação. Uma configuração mínima é assim:

# .doco-cd.yaml
name: my-stack
# Everything below is optional. These are the defaults.
timeout: 180          # seconds
remove_orphans: true
prune_images: true
force_recreate: false

Esses são os padrões documentados: tempo limite de 180 segundos, órfãos removidos, imagens podadas e sem recriação forçada.

Descoberta automática. Com a descoberta automática ligada, o Doco CD varre subdiretórios atrás de arquivos do Compose, de modo que um único repositório pode abrigar vários stacks. Ele também aceita várias configurações de implantação em um só arquivo, escritas como documentos YAML separados por uma linha de três hifens. Os padrões de limpeza são conservadores e vale a pena lê-los antes de depender deles:

Em outras palavras, nada é derrubado pelas suas costas até você ligar a exclusão e, mesmo assim, seus volumes de dados são os últimos a sair.

Provedores Git suportados. GitHub, GitLab, Gitea, Forgejo, Gogs e Azure DevOps são suportados. O Azure DevOps é a exceção quanto a webhooks, porque os Azure Service Hooks não têm suporte. O suporte a Gitea e Forgejo importa se você hospeda sua própria forja.

Docker Swarm. Suportado como destino. O que a página de configurações de deploy sinaliza explicitamente: no modo Swarm, a reconciliação não verifica reinícios de contêiner nem o estado de saúde, e a poda de imagens não é suportada no Swarm. Se o seu destino for o Swarm, você ganha deploys, mas não reconciliação completa de saúde.

Reconciliação. Por padrão, há um limite de 5 reinícios em uma janela de 300 segundos, criado para impedir que health checks instáveis entrem em loop eterno. Mesmo repositório com referência diferente roda em sequência; mesmo repositório com a mesma referência roda em paralelo. Esse último detalhe é sutil, mas útil: vários deploys da mesma referência não ficam enfileirados uns atrás dos outros.

Provedores externos de segredos integrados. Essa é uma das razões mais fortes para considerar o Doco CD em vez de um script de deploy simples: ele suporta AWS Secrets Manager, Bitwarden Secrets Manager, Bitwarden Vault / Vaultwarden, 1Password, 1Password Connect, Infisical, OpenBao e Webhook. Em separado, ele suporta criptografia baseada em SOPS para dados sensíveis de implantação. Isso te dá um caminho limpo para sair dos arquivos env em texto puro no Git, sem construir todo o fluxo de resolução de segredos por conta própria.

O resto. O Doco CD oferece métricas do Prometheus, agendamento de tarefas, notificações, uma imagem de contêiner distroless e licença Apache-2.0. Segundo seu histórico de versões, em 20 de agosto de 2026, a v0.109.2 é a versão estável mais recente e a v0.110.0-rc.1 é a pré-versão mais nova.

O trabalho do Doco CD para em "aplicar o manifesto"; daí em diante é Docker comum. Os próprios comandos de log do Compose são o que você vai usar para inspecionar o que está rodando.

Dica prática sobre segredos. Se o seu repositório privado ainda tem arquivos env em texto puro, priorize os provedores externos de segredos do Doco CD ou o suporte a SOPS. O objetivo é simples: tirar segredos em texto puro do Git e mesmo assim deixar as implantações resolverem os valores em tempo de execução.

Onde o Doco CD deixa a desejar

Toda ferramenta tem limites, e os do Doco CD vale a pena conhecer antes de gastar um fim de semana configurando.

Um único dono do código. O arquivo CODEOWNERS do repositório atribui todos os caminhos a kimdre. Os lançamentos continuam frequentes, mas a governança está concentrada em uma única pessoa.

Anterior à 1.0. O Doco CD ainda usa versionamento 0.x, então fixe uma versão testada e leia as notas de atualização antes de colocar em produção. A issue #851 do GitHub, já encerrada, ilustra o porquê: o Docker v29 obrigou o projeto a abandonar módulos Go do Docker já descontinuados.

Sem shell dentro do contêiner do Doco CD. Por segurança, o Doco CD não oferece um ambiente de shell nem executa scripts arbitrários no host. Tarefas antes e depois da implantação precisam passar por contêineres de inicialização, sidecars ou hooks de ciclo de vida do Compose, o que acrescenta configuração em comparação com ferramentas que rodam um script de deploy diretamente.

Perda de estado ao reiniciar. O estado de reconciliação fica em memória. Quando o Doco CD reinicia, esse estado só é reconstruído após o próximo poll ou evento de webhook, então a lacuna depende do seu intervalo de polling ou de quando chegar outro webhook.

Sem interface para gerenciar a frota. Trabalhar com vários hosts não exige mais um agente por máquina. Desde a v0.102.0, as configurações de implantação podem apontar para contextos Docker remotos, inclusive contextos SSH, e um mesmo repositório pode definir vários destinos de implantação. Rodar uma instância do Doco CD por host continua válido, mas agora uma instância central consegue implantar em hosts Docker remotos. O que ainda falta ao Doco CD é a interface de gestão de frota do Komodo e um inventário centralizado de hosts.

O consumo de RAM e CPU não está documentado em números. A documentação oficial descreve os requisitos como "minúsculos", mas não publica nenhum número de referência. Dimensione o VPS pelas aplicações que ele vai rodar, deixe folga operacional e verifique o consumo real do Doco CD no seu próprio ambiente.

Dica prática sobre múltiplos hosts. Use um contexto Docker e um destino de implantação separados por máquina, restrinja o acesso SSH e mantenha os segredos de webhook ou de API únicos. Se você prefere agentes isolados, uma instância do Doco CD por host continua válida.

Doco CD frente às alternativas

As outras quatro ferramentas que eu colocaria na lista curta tentam resolver "implantar o Compose automaticamente a partir do Git", mas com trade-offs bem diferentes. A decisão não é se você vai fazer isso; isso você já decidiu. A decisão é qual formato de ferramenta serve para o seu ambiente. Aqui vai a comparação lado a lado.

Um resumo de cada um, já que a tabela dá o formato e o comentário dá o porquê:

Komodo. A alternativa séria para vários hosts. Um serviço Core central mais um agente Periphery em cada máquina, uma única interface que enxerga todas, builds guiados por Git além dos deploys e suporte a Docker Swarm. É mais pesado de montar, porque você acaba rodando um banco de dados e um control plane, mas é o formato certo se você tem uma frota. O Komodo se encaixa melhor quando o controle centralizado da frota importa.

Portainer (CE ou BE) com GitOps. Uma interface gráfica completa em cima da sincronização com o Git. É a escolha certa quando a equipe quer gerenciar contêineres no clique junto com o CD. Se alguém vai estar na interface de qualquer jeito, olhando logs e reiniciando contêineres, mais vale ter o CD no mesmo lugar. O consumo de recursos é maior que o do Doco CD. OIDC/SSO e RBAC granular ficam atrás do paywall da Business Edition. Nosso guia de alternativas ao Portainer cobre o panorama mais amplo da gestão de Docker.

Dokploy. Estilo PaaS. Tem opinião forte, faz deploy automático no push, tem interface web para tudo e já te entrega Traefik com URLs limpas de fábrica. Melhor para times que querem uma sensação de Heroku e topam abrir mão da flexibilidade crua do Compose por isso. Se você é alérgico a YAML, esse é o caminho mais leve até "dei git push e a aplicação subiu".

GitHub Actions + SSH. Zero infraestrutura extra. O job de deploy mora no workflow que você já tem. Você recebe os logs do workflow, mas nenhuma reconciliação nativa do Compose, nenhuma recuperação de desvios e nenhuma visão persistente do estado do host, a não ser que construa essas peças você mesmo. Serve bem para um serviço em um host. Desmorona assim que você acrescenta um segundo destino ou quer saber o que está rodando onde sem entrar por SSH. Para a fatia mais simples do público, GitHub Actions + SSH continua sendo a resposta certa.

Há um recém-chegado chamado stackd , que se apresenta com uma linguagem parecida: "GitOps sem o imposto do Kubernetes". Vale saber que a categoria está ativa, mas não vale escolhê-lo em vez do Doco CD no cara ou coroa hoje.

LER

Coolify vs Dokploy: Uma comparação aprofundada para PaaS self-hosted num VPS

Quando o Doco CD é a escolha certa (e quando não é)

Escolha o Doco CD quando:

• Você roda um ou poucos hosts com Docker Compose e quer o Git como fonte da verdade.
• Você prefere editar YAML no seu editor a ficar clicando por uma interface.
• Você quer suporte a provedores externos de segredos e criptografia baseada em SOPS sem construir todo o fluxo por conta própria.
• Você está tranquilo com um projeto de mantenedor único, anterior à 1.0, mas em desenvolvimento ativo.

Komodo. Escolha-o quando você gerencia muitos hosts e quer controle centralizado da frota, ou quando precisa de builds guiados por Git, e não apenas deploys, sob o mesmo teto.

Portainer (CE ou BE). Escolha-o quando a equipe quer uma interface para a operação diária de contêineres junto com o CD, quando a camada visual é o real motivo de você estar considerando a ferramenta.

Dokploy. Escolha-o quando você quer uma experiência de deploy no estilo PaaS e não precisa do controle cru do Compose.

GitHub Actions + SSH. Fique com isso quando for um serviço, um host, e você não precisar de reconciliação nem de recuperação de desvios.

Para quem está nesse meio-termo, depois do Watchtower e antes do Kubernetes, o Doco CD é uma escolha leve e forte. Minha leitura: para um homelab novo ou um SaaS pequeno, eu começaria com o Doco CD enquanto a operação Git em primeiro lugar e sem interface fizer sentido, e migraria para o Komodo assim que inventário centralizado, permissões e visibilidade da frota virarem requisitos.

Seja qual for a ferramenta escolhida, rode-a em um VPS Linux dimensionado para as cargas do Compose que ele vai hospedar. O VPS Linux da Cloudzy é um lar razoável para isso, com acesso root por padrão. E se você quiser pular a dança do apt, também dá para implantar o Docker com um clique a partir do nosso marketplace.

Nosso marketplace também tem imagens de um clique para Gitea, com o qual o Doco CD se integra nativamente. Também há imagens para Komodo também, e para Portainer, caso você decida que um deles é o formato que prefere.

Perguntas frequentes

O Doco CD está pronto para produção?

O Doco CD pode ir para produção se o perfil de risco dele combinar com a sua carga de trabalho. Ele é desenvolvido ativamente, mas ainda usa versionamento anterior à 1.0 e seu arquivo CODEOWNERS atribui o projeto a uma única pessoa. Fixe uma versão testada, teste as atualizações antes de aplicá-las e considere uma governança mais ampla no caso de infraestrutura crítica.

Como gerencio vários hosts com o Doco CD?

Use um contexto Docker e um destino de implantação separados para cada host. Uma única instância do Doco CD consegue implantar em vários hosts Docker remotos por SSH ou TCP; uma instância por host continua sendo um modelo de isolamento opcional. Escolha o Komodo se você precisa de inventário centralizado, permissões e visibilidade da frota.

Qual a diferença entre o modo webhook e o modo polling?

O modo webhook implanta quase instantaneamente quando chega um push ao Git, mas exige uma porta acessível pela internet, ou um proxy reverso na frente do Doco CD. O modo polling consulta o repositório em intervalos programados, então os deploys atrasam um pouco, mas nenhuma porta precisa ficar exposta. O polling é o padrão mais simples; webhooks valem a pena quando você faz push com frequência ou precisa de retorno rápido.

Como o Doco CD se compara ao Komodo?

O Doco CD é mais leve e sem interface, e consegue gerenciar vários hosts por meio de contextos Docker remotos. O Komodo usa um serviço Core central mais agentes Periphery e acrescenta uma interface de frota e builds guiados por Git. Escolha o Doco CD para implantar Compose sem interface; escolha o Komodo quando o controle centralizado da frota importar.

O Doco CD pode substituir o Watchtower?

Para o caso de uso que a maioria dos usuários do Watchtower realmente queria, "implante o que está no Git, quando o Git mudar", sim, é exatamente o que o Doco CD faz. Para o modelo literal do Watchtower, consultar um registro e baixar assim que aparece uma nova tag de imagem, não; o Doco CD é disparado pelo Git, não pelo registro. O modelo disparado por Git é a escolha mais segura e mais auditável para qualquer coisa além de serviços de brinquedo.