swl-ses 3.3.2

package/habilidades/contenedores-docker/SKILL.md

@@ -0,0 +1,453 @@
+---
+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.
+---
+
+# Docker y Containerización — Producción
+
+Docker en producción requiere imágenes seguras, pequeñas y reproducibles.
+Este skill cubre desde Dockerfiles hasta orquestación con Compose.
+
+---
+
+## 1. Dockerfile Base — Python API
+
+```dockerfile
+# =====================================================================
+# Etapa 1: Dependencias (caché eficiente)
+# =====================================================================
+FROM python:3.12-slim AS deps
+
+# Instalar dependencias del sistema (solo las necesarias)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*   # SIEMPRE limpiar en misma capa
+
+WORKDIR /app
+
+# Copiar SOLO archivos de dependencias primero (mejor caché)
+COPY pyproject.toml uv.lock* requirements*.txt ./
+
+# pip sin caché ni warnings innecesarios
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# =====================================================================
+# Etapa 2: Build (compilar assets si los hay)
+# =====================================================================
+FROM deps AS builder
+
+COPY . .
+RUN python -m compileall -q /app   # Precompilar .pyc
+
+# =====================================================================
+# Etapa 3: Producción (imagen final mínima)
+# =====================================================================
+FROM python:3.12-slim AS production
+
+# Seguridad: NO correr como root
+RUN groupadd --gid 1001 appuser && \
+    useradd --uid 1001 --gid appuser --shell /bin/bash --create-home appuser
+
+WORKDIR /app
+
+# Copiar solo lo necesario desde la etapa de build
+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
+
+# Instalar dependencias de sistema mínimas para runtime
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+USER appuser
+
+# Variables de entorno para Python en contenedor
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONFAULTHANDLER=1 \
+    PORT=8000
+
+EXPOSE 8000
+
+# Health check integrado en la imagen
+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"]
+```
+
+---
+
+## 2. Multi-stage Build — Node.js + Angular
+
+```dockerfile
+# Etapa 1: Dependencias npm (caché por package-lock.json)
+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                              # Incluye devDependencies para build
+COPY . .
+RUN npm run build -- --configuration=production --output-path=dist
+
+# Etapa 3: Nginx para servir el SPA
+FROM nginx:1.25-alpine AS production
+
+# Configuración de Nginx optimizada
+COPY nginx.conf /etc/nginx/nginx.conf
+COPY --from=angular-builder /app/dist /usr/share/nginx/html
+
+# Usuario no-root para nginx
+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
+```
+
+---
+
+## 3. .dockerignore — Crítico para el Contexto de Build
+
+```dockerignore
+# Control de versiones
+.git
+.gitignore
+
+# Dependencias locales (nunca copiar node_modules o venv)
+node_modules
+__pycache__
+*.pyc
+*.pyo
+.venv
+venv
+env
+
+# Tests y documentación
+tests/
+docs/
+*.md
+!README.md
+
+# Archivos de configuración 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
+```
+
+---
+
+## 4. docker-compose — Entorno de Desarrollo Completo
+
+```yaml
+# docker-compose.yml
+version: '3.9'
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: deps              # Etapa de desarrollo (no producción)
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+    volumes:
+      - .:/app                  # Hot reload en desarrollo
+      - /app/.venv              # Excluir venv del host
+    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              # Variables de entorno sensibles
+    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"             # Solo exponer en desarrollo
+    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
+```
+
+---
+
+## 5. Networking en Docker
+
+```bash
+# Crear red personalizada (mejores nombres DNS internos)
+docker network create --driver bridge --subnet 172.21.0.0/16 mi-red
+
+# Inspeccionar red
+docker network inspect mi-red
+
+# Contenedores en la misma red se comunican por nombre
+# api puede conectarse a "db" por nombre → postgresql://db:5432/appdb
+
+# 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
+```
+
+---
+
+## 6. Volúmenes — Persistencia Correcta
+
+```yaml
+# Tipos de volúmenes y cuándo usar cada uno
+
+# 1. Named volumes (RECOMENDADO para datos de BD)
+volumes:
+  postgres_data:          # Docker administra la ubicación
+
+# 2. Bind mounts (SOLO para desarrollo — hot reload)
+volumes:
+  - ./src:/app/src        # Código fuente del host → contenedor
+
+# 3. tmpfs (datos efímeros — sesiones, caché temporal)
+tmpfs:
+  - /tmp
+  - /run
+
+# MAL: montar directorio completo en producción
+volumes:
+  - .:/app                # ¡Incluye .git, node_modules, .env!
+
+# BIEN: montar solo lo necesario
+volumes:
+  - ./config:/app/config:ro   # :ro = solo lectura
+  - ./logs:/app/logs          # Solo el directorio de logs
+```
+
+---
+
+## 7. Variables de Entorno y Secrets
+
+```bash
+# MAL: secrets en variables de entorno del Dockerfile
+ENV DATABASE_PASSWORD=supersecreta123
+
+# MAL: pasar secrets en build args (aparecen en capas)
+docker build --build-arg DB_PASS=secreto .
+
+# BIEN: runtime environment variables (nunca en imagen)
+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 (nunca commitar .env real)
+# .env.example (sí commitear)
+DATABASE_URL=postgresql://usuario:password@localhost:5432/db
+SECRET_KEY=cambiar-en-produccion
+
+# docker-compose.yml
+env_file:
+  - .env
+```
+
+---
+
+## 8. 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 }} .
+
+      # Trivy — escaneo de vulnerabilidades en imagen
+      - 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'   # Fallar el pipeline si hay vulns críticas
+
+      # Hadolint — linter de Dockerfile
+      - name: Hadolint
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: Dockerfile
+
+      # Dockle — mejores prácticas de imagen
+      - 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 }}
+```
+
+---
+
+## 9. Optimización de Build Cache
+
+```dockerfile
+# ORDEN CRÍTICO para maximizar caché:
+# 1. Lo que cambia MENOS al inicio
+# 2. Lo que cambia MÁS al final
+
+# MAL: copiar todo antes de instalar dependencias
+COPY . .
+RUN pip install -r requirements.txt   # Invalida caché con CUALQUIER cambio
+
+# BIEN: dependencias antes que código
+COPY requirements.txt .
+RUN pip install -r requirements.txt   # Se cachea hasta que requirements.txt cambie
+COPY . .                              # Aquí va el código que cambia frecuentemente
+
+# BuildKit — caché de montaje (pip, npm, apt)
+# 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
+```
+
+---
+
+## 10. 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 `rm -rf /var/lib/apt/lists/*` | 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, puede romper | Tag de versión exacta |
+| Sin `HEALTHCHECK` | Orquestador no sabe si está sano | `HEALTHCHECK` siempre |
+| `CMD` como shell string | Signals no llegan al proceso | `CMD ["ejecutable", "arg"]` forma exec |
+| Múltiples procesos en un contenedor | Viola principio de responsabilidad única | Un proceso por contenedor |
+
+---
+
+## 11. 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

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/
+# ═══════════════════════════════════════════════════════════════════════════════