Extender Takuto Core

A menudo necesitarás herramientas que no vienen horneadas en la imagen oficial — kubectl, terraform, una CLI interna de un proveedor, o una versión fijada de claude. Takuto Core tiene un modelo de extensión de tres niveles, más una cuarta vía para ajustes solo de tiempo de ejecución. Elige la que encaje con tu necesidad.

El principio rector: Horneado = requerido para las funcionalidades anunciadas, Provisioning = preferencias del admin, Imagen a medida = necesidades especializadas a nivel de SO.

Mecanismo 1 — [provisioning].install_commands

El caso más común. En cada arranque de Takuto, el entrypoint ejecuta una pasada de install protegida por SHA:

1. Hashea la lista install_commands.
2. Si el hash coincide con la última ejecución exitosa → omite (la ruta rápida; corre en cada arranque cuando nada cambió).
3. Si difiere → exporta MAESTRO_TOOLS_BIN=/opt/maestro-tools/bin y ejecuta cada comando vía bash -c como root. Los fallos por comando registran un warning pero no abortan. El nuevo hash se registra solo en caso de éxito total, así que los fallos parciales se reintentan en el siguiente arranque.

Las herramientas aterrizan en el volumen de Docker maestro-tools, montado en bind como solo lectura en cada container de worker, editor y run-command, con /opt/maestro-tools/bin primero en el $PATH — así que cualquier cosa que dejes ahí está disponible en todas partes y eclipsa las herramientas horneadas del mismo nombre.

La idempotencia es responsabilidad tuya

Las reejecuciones ocurren cada vez que la lista cambia — incluido cuando añades un comando (los existentes también se reejecutan). Protege cada comando con una comprobación de existencia:

[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")',
]

Tras un reinicio, cada workflow puede llamar a kubectl directamente.

Fijar claude a una versión específica

[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 precedencia del PATH hace que la versión fijada gane sobre el @latest horneado. Para revertir: quita la línea, reinicia y rm /opt/maestro-tools/bin/claude.

Instalar una CLI privada de proveedor

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"',
]

Fija MYCO_TOKEN en takuto.env para que el comando de install pueda verlo.

Forzar una reinstalación sin cambiar la configuración

La puerta SHA omite las reejecuciones cuando la lista no cambia. Para forzar una (p. ej. sospechas de un binario roto):

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

Borrar todas las personalizaciones

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

Mecanismo 2 — Dockerfile a medida

Usa esto para paquetes del sistema (librerías apt, daemons) o cualquier cosa que toque múltiples directorios del SO (/etc, /usr/share, /var/lib). El volumen maestro-tools solo escribe un único directorio bin/, así que el provisioning es la herramienta equivocada para instalaciones a nivel de sistema.

# 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

Cabléalo en docker-compose.yml:

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

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

Mecanismo 3 — docker-compose.override.yml

Compose fusiona docker-compose.override.yml automáticamente. Úsalo para ajustes solo de tiempo de ejecución que no necesitan un rebuild.

Variables de entorno extra:

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

Bind mount extra:

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

Los overrides de compose afectan solo al servicio maestro. Para propagar un mount o una variable de entorno a los containers de worker generados, las listas de volúmenes de worker / env de passthrough del motor deben incluirlos — consulta el código fuente de Takuto Core para WORKER_VOLUMES y PASSTHROUGH_ENV.

Inventario de herramientas de un vistazo

• Horneadas (requeridas para las funcionalidades anunciadas): node, npm, el toolchain de Rust (cargo/rustfmt/clippy), git, gh, acli, jq, la CLI de docker, iptables, claude, cursor-agent, codex, opencode, openvscode-server, mise y las librerías de Playwright/Chromium.
• Valores por defecto de provisioning (el admin puede fijar/reemplazar/desactivar): herramientas de un solo binario como las CLIs de Figma y Lokalise.
• Eliminadas (gestiónalas vía imagen a medida): herramientas como AWS CLI v2 que solo una minoría de despliegues necesita.

Troubleshooting de provisioning

• “Mi comando no corre al reiniciar.” La puerta SHA omite las listas sin cambios — edita algo (incluso un comentario) para cambiar el hash, o rm /opt/maestro-tools/.provisioning-sha y reinicia.
• “Los workers no ven mi herramienta.” Comprueba que aterrizó en el volumen (docker exec maestro-core-maestro-1 ls /opt/maestro-tools/bin/) y que /opt/maestro-tools/bin es lo primero en el $PATH del worker. Busca líneas [maestro-provisioning] … WARN en el log de arranque por si hubo fallos de install.

Para más, consulta troubleshooting.