ludix0/docker-update repository overview

⁠docker-update

👉 Jump to 🇬🇧 English⁠ · Aller au 🇫🇷 Français⁠

⁠🇬🇧 English

A self-hosted, containerized scheduler that safely tests, pulls, rebuilds and restarts your other Docker Compose projects — with a built-in scheduler, no host cron, no direct Docker socket exposure, and multi-channel notifications (email, Discord, ntfy, Telegram, Gotify, Pushover).

Point it at a folder full of ~/projects/<name>/docker-compose.yml projects and it takes care of the rest: run each project's tests, compare image digests before/after pull, rebuild local Dockerfiles, restart only what changed, verify containers are still up 10 seconds later, clean up unused images, and notify you — only when something actually happened.

⁠Features

• Scans a projects folder (find -L, symlink-aware) for any docker-compose.yml, at a configurable depth.
• Runs tests first: test.sh or make test (if a Makefile defines a test: target). A failing test cancels the update for that project only.
• Digest-based change detection: compares each image's resolved digest before and after docker compose pull — no restart if nothing changed.
• Rebuilds local images: if a project has its own Dockerfile, it's rebuilt every run.
• Restarts only on change, then waits and re-checks container state to catch a bad restart.
• Prunes unused images after each run.
• Timestamped logs per run + a latest.log symlink, with automatic retention/cleanup.
• Multi-channel notifications, any combination at once: email, Discord, ntfy, Telegram, Gotify, Pushover. Silent when nothing changed and nothing failed (no spam).
• Built-in scheduler: a daily trigger time (UPDATE_TIME), no dependency on the host's cron.
• Runs as a non-root user (configurable PUID/PGID), never touches /var/run/docker.sock directly — it goes through a filtering Tecnativa docker-socket-proxy⁠.
• Fully configurable via environment variables / .env — nothing is hardcoded.

⁠How it works

┌───────────────────────────┐    tcp://…:2375    ┌───────────────────────────┐
│       docker-update       │ ──────────────────► │   docker-socket-proxy    │
│ (scheduler + update logic)│                      │ (filters the Docker API) │
│        non-root user      │                      │                          │
└───────────────────────────┘                      └────────────┬─────────────┘
                                                                  │ ro bind-mount
                                                                  ▼
                                                       /var/run/docker.sock
                                                        (host Docker daemon)

docker-update never runs its own Docker daemon. It sends docker compose commands over the network to docker-socket-proxy, which is the only container allowed to touch the real socket — and only for the operations it explicitly allows (see Security⁠).

⁠Expected project layout

/home/you/projects/
├── nextcloud/
│   ├── docker-compose.yml
│   └── test.sh              # optional — exit 0 = pass, anything else = cancel update
├── vaultwarden/
│   ├── docker-compose.yml
│   └── Dockerfile           # optional — rebuilt on every run if present
└── some-app/
    ├── docker-compose.yml
    └── Makefile              # optional — needs a "test:" target

⁠Quick start

git clone <this-repo>
cd maj-docker
cp .env.example .env
# edit .env: at minimum set PROJETS_DIR and one notification channel
docker compose build
docker compose up -d
docker compose logs -f docker-update

To trigger a run immediately instead of waiting for UPDATE_TIME, either set RUN_ON_STARTUP=true in .env, or run it manually once:

docker compose exec --user appuser docker-update /app/update-projets.sh

⁠Configuration reference

All variables live in .env (copy .env.example first). Anything left empty falls back to the default shown, or disables the related feature.

⁠Container user & timezone

⁠Projects

⁠Logs

⁠Scheduler (no host cron involved)

⁠Update behavior

⁠Notifications — channel selection

A notification only fires when something failed or something was actually updated — an all-skipped run stays silent.

⁠Notification channels

Enable any combination via NOTIFY_CHANNELS. A channel listed there but left unconfigured (empty URL/token) is skipped with a log line — it never breaks the run.

⁠Security

• Never runs as root — a dedicated non-root user with configurable PUID/PGID, switched to via su-exec after a short root-only setup step (permission fixing, .msmtprc generation).
• Base images pinned by SHA256 digest, never a tag — immutable and reproducible builds.
• No secrets in the image: no ENV/ARG credentials in the Dockerfile. SMTP and every notification token/URL are injected at container runtime from .env, and .msmtprc is generated fresh on each start.
• No direct docker.sock mount in the update container. The only container touching the real socket is docker-socket-proxy, and it's configured with a minimal allow-list (containers, images, networks, volumes, build, start/stop/restart) — Swarm, secrets, exec, auth and everything else is explicitly denied.
• The proxy is never published on a host port — only reachable from the internal docker-update-net network.

⁠Troubleshooting

Full logs live at ${LOGS_DIR}/update-docker-<timestamp>.log on the host, with ${LOGS_DIR}/latest.log always pointing at the most recent run.

⁠🇫🇷 Français

Un ordonnanceur conteneurisé et auto-hébergé qui teste, met à jour, reconstruit et redémarre en toute sécurité vos autres projets Docker Compose — avec un ordonnanceur interne (sans cron de l'hôte), aucune exposition directe du socket Docker, et des notifications multi-canaux (email, Discord, ntfy, Telegram, Gotify, Pushover).

Pointez-le vers un dossier contenant des projets ~/projets/<nom>/docker-compose.yml et il s'occupe du reste : lancer les tests de chaque projet, comparer les digests d'images avant/après pull, reconstruire les Dockerfile locaux, ne redémarrer que ce qui a changé, vérifier 10 secondes plus tard que les conteneurs tournent toujours, nettoyer les images inutilisées, et vous notifier — uniquement quand quelque chose s'est réellement passé.

⁠Fonctionnalités

• Parcourt un dossier de projets (find -L, suit les liens symboliques) à la recherche de docker-compose.yml, à une profondeur configurable.
• Lance les tests en premier : test.sh ou make test (si un Makefile définit une cible test:). Un test qui échoue annule la mise à jour pour ce projet uniquement.
• Détection de changement par digest : compare le digest résolu de chaque image avant/après docker compose pull — aucun redémarrage si rien n'a changé.
• Reconstruit les images locales : si un projet a son propre Dockerfile, il est reconstruit à chaque passage.
• Redémarre uniquement en cas de changement, puis attend et revérifie l'état des conteneurs pour détecter un mauvais redémarrage.
• Nettoie les images inutilisées après chaque exécution.
• Logs horodatés à chaque exécution + un lien latest.log, avec purge automatique selon une durée de rétention.
• Notifications multi-canaux, combinables librement : email, Discord, ntfy, Telegram, Gotify, Pushover. Silencieux quand rien n'a changé et qu'aucune erreur n'est survenue (pas de spam).
• Ordonnanceur interne : une heure de déclenchement quotidienne (UPDATE_TIME), sans dépendre du cron de l'hôte.
• Toujours en utilisateur non-root (PUID/PGID configurables), ne touche jamais /var/run/docker.sock directement — il passe par un proxy filtrant Tecnativa docker-socket-proxy⁠.
• Entièrement configurable via des variables d'environnement / .env — rien n'est codé en dur.

⁠Fonctionnement

┌───────────────────────────┐   tcp://…:2375    ┌───────────────────────────┐
│       docker-update        │ ─────────────────► │   docker-socket-proxy    │
│ (ordonnanceur + logique)  │                     │ (filtre l'API Docker)    │
│      utilisateur non-root │                     │                          │
└───────────────────────────┘                     └────────────┬─────────────┘
                                                                  │ montage ro
                                                                  ▼
                                                       /var/run/docker.sock
                                                    (démon Docker de l'hôte)

docker-update ne fait jamais tourner son propre démon Docker. Il envoie ses commandes docker compose par le réseau à docker-socket-proxy, le seul conteneur autorisé à toucher le vrai socket — et uniquement pour les opérations qu'il autorise explicitement (voir Sécurité⁠).

⁠Arborescence de projets attendue

/home/vous/projets/
├── nextcloud/
│   ├── docker-compose.yml
│   └── test.sh              # optionnel — exit 0 = OK, sinon = annule la mise à jour
├── vaultwarden/
│   ├── docker-compose.yml
│   └── Dockerfile           # optionnel — reconstruit à chaque passage si présent
└── une-appli/
    ├── docker-compose.yml
    └── Makefile              # optionnel — nécessite une cible "test:"

⁠Démarrage rapide

git clone <ce-dépôt>
cd maj-docker
cp .env.example .env
# éditer .env : au minimum PROJETS_DIR et un canal de notification
docker compose build
docker compose up -d
docker compose logs -f docker-update

Pour déclencher une exécution immédiate plutôt que d'attendre UPDATE_TIME, soit mettez RUN_ON_STARTUP=true dans .env, soit lancez-la manuellement :

docker compose exec --user appuser docker-update /app/update-projets.sh

⁠Référence des variables

Toutes les variables vivent dans .env (copier .env.example d'abord). Une variable laissée vide reprend la valeur par défaut indiquée, ou désactive la fonctionnalité concernée.

⁠Utilisateur du conteneur et fuseau horaire

⁠Projets

⁠Logs

⁠Ordonnanceur (aucun cron de l'hôte impliqué)

⁠Comportement de la mise à jour

⁠Notifications — sélection des canaux

Une notification n'est envoyée que si quelque chose a échoué ou a effectivement été mis à jour — une exécution où tout est inchangé reste silencieuse.

⁠Canaux de notification

Activez n'importe quelle combinaison via NOTIFY_CHANNELS. Un canal listé mais non configuré (URL/jeton vide) est simplement ignoré avec une ligne de log — il ne bloque jamais l'exécution.

⁠Sécurité

• Jamais en root — un utilisateur dédié non-root avec PUID/PGID configurables, la bascule se faisant via su-exec après une courte étape d'initialisation en root (correction des permissions, génération de .msmtprc).
• Images de base épinglées par digest SHA256, jamais par tag — builds immuables et reproductibles.
• Aucun secret dans l'image : pas d'identifiants dans ENV/ARG du Dockerfile. SMTP et tous les jetons/URL de notification sont injectés au runtime depuis .env, et .msmtprc est régénéré à chaque démarrage.
• Aucun montage direct de docker.sock dans le conteneur de mise à jour. Le seul conteneur qui touche le vrai socket est docker-socket-proxy, configuré avec une liste minimale d'autorisations (containers, images, réseaux, volumes, build, start/stop/restart) — Swarm, secrets, exec, auth et tout le reste sont explicitement refusés.
• Le proxy n'est jamais exposé sur un port de l'hôte — uniquement joignable depuis le réseau interne docker-update-net.

⁠Dépannage

Les logs complets se trouvent dans ${LOGS_DIR}/update-docker-<horodatage>.log sur l'hôte, avec ${LOGS_DIR}/latest.log qui pointe toujours vers la dernière exécution.