docker-patterns

# Patrones Docker Buenas prácticas de Docker y Docker Compose para desarrollo en contenedores. ## Cuándo Activar - Configurar Docker Compose para desarrollo local - Diseñar arquitecturas de múltiples contenedores - Resolver problemas de networking o volúmenes de contenedores - Revisar Dockerfiles para seguridad y tamaño - Migrar de desarrollo local a flujo de trabajo en contenedores ## Docker Compose para Desarrollo Local ### Stack Estándar de Aplicación Web ```yaml # docker-compose.yml services: app: build: context: . target: dev # Usar etapa dev del Dockerfile multi-stage ports: - "3000:3000" volumes: - .:/app # Bind mount para hot reload - /app/node_modules # Volumen anónimo -- preserva deps del contenedor environment: - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev - REDIS_URL=redis://redis:6379/0 - NODE_ENV=development depends_on: db: condition: service_healthy redis: condition: service_started command: npm run dev db: image: postgres:16-alpine ports: - "5432:5432" environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres POSTGRES_DB: app_dev volumes: - pgdata:/var/lib/postgresql/data - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 5s timeout: 3s retries: 5 redis: image: redis:7-alpine ports: - "6379:6379" volumes: - redisdata:/data mailpit: # Pruebas de email locales image: axllent/mailpit ports: - "8025:8025" # Web UI - "1025:1025" # SMTP volumes: pgdata: redisdata: ``` ### Dockerfile de Desarrollo vs Producción ```dockerfile # Etapa: dependencias FROM node:22-alpine AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci # Etapa: dev (hot reload, herramientas de debug) FROM node:22-alpine AS dev WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . EXPOSE 3000 CMD ["npm", "run", "dev"] # Etapa: build FROM node:22-alpine AS build WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npm run build && npm prune --production # Etapa: producción (imagen mínima) FROM node:22-alpine AS production WORKDIR /app RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001 USER appuser COPY --from=build --chown=appuser:appgroup /app/dist ./dist COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules COPY --from=build --chown=appuser:appgroup /app/package.json ./ ENV NODE_ENV=production EXPOSE 3000 HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1 CMD ["node", "dist/server.js"] ``` ### Archivos de Override ```yaml # docker-compose.override.yml (carga automática, configuración solo para dev) services: app: environment: - DEBUG=app:* - LOG_LEVEL=debug ports: - "9229:9229" # Debugger de Node.js # docker-compose.prod.yml (explícito para producción) services: app: build: target: production restart: always deploy: resources: limits: cpus: "1.0" memory: 512M ``` ```bash # Desarrollo (carga override automáticamente) docker compose up # Producción docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d ``` ## Networking ### Descubrimiento de Servicios Los servicios en la misma red de Compose se resuelven por nombre de servicio: ``` # Desde el contenedor "app": postgres://postgres:postgres@db:5432/app_dev # "db" resuelve al contenedor db redis://redis:6379/0 # "redis" resuelve al contenedor redis ``` ### Redes Personalizadas ```yaml services: frontend: networks: - frontend-net api: networks: - frontend-net - backend-net db: networks: - backend-net # Solo accesible desde api, no desde frontend networks: frontend-net: backend-net: ``` ### Exponer Solo Lo Necesario ```yaml services: db: ports: - "127.0.0.1:5432:5432" # Solo accesible desde el host, no desde la red # Omitir ports completamente en producción -- accesible solo dentro de la red Docker ``` ## Estrategias de Volúmenes ```yaml volumes: # Volumen nombrado: persiste entre reinicios de contenedor, gestionado por Docker pgdata: # Bind mount: mapea directorio del host al contenedor (para desarrollo) # - ./src:/app/src # Volumen anónimo: preserva contenido generado por el contenedor del bind mount override # - /app/node_modules ``` ### Patrones Comunes ```yaml services: app: volumes: - .:/app # Código fuente (bind mount para hot reload) - /app/node_modules # Proteger node_modules del contenedor del host - /app/.next # Proteger caché de build db: volumes: - pgdata:/var/lib/postgresql/data # Datos persistentes - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql # Scripts de init ``` ## Seguridad de Contenedores ### Hardening de Dockerfile ```dockerfile # 1. Usar etiquetas específicas (nunca :latest) FROM node:22.12-alpine3.20 # 2. Ejecutar como usuario no-root RUN addgroup -g 1001 -S app && adduser -S app -u 1001 USER app # 3. Eliminar capabilities (en compose) # 4. Sistema de archivos raíz de solo lectura donde sea posible # 5. Sin secretos en capas de imagen ``` ### Seguridad de Compose ```yaml services: app: security_opt: - no-new-privileges:true read_only: true tmpfs: - /tmp - /app/.cache cap_drop: - ALL cap_add: - NET_BIND_SERVICE # Solo si se vincula a puertos < 1024 ``` ### Gestión de Secretos ```yaml # BIEN: Usar variables de entorno (inyectadas en tiempo de ejecución) services: app: env_file: - .env # Nunca hacer commit de .env a git environment: - API_KEY # Hereda del entorno del host # BIEN: Docker secrets (modo Swarm) secrets: db_password: file: ./secrets/db_password.txt services: db: secrets: - db_password # MAL: Hardcodeado en imagen # ENV API_KEY=sk-proj-xxxxx # NUNCA HACER ESTO ``` ## .dockerignore ``` node_modules .git .env .env.* dist coverage *.log .next .cache docker-compose*.yml Dockerfile* README.md tests/ ``` ## Depuración ### Comandos Comunes ```bash # Ver logs docker compose logs -f app # Seguir logs de app docker compose logs --tail=50 db # Últimas 50 líneas de db # Ejecutar comandos en contenedor en ejecución docker compose exec app sh # Shell en app docker compose exec db psql -U postgres # Conectar a postgres # Inspeccionar docker compose ps # Servicios en ejecución docker compose top # Procesos en cada contenedor docker stats # Uso de recursos # Reconstruir docker compose up --build # Reconstruir imágenes docker compose build --no-cache app # Forzar reconstrucción completa # Limpiar docker compose down # Detener y eliminar contenedores docker compose down -v # También eliminar volúmenes (DESTRUCTIVO) docker system prune # Eliminar imágenes/contenedores no usados ``` ### Depurar Problemas de Red ```bash # Verificar resolución DNS dentro del contenedor docker compose exec app nslookup db # Verificar conectividad docker compose exec app wget -qO- http://api:3000/health # Inspeccionar red docker network ls docker network inspect <project>_default ``` ## Anti-Patrones ``` # MAL: Usar docker compose en producción sin orquestación # Usar Kubernetes, ECS o Docker Swarm para cargas de trabajo de múltiples contenedores en producción # MAL: Almacenar datos en contenedores sin volúmenes # Los contenedores son efímeros -- todos los datos se pierden al reiniciar sin volúmenes # MAL: Ejecutar como root # Siempre crear y usar un usuario no-root # MAL: Usar etiqueta :latest # Fijar a versiones específicas para builds reproducibles # MAL: Un contenedor gigante con todos los servicios # Separar responsabilidades: un proceso por contenedor # MAL: Poner secretos en docker-compose.yml # Usar archivos .env (en .gitignore) o Docker secrets ```