telemach-plugin-docker

TELEMACH PLUGIN DOCKER

TELEMACH est un plugin pédagogique pour Docker : quand une commande docker ou docker compose échoue, il t'explique en français ce qui s'est passé, le concept Docker en jeu, la cause probable et comment corriger, avec une sortie largement colorée.

$ docker run -p 8080:80 nginx:1.30-alpine
docker: Error response from daemon: … Bind for 0.0.0.0:8080 failed: port is already allocated

✖ Le port 8080 de ta machine est déjà utilisé.

📘 Concept — port publishing
   L'option « -p PORT_MACHINE:PORT_CONTENEUR » relie un port de ta machine à un
   port du conteneur. Un port de la machine ne peut être relié qu'une seule fois.

🔎 Cause probable
   Un autre conteneur (ou un autre programme de ta machine) écoute déjà sur le port 8080.

💡 Corrections
   1. Voir quel conteneur publie déjà ce port.
      docker ps --filter publish=8080
   2. Publier le conteneur sur un autre port de ta machine.
      docker run -p 8081:80 nginx:1.30-alpine

➜ Pour aller plus loin : docker telemach deepen

Le projet

Quand on apprend Docker, les erreurs arrivent vite, et elles sont écrites en anglais technique : Bind for 0.0.0.0:8080 failed, pull access denied, mapping values are not allowed in this context… Le message dit ce qui a échoué, rarement pourquoi, et encore moins ce qu'il faut comprendre pour ne plus refaire l'erreur.

TELEMACH transforme chaque erreur en petite leçon. Le nom vient de Télémaque, le fils d'Ulysse, guidé par Mentor dans l'Odyssée : le plugin joue ce rôle de mentor, au moment précis où tu en as besoin, dans ton propre terminal.

Il s'adresse aux personnes qui débutent ou progressent avec Docker : étudiants, développeurs qui découvrent les conteneurs, formateurs qui veulent un compagnon pour leurs travaux pratiques.

Le concept

Une erreur = une leçon en quatre temps

Chaque explication suit toujours la même structure, pour que l'apprenant prenne l'habitude de raisonner ainsi :

Si la même erreur se répète dans les 10 minutes, TELEMACH n'affiche qu'un rappel court ; docker telemach last réaffiche alors l'explication complète.

Le message Docker d'origine reste affiché, atténué, avec les éléments importants (port, image, chemin) surlignés : on apprend aussi à lire soi-même les erreurs Docker.

Trois principes

• Ne jamais inventer. Une erreur inconnue est présentée comme telle, avec des pistes et un lien vers la documentation officielle, mais sans cause supposée.
• Ne jamais agir à ta place. TELEMACH propose, tu décides : il n'exécute aucune commande et ne modifie aucun fichier.
• Enseigner les bonnes pratiques. Les exemples évitent root, --privileged et les secrets écrits en clair ; une solution dangereuse est toujours signalée comme telle.

Comment ça marche

flowchart LR
    A["Tu tapes<br/>docker …"] --> B["Fonction shell<br/>docker"]
    B --> C["Vrai docker<br/>(sortie inchangée)"]
    C -- "échec : code de sortie<br/>+ copie de stderr" --> D["docker-telemach explain"]
    D --> E["Nettoyage et<br/>masquage des secrets"]
    E --> F{"docker compose ?"}
    F -- oui --> G["Analyse des<br/>fichiers Compose"]
    F -- non --> H["Catalogue<br/>d'erreurs"]
    G --> I["Explication colorée<br/>en français"]
    H --> I

1. Capture. shell-init définit une fonction docker dans ton shell. Elle lance le vrai docker sans toucher à son entrée ni à sa sortie standard, et garde une copie de la sortie d'erreur dans un fichier temporaire privé (0600), supprimé juste après.
2. Nettoyage. Le texte capturé est traité comme non fiable : les séquences de contrôle du terminal sont neutralisées et les secrets (mots de passe, jetons, user:motdepasse@) sont masqués avant tout usage.
3. Diagnostic. Le catalogue (fichiers YAML en français, embarqués dans le binaire) reconnaît l'erreur grâce à des motifs. Le code de sortie indique si l'erreur vient de Docker (125) ou du programme du conteneur (126, 127, 137, 143 et les autres codes).
4. Compose. Pour docker compose, l'analyseur relit les fichiers Compose en lecture seule, avec le parseur officiel compose-go, pour pointer le fichier, la ligne et la clé exacts.
5. Rendu. L'explication est affichée sur la sortie d'erreur, avec un code couleur par bloc et la coloration syntaxique des commandes et des extraits YAML.

Vérifier un fichier Compose avant de le lancer

$ docker telemach check
✖ Problème 1/1 — compose.yaml:4:5
   service « web », clé « services.web.port »
   la clé « port » n'existe pas à cet endroit — tu voulais sans doute écrire « ports »

     1 │ services:
     2 │   web:
     3 │     image: nginx:1.30-alpine
   ➤ 4 │     port:
             ^
     5 │       - "8080:80"

   💡 Version corrigée
     4 │     ports:

L'analyse détecte : fichier introuvable ou illisible, tabulations, syntaxe YAML, clés en double ou inconnues (avec la clé probable), types de valeurs incorrects, services, réseaux ou volumes non déclarés, dépendances en boucle, variables non définies et secrets écrits en clair.

Installation

Prérequis

Go n'est pas nécessaire, sauf pour compiler depuis les sources. Windows natif (PowerShell) n'est pas pris en charge ; sous Windows, utilise WSL2.

1. Installer le plugin

Depuis une Release (recommandé)

Chaque version publie, sur la page des Releases, un binaire par système (Linux, macOS) et par processeur (amd64, arm64), avec un fichier de sommes de contrôle signé. Télécharge en ligne de commande plutôt qu'avec un navigateur : sous macOS, un fichier téléchargé par un navigateur peut être bloqué au premier lancement.

Linux et WSL2 :

VERSION=0.2.0
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64 ;; aarch64|arm64) ARCH=arm64 ;; esac
FICHIER=docker-telemach_${VERSION}_linux_${ARCH}
curl -fsSLO "https://github.com/aboigues/telemach-plugin-docker/releases/download/v${VERSION}/${FICHIER}"
curl -fsSLO "https://github.com/aboigues/telemach-plugin-docker/releases/download/v${VERSION}/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
mkdir -p ~/.docker/cli-plugins
install -m 0755 "$FICHIER" ~/.docker/cli-plugins/docker-telemach
docker telemach --version

macOS :

VERSION=0.2.0
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64 ;; aarch64|arm64) ARCH=arm64 ;; esac
FICHIER=docker-telemach_${VERSION}_darwin_${ARCH}
curl -fsSLO "https://github.com/aboigues/telemach-plugin-docker/releases/download/v${VERSION}/${FICHIER}"
curl -fsSLO "https://github.com/aboigues/telemach-plugin-docker/releases/download/v${VERSION}/checksums.txt"
shasum -a 256 --check --ignore-missing checksums.txt
mkdir -p ~/.docker/cli-plugins
install -m 0755 "$FICHIER" ~/.docker/cli-plugins/docker-telemach
docker telemach --version

La ligne --check doit afficher OK : la somme du fichier téléchargé correspond à celle publiée. Si elle affiche FAILED, n'installe pas ce fichier (téléchargement corrompu ou altéré) : supprime-le et recommence.

curl -fsSLO "https://github.com/aboigues/telemach-plugin-docker/releases/download/v${VERSION}/checksums.txt.sigstore.json"
cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/aboigues/telemach-plugin-docker/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

gh attestation verify "$FICHIER" --repo aboigues/telemach-plugin-docker

Avec Docker seulement

L'image officielle telemachlearning/telemach copie le bon binaire dans ton dossier des plugins Docker, sans rien d'autre à installer.

Linux et WSL2 :

mkdir -p ~/.docker/cli-plugins
docker run --rm --user "$(id -u):$(id -g)" -v ~/.docker/cli-plugins:/sortie telemachlearning/telemach:0.2.0 install

macOS (Docker Desktop) :

mkdir -p ~/.docker/cli-plugins
docker run --rm --user "$(id -u):$(id -g)" -e HOST_OS=darwin -v ~/.docker/cli-plugins:/sortie telemachlearning/telemach:0.2.0 install

Ce que fait chaque option, et ce qu'elle t'apprend de Docker :

L'image existe aussi sous le tag latest, mais préfère un tag de version : latest change à chaque publication, et une même commande pourrait installer deux versions différentes. Pour mettre à jour, relance la commande avec la nouvelle version : l'image indique la version remplacée.

L'image est minimale (FROM scratch : ni shell, ni gestionnaire de paquets), s'exécute sans privilèges et est signée. Vérification avec cosign v3 :

cosign verify telemachlearning/telemach:0.2.0 \
  --certificate-identity-regexp '^https://github\.com/aboigues/telemach-plugin-docker/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Essayer sans rien installer

Pour voir ce que TELEMACH dit de ton fichier Compose sans rien installer, lance l'image depuis le dossier de ton projet :

docker run --rm -t -v "$PWD":/projet:ro telemachlearning/telemach:0.2.0 check /projet

• -v "$PWD":/projet:ro monte le dossier courant dans le conteneur, en lecture seule (:ro) : l'image ne peut rien y modifier ;
• -t alloue un terminal, pour avoir les couleurs.

Les variables d'environnement de ton shell ne sont pas visibles dans le conteneur : si ton fichier Compose utilise ${NOM_VARIABLE}, TELEMACH la signalera comme non définie. Transmets-la avec -e, par exemple docker run --rm -t -e NOM_VARIABLE -v "$PWD":/projet:ro telemachlearning/telemach:0.2.0 check /projet.

L'essai ne couvre que la vérification des fichiers Compose : l'explication automatique des erreurs de docker demande d'installer le plugin.

Compiler depuis les sources

Il faut Go 1.27 ou plus récent (la version exacte, 1.27.2, est téléchargée automatiquement par Go).

git clone https://github.com/aboigues/telemach-plugin-docker.git
cd telemach-plugin-docker
mkdir -p ~/.docker/cli-plugins
go build -o ~/.docker/cli-plugins/docker-telemach ./cmd/docker-telemach

Vérifier l'installation

Docker découvre automatiquement les plugins placés dans ~/.docker/cli-plugins/. Vérifie :

docker telemach --version        # version, licence et site du projet
docker telemach --help
docker --help | grep telemach    # « telemach*  Explique en français les erreurs… »

2. Activer l'explication automatique

Ajoute la ligne correspondant à ton shell à la fin de son fichier de configuration :

# zsh — dans ~/.zshrc
eval "$(docker telemach shell-init zsh)"

# bash — dans ~/.bashrc
eval "$(docker telemach shell-init bash)"

Puis ouvre un nouveau terminal (ou recharge la configuration avec source ~/.zshrc).

3. Tester

type docker              # « docker is a shell function » : l'intégration est active
docker run --rm ngnix    # faute de frappe volontaire : TELEMACH propose « nginx »
docker telemach deepen   # approfondit cette erreur

Mettre à jour

Refais l'étape 1 avec la nouvelle version (VERSION=…) : le binaire est remplacé. Depuis les sources : git pull puis la même commande go build.

Désinstaller

1. Retire la ligne eval "$(docker telemach shell-init …)" de ton ~/.zshrc ou ~/.bashrc.

2. Supprime le plugin et son état local :

   rm ~/.docker/cli-plugins/docker-telemach
   rm -rf ~/.local/state/telemach
   

Dépannage

Commandes

Confidentialité et sécurité

• Fonctionne 100 % en local, sans aucun accès réseau.
• N'exécute aucune commande et ne modifie aucun de tes fichiers : il propose, tu décides. Seule exception : docker --version, lu une fois à l'activation pour connaître ta version de Docker.
• Masque les secrets (mots de passe, jetons, clés) partout où il affiche ou enregistre quelque chose.
• Le dernier diagnostic, déjà masqué, est conservé dans ~/.local/state/telemach/ (droits 0600) pour la commande deepen.

Couleurs

La sortie est colorée dans un terminal ; chaque bloc garde aussi un symbole et un libellé (✖, 📘, 🔎, 💡, ⚠), pour rester lisible sans couleur.

• --color=auto|always|never (par défaut auto) ;
• NO_COLOR=1 désactive les couleurs, CLICOLOR_FORCE=1 les force ;
• la palette s'adapte aux fonds clairs et sombres (variable COLORFGBG ou interrogation du terminal).

Désactivation ponctuelle

TELEMACH_DISABLE=1 docker …

Contribuer

Le projet suit une constitution : pédagogie, français pour l'humain et anglais pour le code, sécurité élevée, gates GitHub Actions obligatoires et mémoire des incidents (LESSON-LEARNED.md). Voir CONTRIBUTING.md et, pour enrichir le catalogue d'erreurs, docs/catalogue.md.

Signalement de vulnérabilité : voir SECURITY.md.

Licence

TELEMACH PLUGIN DOCKER est un logiciel libre distribué sous la licence Apache 2.0 — © 2026 TELEMACH Learning. Tu peux l'utiliser, le modifier et le redistribuer, y compris pour tes formations, en conservant les mentions des fichiers LICENSE et NOTICE.