theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-despliegue/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: patrones-despliegue
+description: Flujos de despliegue, patrones de pipelines CI/CD, contenedores con Docker, health checks, estrategias de rollback y checklists de preparación para producción en aplicaciones web.
+---
+
+# Patrones de despliegue
+
+Flujos de despliegue a producción y buenas prácticas de CI/CD.
+
+## Cuándo activarla
+
+- Al configurar pipelines de CI/CD
+- Al dockerizar una aplicación
+- Al planificar la estrategia de despliegue (blue-green, canary, rolling)
+- Al implementar health checks y probes de readiness
+- Al preparar un lanzamiento a producción
+- Al configurar ajustes específicos por entorno
+
+## Estrategias de despliegue
+
+### Despliegue rolling (por defecto)
+
+Reemplaza las instancias gradualmente — la versión vieja y la nueva corren simultáneamente durante el rollout.
+
+```
+Instancia 1: v1 → v2  (se actualiza primero)
+Instancia 2: v1        (sigue corriendo v1)
+Instancia 3: v1        (sigue corriendo v1)
+
+Instancia 1: v2
+Instancia 2: v1 → v2  (se actualiza segunda)
+Instancia 3: v1
+
+Instancia 1: v2
+Instancia 2: v2
+Instancia 3: v1 → v2  (se actualiza al final)
+```
+
+**Ventajas:** cero downtime, rollout gradual
+**Desventajas:** dos versiones corren a la vez — requiere cambios retrocompatibles
+**Úsalo cuando:** despliegues estándar, cambios retrocompatibles
+
+### Despliegue blue-green
+
+Corre dos entornos idénticos. Cambia el tráfico de forma atómica.
+
+```
+Blue  (v1) ← tráfico
+Green (v2)   ocioso, corriendo la versión nueva
+
+# Tras la verificación:
+Blue  (v1)   ocioso (pasa a ser respaldo)
+Green (v2) ← tráfico
+```
+
+**Ventajas:** rollback instantáneo (vuelves a blue), corte limpio
+**Desventajas:** requiere 2x de infraestructura durante el despliegue
+**Úsalo cuando:** servicios críticos, tolerancia cero a incidencias
+
+### Despliegue canary
+
+Dirige primero un pequeño porcentaje del tráfico a la versión nueva.
+
+```
+v1: 95% del tráfico
+v2:  5% del tráfico  (canary)
+
+# Si las métricas se ven bien:
+v1: 50% del tráfico
+v2: 50% del tráfico
+
+# Final:
+v2: 100% del tráfico
+```
+
+**Ventajas:** detecta problemas con tráfico real antes del rollout completo
+**Desventajas:** requiere infraestructura de partición de tráfico y monitoreo
+**Úsalo cuando:** servicios de alto tráfico, cambios riesgosos, feature flags
+
+## Docker
+
+### Dockerfile multietapa (Node.js)
+
+```dockerfile
+# Etapa 1: instalar dependencias
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+# Etapa 2: build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+RUN npm prune --production
+
+# Etapa 3: imagen de producción
+FROM node:22-alpine AS runner
+WORKDIR /app
+
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
+USER appuser
+
+COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+COPY --from=builder --chown=appuser:appgroup /app/package.json ./
+
+ENV NODE_ENV=production
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/server.js"]
+```
+
+### Dockerfile multietapa (Go)
+
+```dockerfile
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server
+
+FROM alpine:3.19 AS runner
+RUN apk --no-cache add ca-certificates
+RUN adduser -D -u 1001 appuser
+USER appuser
+
+COPY --from=builder /server /server
+
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
+CMD ["/server"]
+```
+
+### Dockerfile multietapa (Python/Django)
+
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --no-cache-dir uv
+COPY requirements.txt .
+RUN uv pip install --system --no-cache -r requirements.txt
+
+FROM python:3.12-slim AS runner
+WORKDIR /app
+
+RUN useradd -r -u 1001 appuser
+USER appuser
+
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+COPY . .
+
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1
+CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]
+```
+
+### Buenas prácticas de Docker
+
+```
+# Prácticas BUENAS
+- Usa tags de versión específicos (node:22-alpine, no node:latest)
+- Builds multietapa para minimizar el tamaño de la imagen
+- Corre como usuario no-root
+- Copia primero los archivos de dependencias (caché de capas)
+- Usa .dockerignore para excluir node_modules, .git, tests
+- Agrega la instrucción HEALTHCHECK
+- Define límites de recursos en docker-compose o k8s
+
+# Prácticas MALAS
+- Correr como root
+- Usar tags :latest
+- Copiar el repo entero en una sola capa COPY
+- Instalar dependencias de dev en la imagen de producción
+- Guardar secretos en la imagen (usa variables de entorno o un gestor de secretos)
+```
+
+## Pipeline de CI/CD
+
+### GitHub Actions (pipeline estándar)
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test -- --coverage
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage
+          path: coverage/
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v5
+        with:
+          push: true
+          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment: production
+    steps:
+      - name: Deploy a producción
+        run: |
+          # Comando de despliegue específico de la plataforma
+          # Railway: railway up
+          # Vercel: vercel --prod
+          # K8s: kubectl set image deployment/app app=ghcr.io/${{ github.repository }}:${{ github.sha }}
+          echo "Desplegando ${{ github.sha }}"
+```
+
+### Etapas del pipeline
+
+```
+PR abierto:
+  lint → typecheck → tests unitarios → tests de integración → deploy de preview
+
+Merge a main:
+  lint → typecheck → tests unitarios → tests de integración → build de imagen → deploy a staging → smoke tests → deploy a producción
+```
+
+## Health checks
+
+### Endpoint de health check
+
+```typescript
+// Health check simple
+app.get("/health", (req, res) => {
+  res.status(200).json({ status: "ok" });
+});
+
+// Health check detallado (para monitoreo interno)
+app.get("/health/detailed", async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    externalApi: await checkExternalApi(),
+  };
+
+  const allHealthy = Object.values(checks).every(c => c.status === "ok");
+
+  res.status(allHealthy ? 200 : 503).json({
+    status: allHealthy ? "ok" : "degraded",
+    timestamp: new Date().toISOString(),
+    version: process.env.APP_VERSION || "unknown",
+    uptime: process.uptime(),
+    checks,
+  });
+});
+
+async function checkDatabase(): Promise<HealthCheck> {
+  try {
+    await db.query("SELECT 1");
+    return { status: "ok", latency_ms: 2 };
+  } catch (err) {
+    return { status: "error", message: "Base de datos inaccesible" };
+  }
+}
+```
+
+### Probes de Kubernetes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 10
+  periodSeconds: 30
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  failureThreshold: 2
+
+startupProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 0
+  periodSeconds: 5
+  failureThreshold: 30    # 30 * 5s = 150s de arranque máximo
+```
+
+## Configuración de entornos
+
+### Patrón Twelve-Factor App
+
+```bash
+# Toda la configuración por variables de entorno — nunca en el código
+DATABASE_URL=postgres://user:pass@host:5432/db
+REDIS_URL=redis://host:6379/0
+API_KEY=${API_KEY}           # inyectada por el gestor de secretos
+LOG_LEVEL=info
+PORT=3000
+
+# Comportamiento específico por entorno
+NODE_ENV=production          # o staging, development
+APP_ENV=production           # entorno explícito de la app
+```
+
+### Validación de configuración
+
+```typescript
+import { z } from "zod";
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "staging", "production"]),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+
+// Validar al arrancar — falla rápido si la configuración está mal
+export const env = envSchema.parse(process.env);
+```
+
+## Estrategia de rollback
+
+### Rollback instantáneo
+
+```bash
+# Docker/Kubernetes: apuntar a la imagen anterior
+kubectl rollout undo deployment/app
+
+# Vercel: promover el despliegue anterior
+vercel rollback
+
+# Railway: redesplegar el commit anterior
+railway up --commit <sha-anterior>
+
+# Base de datos: revertir la migración (si es reversible)
+npx prisma migrate resolve --rolled-back <nombre-de-migracion>
+```
+
+### Checklist de rollback
+
+- [ ] La imagen/artefacto anterior está disponible y etiquetada
+- [ ] Las migraciones de BD son retrocompatibles (sin cambios destructivos)
+- [ ] Los feature flags pueden desactivar funcionalidades nuevas sin deploy
+- [ ] Alertas de monitoreo configuradas para picos en la tasa de errores
+- [ ] Rollback probado en staging antes del lanzamiento a producción
+
+## Checklist de preparación para producción
+
+Antes de cualquier despliegue a producción:
+
+### Aplicación
+- [ ] Todos los tests pasan (unitarios, integración, E2E)
+- [ ] Sin secretos hardcodeados en el código ni en archivos de configuración
+- [ ] El manejo de errores cubre todos los casos límite
+- [ ] Los logs son estructurados (JSON) y no contienen PII
+- [ ] El endpoint de health check devuelve un estado con significado
+
+### Infraestructura
+- [ ] La imagen Docker se construye de forma reproducible (versiones fijadas)
+- [ ] Variables de entorno documentadas y validadas al arranque
+- [ ] Límites de recursos definidos (CPU, memoria)
+- [ ] Escalado horizontal configurado (mín/máx de instancias)
+- [ ] SSL/TLS habilitado en todos los endpoints
+
+### Monitoreo
+- [ ] Métricas de la aplicación exportadas (tasa de peticiones, latencia, errores)
+- [ ] Alertas configuradas para tasa de errores > umbral
+- [ ] Agregación de logs configurada (logs estructurados, buscables)
+- [ ] Monitoreo de uptime sobre el endpoint de salud
+
+### Seguridad
+- [ ] Dependencias escaneadas en busca de CVEs
+- [ ] CORS configurado solo para los orígenes permitidos
+- [ ] Rate limiting habilitado en los endpoints públicos
+- [ ] Autenticación y autorización verificadas
+- [ ] Cabeceras de seguridad configuradas (CSP, HSTS, X-Frame-Options)
+
+### Operaciones
+- [ ] Plan de rollback documentado y probado
+- [ ] Migración de BD probada contra datos de tamaño de producción
+- [ ] Runbook para los escenarios de fallo comunes
+- [ ] Rotación de guardia y ruta de escalamiento definidas