Ogni push segue lo stesso rituale: accesso via SSH, pull del repository, riavvio dello stack Compose, la speranza che nulla si sia rotto e il tentativo di ricordare se hai eseguito la migrazione. Quel ciclo manuale regge finché non ti servono deployment ripetibili, un registro chiaro di ciò che è in esecuzione o il recupero dalla deriva.
Doco CD è una risposta diretta. È un piccolo servizio in Go che osserva il tuo repository Git e applica le modifiche Compose quando fai push: webhook o polling, scegli tu. ArgoCD e Flux fanno lo stesso per Kubernetes, ma Doco CD evita Kubernetes, perché non ha bisogno di un control plane.
Questa recensione copre cosa fa Doco CD, cosa non fa e come si confronta con Komodo, la modalità GitOps di Portainer, Dokploy e un semplice script GitHub Actions + SSH. Alla fine saprai se è adatto al tuo setup e cosa scegliere in caso contrario.
TL;DR
- Doco CD è un agente GitOps minuscolo e nativo per Compose: osserva un repository Git (GitHub, GitLab, Gitea, Forgejo e altri) e riconcilia il tuo stack quando qualcosa cambia.
- Il supporto integrato per provider di segreti esterni, insieme alla cifratura basata su SOPS, è ciò che lo distingue da uno script di deploy fatto in casa.
- Stando al suo README, si presenta come "una semplice alternativa a Portainer o ArgoCD per Docker". L'inquadramento è più o meno corretto.
- I limiti veri: un solo proprietario del codice, versionamento precedente alla 1.0, nessuna interfaccia per la gestione di una flotta e uno stato di riconciliazione che viene ricostruito solo dopo il successivo polling o evento webhook.
- Scegli questo quando gestisci uno o pochi host Compose e vuoi Git come fonte di verità senza interfaccia. Prendi Komodo per una flotta, Portainer se vuoi un'interfaccia, Dokploy per un'esperienza da PaaS, o GitHub Actions + SSH quando si tratta davvero di un solo servizio su un solo host.
Il vuoto che Doco CD prova a colmare
C'è una via di mezzo strana per chiunque usi Docker Compose nel 2026. I grandi strumenti GitOps come Argo CD e Flux puntano a Kubernetes, mentre il modello di Watchtower basato sul polling del registry reagisce ai cambi di immagine invece di applicare uno stato Compose versionato. Il repository è stato archiviato il 17 dicembre 2025 e ora dichiara che il progetto non è più mantenuto.
GitHub Actions più uno step di deploy via SSH funziona. Per un servizio su un host è la scelta giusta. I guai arrivano quando aggiungi un secondo host, o un secondo stack, o vuoi sapere quale commit è attualmente in produzione. I log del workflow restano, ma non hai riconciliazione nativa per Compose, né recupero dalla deriva, né una vista persistente su quanto l'host corrisponda ancora al repository.
La proposta di Doco CD, presa direttamente dal README, è "una semplice alternativa a Portainer o ArgoCD per Docker". Quell'inquadramento è tutto il punto: piccolo, nativo per Compose, niente Kubernetes, nessuna interfaccia da mantenere, nessun control plane centrale da sorvegliare. Se non usi K8s e non volevi farlo, questa è la categoria che cercavi.
Come funziona davvero Doco CD
Doco CD è un singolo binario Go che gira in un container Docker, osserva un repository Git e applica le modifiche Compose quando lo stato del repository cambia. Il concetto è tutto qui. Le parti interessanti stanno nei valori predefiniti e nelle integrazioni.
Trigger. Due modalità: webhook o polling. Il webhook è quasi istantaneo ma richiede una porta esposta, o più realisticamente un reverse proxy davanti a Doco CD. Il polling è un recupero periodico: leggermente in ritardo, senza porte in ingresso. Il polling è il default più semplice e, secondo la documentazione ufficiale , entrambi sono di prima classe. Scegli in base al fatto che il tuo host abbia o meno un endpoint pubblico raggiungibile e a quanto ti servono deploy rapidi.
Configurazione per repository. Un file .doco-cd.yaml (o .doco-cd.yml) sta nella radice del repository, accanto al tuo file Compose. L'unico campo obbligatorio è il nome del deployment. Una configurazione minima è così:
# .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: falseQuesti sono i valori predefiniti documentati: timeout di 180 secondi, container orfani rimossi, immagini ripulite e nessuna ricreazione forzata.
Rilevamento automatico. Con il rilevamento automatico attivo, Doco CD analizza le sottocartelle in cerca di file Compose, così un solo repository può contenere più stack. Supporta anche più configurazioni di deployment in un unico file, scritte come documenti YAML separati da una riga di tre trattini. I valori predefiniti per la pulizia sono prudenti e vale la pena leggerli prima di affidarcisi:
| Impostazione | Predefinito | Che cosa significa |
|---|---|---|
delete | false | Un deployment obsoleto viene lasciato al suo posto quando la sua app sparisce dalla directory di lavoro. |
remove_volumes | false | I volumi sopravvivono quando uno stack rilevato automaticamente viene eliminato. |
remove_images | true | Le immagini inutilizzate vengono rimosse quando uno stack rilevato automaticamente viene eliminato. |
In altre parole, nulla viene smontato alle tue spalle finché non attivi l'eliminazione, e anche allora i volumi dei dati sono gli ultimi ad andarsene.
Provider Git supportati. Sono supportati GitHub, GitLab, Gitea, Forgejo, Gogs e Azure DevOps. Azure DevOps è l'eccezione per i webhook, perché gli Azure Service Hooks non sono supportati. Il supporto a Gitea e Forgejo conta se ospiti la tua forge in casa.
Docker Swarm. Supportato come destinazione. Ciò che la pagina delle impostazioni di deploy segnala esplicitamente: in modalità Swarm la riconciliazione non controlla né i riavvii dei container né lo stato di salute, e la pulizia delle immagini non è supportata in Swarm. Se il tuo bersaglio è Swarm, ottieni i deploy ma non una riconciliazione completa della salute.
Riconciliazione. Per impostazione predefinita c'è un limite di 5 riavvii in una finestra di 300 secondi, pensato per evitare che health check instabili girino all'infinito. Stesso repository con ref diversa gira in sequenza, stesso repository con la stessa ref gira in parallelo. Quest'ultimo dettaglio è sottile ma utile: più deploy della stessa ref non si accodano l'uno dietro l'altro.
Provider di segreti esterni integrati. Questo è uno dei motivi più forti per preferire Doco CD a un semplice script di deploy: supporta AWS Secrets Manager, Bitwarden Secrets Manager, Bitwarden Vault / Vaultwarden, 1Password, 1Password Connect, Infisical, OpenBao e Webhook. A parte, supporta la cifratura basata su SOPS per i dati di deployment sensibili. Ti offre così una via pulita per abbandonare i file env in chiaro dentro Git, senza costruire da zero l'intero flusso di risoluzione dei segreti.
Il resto. Doco CD fornisce metriche Prometheus, pianificazione dei job, notifiche, un'immagine container distroless e una licenza Apache-2.0. Stando alla sua cronologia dei rilasci, al 20 agosto 2026, la v0.109.2 è l'ultima release stabile e la v0.110.0-rc.1 è la prerelease più recente.
Il compito di Doco CD si ferma ad "applicare il manifest"; da lì in poi è Docker normale. I comandi di log di Compose sono ciò con cui ispezionerai quello che è in esecuzione.
Consiglio pratico sui segreti. Se il tuo repository privato contiene ancora file env in chiaro, dai la priorità ai provider di segreti esterni di Doco CD o al suo supporto per SOPS. L'obiettivo è semplice: togliere i segreti in chiaro da Git lasciando comunque che i deployment risolvano i valori a runtime.
Costruisci su un VPS Linux con accesso root, NVMe e la potenza di AMD EPYC.
Vedi piani LinuxDove Doco CD non arriva
Ogni strumento ha dei limiti, e quelli di Doco CD vale la pena conoscerli prima di dedicare un weekend alla configurazione.
Un solo proprietario del codice. Il file CODEOWNERS del repository assegna tutti i percorsi a kimdre. I rilasci restano frequenti, ma la governance è concentrata in una sola persona.
Prima della 1.0. Doco CD usa ancora il versionamento 0.x, quindi fissa una release testata e leggi le note di aggiornamento prima del rollout. La issue GitHub #851, ormai chiusa, mostra perché: Docker v29 ha costretto il progetto ad abbandonare moduli Go di Docker deprecati.
Nessuna shell dentro il container di Doco CD. Per sicurezza, Doco CD non fornisce un ambiente shell e non esegue script arbitrari sull'host. Le operazioni prima e dopo il deployment devono passare da init container, sidecar o hook del ciclo di vita di Compose, il che aggiunge configurazione rispetto a strumenti che lanciano direttamente uno script di deploy.
Perdita di stato al riavvio. Lo stato di riconciliazione vive in memoria. Quando Doco CD si riavvia, quello stato viene ricostruito solo dopo il successivo polling o evento webhook, quindi la durata del buco dipende dal tuo intervallo di polling o da quanto presto arriva un altro webhook.
Nessuna interfaccia per la gestione della flotta. Il multi-host non richiede più un agente per ogni macchina. Dalla v0.102.0 le configurazioni di deployment possono puntare a contesti Docker remoti, inclusi i contesti SSH, e un singolo repository può definire più destinazioni di deployment. Eseguire un'istanza di Doco CD per host resta valido, ma ora un'istanza centrale può distribuire su host Docker remoti. Ciò che a Doco CD manca ancora è l'interfaccia di gestione della flotta di Komodo e un inventario centralizzato degli host.
L'impronta di RAM e CPU non è documentata con numeri. La documentazione ufficiale definisce i requisiti "minuscoli" ma non pubblica alcun valore di riferimento. Dimensiona il VPS in base alle applicazioni che ospiterà, lascia margine operativo e verifica il consumo reale di Doco CD nel tuo ambiente.
Consiglio pratico sul multi-host. Usa un contesto Docker e una destinazione di deployment distinti per ogni host, limita l'accesso SSH e mantieni univoci i segreti di webhook o API. Se preferisci agenti isolati, un'istanza di Doco CD per host resta una scelta valida.
Doco CD contro le alternative
Gli altri quattro strumenti che metterei in lista provano tutti a risolvere "distribuire Compose automaticamente da Git", ma con compromessi molto diversi. La decisione non è se farlo, quello lo hai già deciso. La decisione è quale forma di strumento si adatta al tuo setup. Ecco il confronto affiancato.
| Strumento | Trigger | Modello multi-host | Segreti | Interfaccia Web | Licenza |
|---|---|---|---|---|---|
| Doco CD | Webhook o polling | Contesti Docker remoti, nessuna interfaccia di flotta | Provider esterni più SOPS | Nessuno | Apache-2.0 |
| Komodo | Webhook più sincronizzazione pianificata | Core centrale più agenti Periphery | Gestione di variabili e segreti | Sì | GPL-3.0 |
| Portainer (CE/BE) | Webhook o polling | Agente Portainer | Limitati, più opzioni in BE | Sì | Zlib, condizioni commerciali per BE |
| Dokploy | Attivato dal push | Multi-server o Docker Swarm | Gestione degli ambienti integrata | Sì | Apache-2.0, con componenti proprietari |
| GitHub Actions + SSH | Attivato dal push | Quello che scrivi nello script | Quello che scrivi nello script | Nessuno | Non applicabile |
Due parole su ciascuno, perché la tabella dà la forma e il commento dà il perché:
Komodo. L'alternativa seria per il multi-host. Un servizio Core centrale più un agente Periphery su ogni host, un'unica interfaccia che li vede tutti, build guidate da Git oltre ai deploy e supporto per Docker Swarm. È più pesante da mettere in piedi, perché fai girare un database e un control plane, ma è la forma giusta se hai una flotta. Komodo calza meglio quando conta il controllo centralizzato della flotta.
Portainer (CE o BE) con GitOps. Un'interfaccia grafica completa sopra la sincronizzazione con Git. È la scelta giusta quando il team vuole gestire i container a colpi di clic insieme al CD. Se qualcuno passerà comunque dall'interfaccia per leggere log e riavviare container, tanto vale avere lì anche il CD. L'impronta sulle risorse è più pesante di Doco CD. OIDC/SSO e RBAC granulare sono dietro il paywall della Business Edition. La nostra guida alle alternative a Portainer copre il panorama più ampio della gestione di Docker.
Dokploy. Stile PaaS. Ha idee precise, distribuisce automaticamente al push, offre un'interfaccia web per tutto e ti prepara Traefik con URL puliti fin da subito. Meglio per team che vogliono un'esperienza alla Heroku e sono disposti a barattarci la flessibilità grezza di Compose. Se sei allergico a YAML, questa è la strada più leggera verso "faccio git push e l'app va online".
GitHub Actions + SSH. Zero infrastruttura aggiuntiva. Il job di deploy vive nel workflow che hai già. Ottieni i log del workflow, ma nessuna riconciliazione nativa per Compose, nessun recupero dalla deriva e nessuna vista persistente dello stato degli host, a meno che tu non costruisca quei pezzi da solo. Va benissimo per un servizio su un host. Si rompe appena aggiungi un secondo bersaglio o vuoi sapere cosa gira dove senza collegarti in SSH. Per la fetta più semplice del pubblico, GitHub Actions + SSH resta la risposta giusta.
C'è un nuovo arrivato chiamato stackd , che si presenta con parole simili: "GitOps senza la tassa di Kubernetes". Vale la pena sapere che la categoria è viva, non vale la pena preferirlo a Doco CD lanciando una monetina oggi.
Quando Doco CD è la scelta giusta (e quando no)
Scegli Doco CD quando:
- Gestisci uno o pochi host Docker Compose e vuoi Git come fonte di verità.
- Preferisci modificare YAML nel tuo editor piuttosto che cliccare in un'interfaccia.
- Vuoi il supporto per provider di segreti esterni e la cifratura basata su SOPS senza costruire da solo l'intero flusso.
- Ti sta bene un progetto con un solo manutentore, precedente alla 1.0 ma sviluppato attivamente.
Komodo. Scegli questo quando gestisci molti host e vuoi un controllo centralizzato della flotta, o quando ti servono build guidate da Git, non solo deploy, sotto lo stesso tetto.
Portainer (CE o BE). Scegli questo quando il team vuole un'interfaccia per le operazioni quotidiane sui container accanto al CD, quando cioè il livello visuale è il vero motivo per cui stai valutando lo strumento.
Dokploy. Scegli questo quando vuoi un'esperienza di deploy in stile PaaS e non ti serve il controllo grezzo di Compose.
GitHub Actions + SSH. Restaci quando si tratta di un servizio, un host, e non ti servono riconciliazione o recupero dalla deriva.
Per chi si trova in quella via di mezzo, dopo Watchtower e prima di Kubernetes, Doco CD è una scelta leggera ma solida. La mia lettura: per un homelab nuovo o un piccolo SaaS partirei da Doco CD finché va bene un'operatività Git-first e senza interfaccia, per poi passare a Komodo quando inventario centralizzato, permessi e visibilità sulla flotta diventano requisiti.
Qualunque strumento tu scelga, eseguilo su un VPS Linux dimensionato per i carichi Compose che dovrà ospitare. Il VPS Linux di Cloudzy è una casa ragionevole per questo, con accesso root di serie. E se vuoi saltare la danza di apt, puoi anche distribuire Docker con un clic dal nostro marketplace.
Il nostro marketplace offre anche immagini installabili con un clic per Gitea, con cui Doco CD si integra nativamente. Ci sono immagini anche per Komodo e per Portainer, se decidi che una di quelle è la forma che preferisci.
Domande frequenti
Doco CD è pronto per la produzione?
Doco CD può stare in produzione se il suo profilo di rischio è compatibile con il tuo carico. È sviluppato attivamente, ma usa ancora versionamento precedente alla 1.0 e il suo file CODEOWNERS assegna il progetto a una sola persona. Fissa una release testata, prova gli aggiornamenti prima del rollout e valuta una governance più ampia se si tratta di infrastruttura critica.
Come gestisco più host con Doco CD?
Usa un contesto Docker e una destinazione di deployment separati per ogni host. Una sola istanza di Doco CD può distribuire su più host Docker remoti via SSH o TCP; un'istanza per host resta un modello di isolamento opzionale. Scegli Komodo se ti servono inventario centralizzato, permessi e visibilità sulla flotta.
Qual è la differenza tra modalità webhook e polling?
La modalità webhook distribuisce quasi all'istante quando arriva un push su Git, ma richiede una porta raggiungibile da internet, o un reverse proxy davanti a Doco CD. La modalità polling controlla il repository a intervalli programmati, quindi i deploy arrivano con un leggero ritardo ma non serve esporre alcuna porta. Il polling è il default più semplice; i webhook valgono la pena quando fai push spesso o ti serve un ciclo di feedback rapido.
Come si confronta Doco CD con Komodo?
Doco CD è più leggero e senza interfaccia, e può gestire più host tramite contesti Docker remoti. Komodo usa un servizio Core centrale più agenti Periphery e aggiunge un'interfaccia per la flotta e build guidate da Git. Scegli Doco CD per il deployment di Compose senza interfaccia; scegli Komodo quando conta il controllo centralizzato della flotta.
Doco CD può sostituire Watchtower?
Per il caso d'uso che la maggior parte degli utenti di Watchtower voleva davvero, cioè "distribuisci ciò che sta in Git, quando Git cambia", la risposta è sì: è esattamente ciò che fa Doco CD. Per il modello letterale di Watchtower, cioè interrogare un registry e scaricare quando compare un nuovo tag di immagine, la risposta è no; Doco CD è innescato da Git, non dal registry. Il modello innescato da Git è la scelta più sicura e più verificabile per qualunque cosa vada oltre i servizi giocattolo.
