@saulwade/swl-ses 1.0.0

package/habilidades/contenedores-docker/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: contenedores-docker
+description: Docker y containerización. Dockerfiles optimizados con multi-stage builds, docker-compose, volúmenes, networking, health checks, security scanning, build caching, distroless images. Anti-patrones comunes.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para orquestación Kubernetes (Deployments, Services, Helm, HPA) — para Kubernetes cargar `kubernetes-orquestacion`."
+  - "No cargar para infraestructura como código con Terraform o Pulumi — para IaC cargar `terraform-experto`."
+  - "No cargar para CI/CD pipelines (GitHub Actions, GitLab CI, build triggers) — para pipelines cargar `ci-cd-pipelines`."
+  - "No cargar para registros de contenedores en cloud (ECR, GCR, ACR) y sus políticas de acceso — para cloud cargar `cloud-aws`, `azure-cloud` o `gcp-cloud`."
+evolvable: true  # default para skill estandar
+---
+# Docker y Containerización — Producción
+
+## Cuándo NO cargar
+
+- La tarea es orquestación de contenedores con Kubernetes: Deployments, Services, Helm, HPA — cargar `kubernetes-orquestacion`.
+- El trabajo es infraestructura como código con Terraform o Pulumi — cargar `terraform-experto`.
+- La tarea es configurar pipelines CI/CD: GitHub Actions, GitLab CI, build triggers automáticos — cargar `ci-cd-pipelines`.
+- El trabajo es con registros de contenedores en cloud (ECR, GCR, ACR) y sus políticas IAM — cargar `cloud-aws`, `azure-cloud` o `gcp-cloud`.
+
+Docker en producción requiere imágenes seguras, pequeñas y reproducibles.
+Este skill cubre desde Dockerfiles hasta orquestación con Compose.
+
+---
+
+## Reglas Obligatorias
+
+1. **SIEMPRE multi-stage build** — imagen final < 200MB si posible.
+2. **NUNCA correr como root** — definir `USER` no-root en el Dockerfile.
+3. **SIEMPRE `.dockerignore`** — sin él, el contexto incluye `.git`, `.env`, `node_modules`.
+4. **SIEMPRE `HEALTHCHECK`** — el orquestador necesita saber si el contenedor está sano.
+5. **NUNCA secrets en `ARG` o `ENV`** del Dockerfile — son visibles en `docker history`.
+6. **SIEMPRE tag de versión exacta** en producción — NUNCA `latest`.
+7. **`CMD` en forma exec (array)** — `CMD ["ejecutable", "arg"]`, no shell string.
+8. **Copiar dependencias ANTES que código** — maximiza el caché de build.
+9. **Limpiar apt-get en la misma capa de RUN** — `rm -rf /var/lib/apt/lists/*`.
+
+---
+
+## Dockerfile Base — Python API
+
+```dockerfile
+# Etapa 1: Dependencias (caché eficiente)
+FROM python:3.12-slim AS deps
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml uv.lock* requirements*.txt ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Etapa 2: Build
+FROM deps AS builder
+COPY . .
+RUN python -m compileall -q /app
+
+# Etapa 3: Producción (imagen final mínima)
+FROM python:3.12-slim AS production
+
+RUN groupadd --gid 1001 appuser && \
+    useradd --uid 1001 --gid appuser --shell /bin/bash --create-home appuser
+
+WORKDIR /app
+
+COPY --from=builder --chown=appuser:appuser /usr/local/lib/python3.12/site-packages \
+    /usr/local/lib/python3.12/site-packages
+COPY --from=builder --chown=appuser:appuser /app /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 curl \
+    && rm -rf /var/lib/apt/lists/*
+
+USER appuser
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONFAULTHANDLER=1 \
+    PORT=8000
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", \
+     "--workers", "2", "--log-level", "info"]
+```
+
+---
+
+## Anti-patrones Comunes
+
+| Anti-patrón | Consecuencia | Corrección |
+|-------------|-------------|------------|
+| `FROM python:3.12` (imagen completa) | Imagen 1GB+ innecesaria | `python:3.12-slim` o `distroless` |
+| Correr como `root` en contenedor | Escalación de privilegios | `USER 1001` en Dockerfile |
+| `COPY . .` antes de dependencias | Invalidar caché en cada cambio | Copiar deps primero |
+| Sin `.dockerignore` | Contexto enorme, secretos incluidos | `.dockerignore` siempre |
+| `apt-get` sin limpiar | Imagen más grande | Limpiar en misma `RUN` |
+| Secrets en `ARG` o `ENV` | Visibles en `docker history` | Runtime env o secrets |
+| Latest tag en producción | No reproducible | Tag de versión exacta |
+| Sin `HEALTHCHECK` | Orquestador no sabe si está sano | `HEALTHCHECK` siempre |
+| `CMD` como shell string | Signals no llegan al proceso | Forma exec (array) |
+| Múltiples procesos en un contenedor | Viola responsabilidad única | Un proceso por contenedor |
+
+---
+
+## Checklist de Imagen Productiva
+
+- [ ] Multi-stage build — imagen final < 200MB si posible
+- [ ] Usuario no-root definido
+- [ ] Variables sensibles fuera de la imagen
+- [ ] `HEALTHCHECK` definido
+- [ ] `.dockerignore` presente y completo
+- [ ] Dependencias del sistema limpiadas en misma capa de RUN
+- [ ] Tag de versión semántica (no `latest`) en producción
+- [ ] Escaneo de vulnerabilidades en CI/CD
+- [ ] `CMD` en forma exec (array), no shell
+- [ ] `PYTHONUNBUFFERED=1` y `PYTHONDONTWRITEBYTECODE=1` para Python
+
+---
+
+Para ejemplos completos de multi-stage Node.js/Angular, .dockerignore, docker-compose, networking, volúmenes, secrets, security scanning en CI y optimización de build cache, ver [recursos/ejemplos-y-configuraciones.md](recursos/ejemplos-y-configuraciones.md).
+
+## Gotchas / Errores comunes no obvios
+
+**`COPY . .` antes de `RUN pip install` invalida el caché de build en cada cambio de código fuente**: Docker invalida el caché de una capa cuando cambia cualquier archivo copiado — si el código fuente cambia en cada commit, la capa de instalación de dependencias nunca se cachea. Causa: el orden de las instrucciones en el Dockerfile determina la eficiencia del caché. Fix: copiar PRIMERO los archivos de dependencias (`pyproject.toml`, `requirements.txt`, `package.json`) e instalar, luego copiar el código fuente — las dependencias solo se reinstalan cuando sus archivos de definición cambian.
+
+**`CMD ["python", "app.py"]` en lugar de `CMD ["gunicorn", ...]` en producción deja el proceso de Python sin manejo de señales SIGTERM**: cuando Kubernetes envía `SIGTERM` para terminar gracefully un pod, el proceso debe recibirlo y terminar limpiamente. Python corriendo con `python app.py` puede no propagar la señal correctamente si usa threads. Causa: `CMD` en forma exec pasa la señal al proceso directamente, pero si el proceso no maneja `SIGTERM`, el contenedor espera el `SIGKILL` tras el `terminationGracePeriodSeconds`. Fix: usar un servidor WSGI/ASGI (`gunicorn`, `uvicorn`) que maneja `SIGTERM` gracefully, o implementar el signal handler en la aplicación.
+
+**Secrets pasados como `ARG` en el Dockerfile son visibles en `docker history` aunque se eliminen en una capa posterior**: `ARG SECRET_KEY` seguido de `RUN rm -f /app/.env` no elimina el valor del ARG del historial de la imagen — `docker history --no-trunc imagen` muestra los valores de los ARG. Causa: `docker history` registra los comandos de cada capa, incluyendo los valores de ARG usados. Fix: NUNCA pasar secretos como `ARG` o `ENV` en el Dockerfile; para secrets en build-time usar `--secret` de Docker BuildKit: `RUN --mount=type=secret,id=api_key cat /run/secrets/api_key`.
+
+**`.dockerignore` mal configurado incluye archivos `.env` o `node_modules` en el contexto de build, ralentizando el daemon y exponiendo secretos**: si `.dockerignore` no existe o no excluye `node_modules`, el contexto de build puede ser de cientos de MB — todo se transfiere al daemon antes del build. Causa: el contexto de build incluye todo el directorio por defecto. Fix: crear `.dockerignore` con al menos `.git`, `node_modules`, `__pycache__`, `.env*`, `*.pyc`, `dist`, `build`, y verificar el tamaño del contexto con `docker build` mirando la línea "Sending build context to Docker daemon X.XX MB".

package/habilidades/contenedores-docker/recursos/dockerfile-template.dockerfile

@@ -0,0 +1,160 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Dockerfile multi-stage para aplicaciones Python (FastAPI / Django)
+# Optimizado para producción: imagen pequeña, sin root, sin caché innecesario.
+#
+# USO:
+#   docker build -t mi-app:1.0.0 .
+#   docker build --target deps -t mi-app:deps .   # solo la etapa de dependencias
+#
+# VARIABLES DE BUILD (--build-arg):
+#   PYTHON_VERSION   Versión de Python (default: 3.12)
+#   APP_PORT         Puerto expuesto (default: 8000)
+#   APP_USER_UID     UID del usuario sin privilegios (default: 1001)
+#
+# INSTRUCCIÓN: Reemplazar todos los valores entre [corchetes] con los reales.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+ARG PYTHON_VERSION=3.12
+ARG APP_PORT=8000
+ARG APP_USER_UID=1001
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Etapa 1: deps — instalar dependencias Python (máximo cache hit en rebuilds)
+# ─────────────────────────────────────────────────────────────────────────────
+FROM python:${PYTHON_VERSION}-slim AS deps
+
+# Dependencias del sistema mínimas (solo las necesarias para compilar wheels)
+# INSTRUCCIÓN: ajustar según las librerías Python que uses
+#   psycopg2  → libpq-dev
+#   Pillow    → libjpeg-dev zlib1g-dev
+#   lxml      → libxml2-dev libxslt-dev
+#   cryptography → libssl-dev
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copiar SOLO los archivos de dependencias primero.
+# Esto permite que Docker reutilice la capa de pip install si el código cambia
+# pero las dependencias no cambian.
+COPY pyproject.toml uv.lock* requirements*.txt ./
+
+# Actualizar pip e instalar dependencias sin caché
+RUN pip install --no-cache-dir --upgrade pip==24.* \
+    && pip install --no-cache-dir -r requirements.txt
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Etapa 2: builder — copiar código y precompilar bytecode
+# ─────────────────────────────────────────────────────────────────────────────
+FROM deps AS builder
+
+# Copiar el código fuente DESPUÉS de instalar dependencias (mejor cache hit)
+COPY . .
+
+# Precompilar .pyc — reduce el tiempo de arranque del contenedor en producción
+# -q suprime output, -b escribe .pyc junto a los .py
+RUN python -m compileall -q /app
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Etapa 3: production — imagen final mínima sin herramientas de build
+# ─────────────────────────────────────────────────────────────────────────────
+FROM python:${PYTHON_VERSION}-slim AS production
+
+ARG APP_PORT
+ARG APP_USER_UID
+
+# Instalar SOLO dependencias de runtime (sin herramientas de compilación)
+# INSTRUCCIÓN: ajustar según las librerías que uses en runtime
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        libpq5 \
+        curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# ── Seguridad: usuario sin privilegios ────────────────────────────────────────
+# NUNCA correr como root en producción
+RUN groupadd --gid ${APP_USER_UID} appuser \
+    && useradd \
+        --uid ${APP_USER_UID} \
+        --gid ${APP_USER_UID} \
+        --no-create-home \
+        --shell /sbin/nologin \
+        appuser
+
+WORKDIR /app
+
+# Copiar dependencias instaladas y código compilado desde las etapas anteriores
+COPY --from=builder /usr/local/lib/python*/site-packages /usr/local/lib/python3.12/site-packages/
+COPY --from=builder /usr/local/bin /usr/local/bin/
+COPY --from=builder /app /app
+
+# Establecer permisos correctos ANTES de cambiar de usuario
+RUN chown -R appuser:appuser /app
+
+# Cambiar al usuario sin privilegios
+USER appuser
+
+# ── Variables de entorno de runtime ───────────────────────────────────────────
+# INSTRUCCIÓN: estas son las variables mínimas recomendadas para Python en producción
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONFAULTHANDLER=1 \
+    PYTHONHASHSEED=random \
+    # FastAPI/Uvicorn
+    PORT=${APP_PORT} \
+    # INSTRUCCIÓN: agregar variables de entorno propias de la aplicación
+    # Las variables con valores sensibles deben venir de secrets, NO hardcodeadas aquí
+    APP_ENV=production
+
+EXPOSE ${APP_PORT}
+
+# ── Health check ──────────────────────────────────────────────────────────────
+# INSTRUCCIÓN: reemplazar /health con el endpoint real de health check
+# interval: frecuencia del check
+# timeout: tiempo máximo de respuesta
+# start_period: tiempo antes del primer check (para que la app arranque)
+# retries: intentos fallidos antes de marcar como unhealthy
+HEALTHCHECK \
+    --interval=30s \
+    --timeout=10s \
+    --start-period=15s \
+    --retries=3 \
+    CMD curl -f http://localhost:${APP_PORT}/health || exit 1
+
+# ── Comando de inicio ─────────────────────────────────────────────────────────
+# INSTRUCCIÓN: ajustar según el framework que uses
+#
+# FastAPI con Uvicorn:
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
+#
+# FastAPI con Gunicorn + Uvicorn workers (para producción con múltiples CPUs):
+# CMD ["gunicorn", "app.main:app", "--workers", "4", "--worker-class", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]
+#
+# Django con Gunicorn:
+# CMD ["gunicorn", "[nombre_proyecto].wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# .dockerignore recomendado (crear en la raíz del proyecto):
+# ───────────────────────────────────────────────────────────────────────────────
+# __pycache__/
+# *.pyc
+# *.pyo
+# .pytest_cache/
+# .mypy_cache/
+# .ruff_cache/
+# .git/
+# .gitignore
+# .env
+# .env.*
+# !.env.example
+# tests/
+# docs/
+# *.md
+# docker-compose*.yml
+# Dockerfile*
+# .github/
+# ═══════════════════════════════════════════════════════════════════════════════

package/habilidades/contenedores-docker/recursos/ejemplos-y-configuraciones.md

@@ -0,0 +1,327 @@
+# Docker — Ejemplos y Configuraciones Completas
+
+Referencia extendida de la skill `contenedores-docker`. Contiene Dockerfiles completos,
+docker-compose, networking, volúmenes, security scanning y optimización de caché.
+
+---
+
+## Dockerfile — Node.js + Angular (Multi-stage)
+
+```dockerfile
+# Etapa 1: Dependencias npm
+FROM node:20-alpine AS npm-deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --only=production
+
+# Etapa 2: Build Angular
+FROM node:20-alpine AS angular-builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build -- --configuration=production --output-path=dist
+
+# Etapa 3: Nginx para servir el SPA
+FROM nginx:1.25-alpine AS production
+
+COPY nginx.conf /etc/nginx/nginx.conf
+COPY --from=angular-builder /app/dist /usr/share/nginx/html
+
+RUN chown -R nginx:nginx /usr/share/nginx/html && \
+    chown -R nginx:nginx /var/cache/nginx && \
+    touch /var/run/nginx.pid && \
+    chown nginx:nginx /var/run/nginx.pid
+
+USER nginx
+
+EXPOSE 80
+
+HEALTHCHECK --interval=30s --timeout=5s \
+    CMD curl -f http://localhost/health || exit 1
+```
+
+---
+
+## .dockerignore completo
+
+```dockerignore
+# Control de versiones
+.git
+.gitignore
+
+# Dependencias locales
+node_modules
+__pycache__
+*.pyc
+*.pyo
+.venv
+venv
+env
+
+# Tests y documentacion
+tests/
+docs/
+*.md
+!README.md
+
+# Archivos de configuracion de desarrollo
+.env
+.env.*
+*.env
+docker-compose.override.yml
+.editorconfig
+.eslintrc*
+.prettierrc*
+
+# IDE
+.vscode
+.idea
+*.swp
+
+# Build outputs locales
+dist/
+build/
+.angular/
+coverage/
+.pytest_cache/
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+Dockerfile*
+docker-compose*.yml
+```
+
+---
+
+## docker-compose — Entorno de Desarrollo Completo
+
+```yaml
+version: '3.9'
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: deps
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+    volumes:
+      - .:/app
+      - /app/.venv
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/appdb
+      - REDIS_URL=redis://redis:6379/0
+      - DEBUG=true
+    env_file:
+      - .env.local
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  db:
+    image: postgres:15-alpine
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+    environment:
+      POSTGRES_DB: appdb
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d appdb"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    networks:
+      - app-network
+
+  redis:
+    image: redis:7-alpine
+    command: redis-server --appendonly yes --requirepass "${REDIS_PASSWORD:-dev_password}"
+    volumes:
+      - redis_data:/data
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+    networks:
+      - app-network
+
+  nginx:
+    image: nginx:1.25-alpine
+    volumes:
+      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./nginx/ssl:/etc/nginx/ssl:ro
+    ports:
+      - "80:80"
+      - "443:443"
+    depends_on:
+      - api
+    networks:
+      - app-network
+
+volumes:
+  postgres_data:
+    driver: local
+  redis_data:
+    driver: local
+
+networks:
+  app-network:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.20.0.0/16
+```
+
+---
+
+## Networking en Docker
+
+```bash
+# Crear red personalizada
+docker network create --driver bridge --subnet 172.21.0.0/16 mi-red
+
+# Inspeccionar red
+docker network inspect mi-red
+
+# MAL: usar --link (obsoleto)
+docker run --link db:database api
+
+# BIEN: red compartida
+docker run --network mi-red --name api mi-imagen-api
+docker run --network mi-red --name db postgres:15
+```
+
+---
+
+## Volúmenes — Persistencia Correcta
+
+```yaml
+# 1. Named volumes (RECOMENDADO para datos de BD)
+volumes:
+  postgres_data:
+
+# 2. Bind mounts (SOLO para desarrollo — hot reload)
+volumes:
+  - ./src:/app/src
+
+# 3. tmpfs (datos efimeros)
+tmpfs:
+  - /tmp
+  - /run
+
+# MAL: montar directorio completo en produccion
+volumes:
+  - .:/app                # Incluye .git, node_modules, .env!
+
+# BIEN: montar solo lo necesario
+volumes:
+  - ./config:/app/config:ro
+  - ./logs:/app/logs
+```
+
+---
+
+## Variables de Entorno y Secrets
+
+```bash
+# MAL: secrets en variables de entorno del Dockerfile
+ENV DATABASE_PASSWORD=supersecreta123
+
+# MAL: pasar secrets en build args
+docker build --build-arg DB_PASS=secreto .
+
+# BIEN: runtime environment variables
+docker run -e DATABASE_URL="postgresql://..." mi-imagen
+
+# BIEN: Docker Secrets (en Swarm)
+docker secret create db_password ./db_password.txt
+
+# BIEN: En docker-compose con .env
+env_file:
+  - .env
+```
+
+---
+
+## Security Scanning — Pipeline de CI
+
+```yaml
+# .github/workflows/security.yml
+name: Security Scan
+
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build imagen
+        run: docker build -t mi-app:${{ github.sha }} .
+
+      - name: Trivy scan
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: mi-app:${{ github.sha }}
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+          severity: 'CRITICAL,HIGH'
+          exit-code: '1'
+
+      - name: Hadolint
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: Dockerfile
+
+      - name: Dockle
+        run: |
+          docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+            goodwithtech/dockle:latest --exit-code 1 mi-app:${{ github.sha }}
+```
+
+---
+
+## Optimización de Build Cache
+
+```dockerfile
+# ORDEN CRITICO para maximizar cache:
+# 1. Lo que cambia MENOS al inicio
+# 2. Lo que cambia MAS al final
+
+# MAL: copiar todo antes de instalar dependencias
+COPY . .
+RUN pip install -r requirements.txt
+
+# BIEN: dependencias antes que codigo
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+
+# BuildKit — cache de montaje
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install -r requirements.txt
+
+RUN --mount=type=cache,target=/var/cache/apt \
+    apt-get update && apt-get install -y libpq-dev
+```