wiki/Catalogue-Self-Hosted/apps/app-doco-cd.md

---
title: Doco-CD
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, docker, ci-cd, deploiement, go, auto-hebergement]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Docker, https://github.com/kimdre/doco-cd]
---

# 🐳 Doco-CD

> **Le déploiement continu pour vos `docker-compose.yml`** : Doco-CD surveille votre dépôt Git, et dès qu'un `docker-compose.yml` est modifié, il tire les nouvelles images et redémarre les services. Le CD idéal pour un homelab ou une petite prod.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | (GitHub) |
| **GitHub** | [kimdre/doco-cd](https://github.com/kimdre/doco-cd) |
| **License** | MIT |
| **Langage** | Go |
| **Étoiles GitHub** | 1479 ⭐ |
| **Dernière MAJ** | 2026-05-22 |
| **Catégorie** | [[cat-docker\|Docker]] |

## 📝 Description

**Doco-CD** (Docker Compose Continuous Deployment) est un **agent de déploiement continu** spécialisé dans les fichiers `docker-compose.yml`. Il **surveille un dépôt Git** (GitHub, Gitea, GitLab, Forgejo…), détecte les changements sur des stacks Compose, et applique automatiquement `docker compose pull && docker compose up -d` sur l'hôte cible.

L'idée : pousser du CD sans la complexité de GitHub Actions, Jenkins ou Gitea Actions. Un seul binaire Go, un seul `docker-compose.yml`, et vous avez un pipeline « push to deploy ».

- ✅ **Watch Git** : poll ou webhook, sur n'importe quel dépôt (GitHub, Gitea, GitLab, Forgejo, Bitbucket…)
- ✅ **Multi-stacks** : un seul dépôt peut contenir plusieurs dossiers Compose, chacun déployé indépendamment
- ✅ **Multi-hôte** : un seul agent Doco-CD peut déployer sur plusieurs machines via SSH
- ✅ **Hooks pre/post-deploy** : scripts custom à exécuter avant/après le redéploiement (ex : backup, notif)
- ✅ **Notifications** : Discord, Slack, Telegram, Ntfy, Gotify, email, webhook
- ✅ **GUI web** : dashboard des déploiements, historique, logs
- ✅ **API REST** : déclenchement manuel d'un redéploiement via API
- ✅ **Mode polling ou webhook** : selon vos contraintes réseau

**Doco-CD vs [[app-dockge|Dockge]]** : Dockge est un *gestionnaire interactif* (cliquez sur Update dans l'UI) ; Doco-CD est un *agent automatique* (détecte le push Git, agit seul). Doco-CD vs Watchtower : Watchtower ne fait que les updates d'images ; Doco-CD redéploie *tout* le stack si le YAML a changé. Doco-CD vs Woodpecker CI / Gitea Actions : Doco-CD est *ultra-spécialisé* Compose, sans la complexité d'un runner CI générique.

## 🚀 Installation

### Docker Compose (recommandé)

```yaml
# docker-compose.yml (sur l'hôte de déploiement)
version: '3.8'
services:
  doco-cd:
    image: ghcr.io/kimdre/doco-cd:latest
    container_name: doco-cd
    restart: unless-stopped
    ports:
      - "8080:8080"  # Web UI
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - doco-cd-data:/data
      - /path/to/your/stacks:/stacks  # optionnel : stacks locales
    environment:
      - TZ=Europe/Paris
      - GIT_REPOSITORY=https://github.com/user/homelab-stacks
      - GIT_BRANCH=main
      - POLLING_INTERVAL=60  # en secondes (0 = webhook only)
      - COMPOSE_PROJECT_DIR=/stacks
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.doco-cd.rule=Host(`deploy.example.com`)"
      - "traefik.http.routers.doco-cd.entrypoints=websecure"
      - "traefik.http.routers.doco-cd.tls.certresolver=letsencrypt"

volumes:
  doco-cd-data:
```

### Exemple de structure de dépôt

```
homelab-stacks/
├── nextcloud/
│   └── docker-compose.yml
├── jellyfin/
│   └── docker-compose.yml
└── traefik/
    └── docker-compose.yml
```

Doco-CD détecte chaque dossier contenant un `docker-compose.yml` et le gère comme un « stack » indépendant.

## ⚙️ Configuration Initiale

1. **Préparer un dépôt Git** avec vos `docker-compose.yml` (un sous-dossier par stack)
2. **Monter le socket Docker en `rw`** : Doco-CD doit pouvoir pull, recreate, restart
3. **Configurer `GIT_REPOSITORY`** et `GIT_BRANCH` dans l'environnement
4. **Choisir le mode** : `POLLING_INTERVAL=60` (poll toutes les 60 s) ou 0 (webhook uniquement, plus économe)
5. **Configurer un webhook** sur votre forge (pointant vers `https://deploy.example.com/webhook`) si mode webhook
6. **Tester un déploiement** : modifier un `docker-compose.yml`, commit & push, observer le déploiement dans l'UI
7. **Ajouter un canal de notification** pour les alertes de déploiement

## 🔄 Alternatives

### Open Source
- [[app-dockge|Dockge]] — GUI interactive, pas de Git watch
- **Watchtower** — update d'images, pas de redéploiement de stack
- **Komodo** ([[app-komodo|Komodo]]) — orchestrateur complet (build + deploy)
- **Woodpecker CI** — CI/CD générique, plus puissant mais plus complexe
- **Gitea Actions / Forgejo Actions** — CI/CD intégré aux forges
- **ArgoCD** — pour Kubernetes, pas Docker Compose

### Comparaison Doco-CD vs alternatives

| Critère | Doco-CD | Dockge | Watchtower | Komodo |
| :--- | :--- | :--- | :--- | :--- |
| Watch Git | ✅ | ❌ | ❌ | ✅ |
| Redéploiement auto | ✅ | ❌ (manuel) | ⚠️ (MAJ image) | ✅ |
| Multi-hôte | ✅ (SSH) | ❌ | ❌ | ✅ |
| Build d'images | ❌ | ❌ | ❌ | ✅ |
| GUI | ✅ | ✅ | ❌ | ✅ |
| Setup | 10 min | 5 min | 3 min | 30 min |

**Verdict** : Doco-CD est **le choix idéal pour du CD Git → Compose** simple. Si vous avez besoin de builder des images en plus, passez à Komodo. Pour du GitOps Kubernetes, c'est ArgoCD.

### Propriétaires (ce que Doco-CD remplace)
- **Watchtower + cron + script bash** (le « DIY » que Doco-CD remplace)
- **Portainer Auto Update** (Business Edition)
- **Cloud 66 / Capistrano** (CD pour VM, payants)
- **Octopus Deploy** (CD enterprise, payant)

## 🔐 Sécurité

- ⚠️ **Socket Docker en `rw`** : Doco-CD peut recreate **n'importe quel conteneur** de l'hôte. C'est *by design* (il déploie des stacks) mais cela en fait une cible de choix
- **Protéger la GUI** : reverse-auth (ex : [[app-authelia|authelia]]) obligatoire si accessible au-delà du LAN
- **Tokens Git** : si dépôt privé, utiliser un token en lecture seule dans `GIT_TOKEN` — ne jamais mettre de token admin
- **Webhook secret** : configurer un secret partagé entre la forge et Doco-CD pour éviter les déploiements non sollicités

## 📚 Ressources

- [GitHub kimdre/doco-cd](https://github.com/kimdre/doco-cd)
- [Documentation complète](https://github.com/kimdre/doco-cd/wiki)

## Pages Liées
- [[cat-docker]] — Catégorie Docker
- [[app-portainer]] / [[app-dockge]] / [[app-yacht]] — GUI Docker
- [[app-traefik]] — Reverse-proxy
- [[recettes-docker-compose]] — Compose files
- [[securisation-home-lab]] — Bonnes pratiques