Saltar a contenido

Regla 08: Stack Tecnológico Recomendado

Premisa: Premisa

Todo proyecto generado con este estándar debe usar un stack tecnológico predefinido para eliminar ambigüedad de versiones, herramientas y runtimes. Esto garantiza que los agentes de IA generen proyectos consistentes y que los builds sean reproducibles en cualquier entorno.

tags: [obligatorio]

Estructura: Estructura

Matriz del stack recomendado

Componente Recomendado Fallback / Alternativa Nota
Documentación Markdown + MermaidJS — Diagramas como código, versionables en Git
Sitio MkDocs (con MkDocs Material) — mkdocs build + GitHub Pages
Java Temurin 25 LTS (JDK) — Build tool: maven o gradle
Node.js Última versión LTS — Gestores: npm, pnpm (preferido)
Python 3.12 o superior — Gestor de dependencias: uv (preferido), poetry
Runtime de contenedores Podman Docker (con warning) Detección automática; sobreescribible con CONTAINER_RUNTIME
Imagen base Alpine (latest estable) Debian-slim (si Alpine no es viable) Imágenes etiquetadas por hash, no por :latest
Definición de imagen Containerfile (o Containerfile.ci) — Nunca Dockerfile. podman build -f Containerfile / docker build -f Containerfile
Cross-compilación --platform linux/amd64 (build en imagen) + QEMU (binfmt) como fallback — Compilar para otra arquitectura usando make build-cross y cross.sh (regla 06)

Herramientas de soporte

helpers/shell/container.sh   →  resuelve podman > docker, construye con Containerfile
helpers/mk/container.mk      →  targets runtime, image, ci
helpers/shell/java.sh        →  build/test/serve con Java
helpers/shell/javascript.sh  →  build/test/serve con Node
helpers/shell/python.sh      →  build/test/serve con Python
helpers/shell/rust.sh        →  build/test/serve con Rust
helpers/shell/docs.sh        →  docs build/serve
helpers/shell/lint.sh        →  lint multi-lenguaje
helpers/shell/format.sh      →  format multi-lenguaje

tags: [opcional]

Nombre Sugerido: Nombres Sugeridos

  • Containerfile o Containerfile.ci para imágenes de CI (nunca Dockerfile).
  • Imágenes base: alpine:3.20, debian:bookworm-slim (con hash).
  • Variables de entorno: CONTAINER_RUNTIME (podman|docker), CI_IMAGE, CI_CONTAINERFILE.
  • Java: JAVA_HOME apuntando a Temurin (gestor de JDK: sdkman o instalación directa).
  • Python: entorno gestionado con uv + pyproject.toml.
  • Node: .nvmrc para fijar la versión LTS.

tags: [opcional]

Comando: Comandos

Verificación del toolchain

java -version          # Temurin 25 LTS
node --version         # LTS
python3 --version      # 3.12+
podman --version       # O docker --version

Build de imagen con Containerfile

podman build -f Containerfile.ci -t mi-proyecto-ci:local .
make image                     # Delegación vía container.mk

CI local con el stack

make image LANG=java BUILD_TOOL=maven
make ci    LANG=java BUILD_TOOL=maven

Si solo hay Docker (warning)

make runtime                   # Detecta docker
make image                     # docker build -f Containerfile.ci ...

El helper container.sh emite un warning: Docker detectado. Podman es la opción recomendada.

tags: [opcional]

Ejemplo: Ejemplos

Diagrama de arquitectura del stack (MermaidJS)

graph TD
    A[Documentación] --> M[Markdown]
    A --> MJ[MermaidJS]
    A --> MK[MkDocs]
    B[Java] --> T[Temurin 25 LTS]
    B --> MV[maven]
    C[Node.js] --> LTS[LTS]
    C --> PN[pnpm]
    D[Python] --> PY[3.12+]
    D --> UV[uv]
    E[Contenedores] --> PD[Podman → Docker]
    E --> AL[Alpine → Debian-slim]
    E --> CF[Containerfile]

Containerfile base Alpine multi-stage

# Containerfile.ci — imagen de CI con toolchain multi-lenguaje
FROM alpine:3.20@sha256:...

RUN apk add --no-cache bash curl git

# Java (Temurin)
# RUN apk add --no-cache openjdk25

# Node.js LTS
# RUN apk add --no-cache nodejs npm

# Python 3.12+
# RUN apk add --no-cache python3 py3-pip

WORKDIR /workspace
ENTRYPOINT ["/bin/bash", "-lc"]

make runtime con detección + warning

$ make runtime
Container runtime: podman

$ make runtime CONTAINER_RUNTIME=docker
WARNING: Docker detectado. Podman es la opción recomendada según la regla 08-stack.
Container runtime: docker

tags: [obligatorio]

Restriccion: Restricciones

  • No usar Dockerfile como nombre de archivo. Usar Containerfile o Containerfile.ci.
  • No usar Docker si podman está disponible — el helper de contenedores lo detecta automáticamente y emite un warning si elige Docker.
  • No usar imágenes base sin etiquetar (:latest). Fijar versión y preferir Alpine; si no, Debian-slim.
  • No usar versiones no-LTS de Java. Siempre Temurin LTS.
  • No usar versiones non-LTS de Node.js en proyectos de API REST.
  • No documentar con formatos no versionables (Google Docs, wikis externas, Confluence). Los diagramas deben ser MermaidJS embebidos en Markdown.
  • No mezclar sistemas de construcción de documentación — MkDocs es el estándar único.
  • No usar Python < 3.12 en nuevos proyectos consumidores.

tags: [obligatorio]

Referencia: Referencias

tags: [obligatorio]

Plantilla: Plantilla

tags: [opcional]