Étendre Takuto Core

Vous aurez souvent besoin d’outils qui ne sont pas intégrés à l’image officielle — kubectl, terraform, un CLI vendor interne, ou une version épinglée de claude. Takuto Core dispose d’un modèle d’extension à trois niveaux, plus une quatrième voie pour les ajustements runtime uniquement. Choisissez celle qui correspond à votre besoin.

Le principe directeur : Intégré = requis pour les fonctionnalités annoncées, Provisioning = préférences de l’admin, Image personnalisée = besoins spécialisés au niveau de l’OS.

Mécanisme 1 — [provisioning].install_commands

Le cas le plus courant. À chaque démarrage de Takuto, l’entrypoint exécute une passe d’installation conditionnée par un SHA :

1. Il hashe la liste install_commands.
2. Si le hash correspond à la dernière exécution réussie → on saute (la voie rapide ; s’exécute à chaque démarrage tant que rien n’a changé).
3. S’il diffère → il exporte MAESTRO_TOOLS_BIN=/opt/maestro-tools/bin et lance chaque commande via bash -c en tant que root. Les échecs par commande logguent un avertissement mais n’interrompent pas. Le nouveau hash n’est enregistré qu’en cas de succès complet, donc les échecs partiels sont retentés au prochain démarrage.

Les outils atterrissent dans le volume Docker maestro-tools, monté en lecture seule dans chaque container worker, éditeur et run-command, avec /opt/maestro-tools/bin en premier sur le $PATH — donc tout ce que vous y déposez est disponible partout et masque les outils intégrés du même nom.

L’idempotence est de votre ressort

Les ré-exécutions ont lieu dès que la liste change — y compris quand vous ajoutez une commande (les existantes sont alors ré-exécutées aussi). Protégez chaque commande par un test d’existence :

[provisioning]
install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/kubectl" ] || (curl -fsSLo "$MAESTRO_TOOLS_BIN/kubectl" https://dl.k8s.io/release/v1.31.0/bin/linux/amd64/kubectl && chmod +x "$MAESTRO_TOOLS_BIN/kubectl")',
]

Après un redémarrage, chaque workflow peut appeler kubectl directement.

Épingler claude à une version précise

[provisioning]
install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/claude" ] || (npm install -g --prefix "$MAESTRO_TOOLS_BIN/.npm" @anthropic-ai/claude-code@2.1.140 && ln -sf "$MAESTRO_TOOLS_BIN/.npm/bin/claude" "$MAESTRO_TOOLS_BIN/claude")',
]

La précédence du PATH fait gagner la version épinglée sur le @latest intégré. Pour revenir en arrière : retirez la ligne, redémarrez, et rm /opt/maestro-tools/bin/claude.

Installer un CLI vendor privé

install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/mycli" ] || curl -fsSL -H "Authorization: token $MYCO_TOKEN" https://internal.example.com/cli/mycli-v2.tgz | tar -xz -C "$MAESTRO_TOOLS_BIN"',
]

Définissez MYCO_TOKEN dans takuto.env pour que la commande d’install puisse le voir.

Forcer une réinstallation sans changer la config

Le verrou SHA saute les ré-exécutions quand la liste est inchangée. Pour en forcer une (par ex. vous suspectez un binaire cassé) :

docker exec --user root maestro-core-maestro-1 \
    rm /opt/maestro-tools/.provisioning-sha
docker compose restart maestro

Tout effacer

docker compose down
docker volume rm maestro-core_maestro-tools
docker compose up -d

Mécanisme 2 — Dockerfile personnalisé

À utiliser pour les paquets système (bibliothèques apt, daemons) ou tout ce qui touche plusieurs répertoires de l’OS (/etc, /usr/share, /var/lib). Le volume maestro-tools n’écrit que dans un seul répertoire bin/, donc le provisioning n’est pas le bon outil pour les installations à l’échelle du système.

# my-takuto.Dockerfile
FROM ghcr.io/takuto-team/takuto-core:latest
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
        awscli postgresql-client \
    && rm -rf /var/lib/apt/lists/*
USER maestro

Câblez-le dans docker-compose.yml :

services:
  maestro:
    build:
      context: .
      dockerfile: my-takuto.Dockerfile

Puis docker compose build maestro && docker compose up -d.

Mécanisme 3 — docker-compose.override.yml

Compose fusionne docker-compose.override.yml automatiquement. Utilisez-le pour les ajustements runtime uniquement qui ne nécessitent pas de rebuild.

Variables d’environnement supplémentaires :

services:
  maestro:
    environment:
      - GH_HOST=github.example.com   # instance GHE interne
      - MY_API_TOKEN=...

Bind mount supplémentaire :

services:
  maestro:
    volumes:
      - /host/shared-cache:/home/maestro/.cache/shared:ro

Les overrides Compose n’affectent que le service maestro. Pour propager un montage ou une variable d’env aux containers worker générés, les listes worker volume / passthrough-env du moteur doivent les inclure — voir les sources de Takuto Core pour WORKER_VOLUMES et PASSTHROUGH_ENV.

Inventaire des outils en un coup d’œil

• Intégrés (requis pour les fonctionnalités annoncées) : node, npm, la toolchain Rust (cargo/rustfmt/clippy), git, gh, acli, jq, le CLI docker, iptables, claude, cursor-agent, codex, opencode, openvscode-server, mise, et les bibliothèques Playwright/Chromium.
• Valeurs de provisioning par défaut (l’admin peut épingler/remplacer/désactiver) : des outils mono-binaire comme les CLI Figma et Lokalise.
• Retirés (à gérer via une image personnalisée) : des outils comme AWS CLI v2 dont seule une minorité de déploiements a besoin.

Dépannage du provisioning

• « Ma commande ne se lance pas au redémarrage. » Le verrou SHA saute les listes inchangées — modifiez quelque chose (même un commentaire) pour changer le hash, ou rm /opt/maestro-tools/.provisioning-sha puis redémarrez.
• « Les workers ne voient pas mon outil. » Vérifiez qu’il a bien atterri dans le volume (docker exec maestro-core-maestro-1 ls /opt/maestro-tools/bin/) et que /opt/maestro-tools/bin est en premier sur le $PATH du worker. Cherchez les lignes [maestro-provisioning] … WARN dans le log de démarrage pour repérer les échecs d’install.

Pour en savoir plus, voir dépannage.