Contenedores y NGINX

Empaqueta un proyecto en una imagen reproducible y lo pone detrás de NGINX.

Avisa si hay versión nueva

Al empezar a trabajar con esta skill, comprueba una vez si hay una versión más reciente:

npm view skills-igb version

Compárala con la instalada: claude plugin list si vino como plugin, o mira ~/.claude/skills/ si se instaló con npm.

• Si hay una más nueva, dilo antes de empezar y ofrece actualizar: "hay una versión más reciente, ¿la actualizo antes de seguir?". No la instales por tu cuenta — es su máquina.
• Si el usuario acepta, actualiza y después confirma en voz alta qué versión quedó instalada y recuérdale que Claude Code necesita reiniciarse para cargarla. Una actualización silenciosa deja a la gente creyendo que usa algo que todavía no usa.
• Si no hay red o el comando falla, no te bloquees: dilo en una línea y sigue con la versión que haya.

Comandos de actualización, según cómo se instaló:

npx skills-igb                                    # instalado por npm
claude plugin marketplace update skills-igb && \
  claude plugin update skills-igb@skills-igb      # instalado como plugin

Una cosa cada vez

Da un comando, espera el resultado, interprétalo, y solo entonces da el siguiente. No entregues una lista de cinco pasos para que se ejecuten de golpe: cada resultado cambia cuál es el paso siguiente, y una tanda entera obliga a la otra persona a decidir por su cuenta qué hacer con cada salida.

Tres reglas que lo hacen funcionar:

• Nunca entregues un comando con un marcador sin rellenar. Si necesitas un dato que aún no tienes —un nombre de servicio, un identificador, una ruta—, ese dato es el siguiente paso, no un <hueco> que la otra persona tenga que adivinar. Un comando que falla porque no se sustituyó un marcador es tiempo perdido y confianza perdida.
• Di qué esperas ver antes de que lo ejecute, y qué significaría cada resultado posible. Así la salida no es un jeroglífico.
• Interpreta el resultado en voz alta antes de continuar: qué acabas de aprender y qué descarta. Si el resultado no es concluyente, dilo en vez de seguir como si lo fuera.

Esto vale doblemente al diagnosticar algo que ya está en producción, donde un paso dado a ciegas puede romper el servicio.

Antes de empezar: comprobar el terreno

command -v docker || echo "docker NO instalado"
command -v docker compose || docker-compose version 2>/dev/null

En esta máquina (WSL) no hay Docker instalado. Eso no impide escribir los ficheros — un Dockerfile es texto — pero sí impide verificar que la imagen construye. Si no está instalado:

1. Dilo de entrada, sin rodeos.
2. Escribe igualmente los ficheros si el usuario los quiere para el repo o para CI.
3. Marca explícitamente que no se ha verificado el build. Nunca digas "listo" sobre una imagen que no construiste.
4. Ofrece instalar Docker Desktop con integración WSL2, o construir en CI, y deja que el usuario elija.

Adapta el nivel a quien tienes delante

Si el CLAUDE.md del proyecto dice con quién trabajas y su perfil, respétalo. Si no lo sabes y la conversación no lo deja claro, pregúntalo antes de empezar: ¿te explico el porqué de cada paso, o voy al grano?

• Con quien no programa: nada de jerga sin traducir, tú tomas las decisiones técnicas y pides visto bueno, y dices qué vas a hacer antes y qué pasó después. Los errores son normales y se arreglan — que nunca se quede pensando que rompió algo.
• Con quien desarrolla: al grano, sin explicar lo básico, y discutiendo las decisiones de igual a igual.

Lo que no cambia con el perfil son las comprobaciones de seguridad ni las advertencias sobre lo que no has podido verificar. Esas van siempre, y en el idioma de la consecuencia real.

Decidir la forma de la imagen

Pregunta qué se está contenerizando, porque cambia todo:

Lee la plantilla correspondiente en references/plantillas.md.

Reglas que no se negocian

• Multi-stage siempre que haya paso de build. Una imagen de SPA que arrastra node_modules pesa 10× lo necesario.
• .dockerignore obligatorio, y lo primero que escribes. Sin él, node_modules y .git se copian al contexto de build y todo se vuelve lento. Mínimo: node_modules, dist, .git, .env, *.log.
• Nunca un secreto en el Dockerfile. Ni ENV JWT_SECRET=..., ni un .env copiado con COPY. Los secretos entran en tiempo de ejecución (--env-file, variables del orquestador). Un secreto en una capa queda en la imagen para siempre, aunque lo borres después.
• Usuario no-root en la imagen final (USER node o un adduser propio).
• Versiones fijadas: node:22-alpine, no node:latest. Una imagen que cambia sola no es reproducible.
• Healthcheck en todo servicio de larga vida, para que el orquestador sepa si está vivo.
• Orden de capas por frecuencia de cambio: primero COPY package*.json + npm ci, después COPY . .. Al revés invalidas la caché en cada commit.

NGINX

Dos papeles distintos, no los confundas:

Servidor de SPA — el fallback a index.html es imprescindible: sin él, recargar en una ruta del router devuelve 404.

Reverse proxy — delante de una o varias APIs: TLS, cabeceras X-Forwarded-*, límites de tamaño y de tasa.

Ambas configuraciones están en references/nginx.md. Puntos que se olvidan siempre:

• try_files $uri $uri/ /index.html; en la SPA.
• proxy_set_header Host y X-Forwarded-For / X-Forwarded-Proto, o la app verá la IP del proxy y generará URLs http:// detrás de TLS.
• client_max_body_size si se suben ficheros — el defecto de 1 MB corta subidas sin explicación clara.
• gzip activado para texto; los assets con hash en el nombre, con Cache-Control largo; index.html nunca cacheado.

Verificar

Si Docker está disponible, no cierres sin ejecutar:

docker build -t <nombre>:test .
docker run --rm -p 8080:80 --env-file .env <nombre>:test
curl -fsS localhost:8080 >/dev/null && echo "responde"
docker images <nombre>:test --format '{{.Size}}'   # ¿tamaño razonable?

Una SPA servida por NGINX debería rondar decenas de MB. Si pasa de 300 MB, el multi-stage está mal y hay que revisarlo antes de dar por bueno el trabajo.

Si Docker no está, di exactamente qué quedó sin verificar.

Límites

• No publica imágenes en ningún registro ni despliega a producción sin petición explícita.
• No instala Docker por su cuenta.
• No genera certificados TLS: para producción, Let's Encrypt vía certbot o el TLS del proveedor.