Docker Compose con Claude Code

Construyendo un entorno de desarrollo reproducible con Docker Compose

Docker Compose es una herramienta para definir y gestionar multiples contenedores, que optimiza significativamente la construccion de entornos de desarrollo. Claude Code soporta de forma fluida desde el diseno de la configuracion de servicios hasta la optimizacion de Dockerfiles e infraestructura.

Configuracion del entorno de desarrollo full-stack

Pidamos a Claude Code que configure la estructura completa del proyecto.

> Construye un entorno de desarrollo con Next.js + PostgreSQL + Redis usando Docker Compose.
> Con soporte de hot reload, carga de datos iniciales y health checks.

# docker-compose.yml
version: "3.9"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: npm run dev

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"
      - "8025:8025"

volumes:
  postgres_data:
  redis_data:

Optimizacion del Dockerfile de desarrollo

Dockerfile de desarrollo compatible con hot reload.

# Dockerfile.dev
FROM node:20-alpine

WORKDIR /app

# Copiar solo archivos de paquete primero para aprovechar cache
COPY package.json package-lock.json ./
RUN npm ci

# El codigo fuente se comparte via volume mount
# No se necesita COPY (configurado en docker-compose.yml)

EXPOSE 3000

CMD ["npm", "run", "dev"]

Build multi-stage para produccion

Dockerfile optimizado para despliegue en produccion.

# Dockerfile
# Etapa 1: Instalacion de dependencias
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

# Etapa 2: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Etapa 3: Imagen de produccion
FROM node:20-alpine AS runner
WORKDIR /app

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000

CMD ["node", "server.js"]

Separacion de archivos de configuracion por entorno

Patron para separar configuracion entre desarrollo, testing y produccion.

# docker-compose.override.yml (para desarrollo, carga automatica)
services:
  app:
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - DEBUG=true
      - LOG_LEVEL=debug

  db:
    ports:
      - "5432:5432"

  adminer:
    image: adminer
    ports:
      - "8080:8080"
    depends_on:
      - db

# docker-compose.test.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp_test
      - NODE_ENV=test
    command: npm run test:ci
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp_test
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    tmpfs:
      - /var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10

Simplificando comandos con Makefile

Agrupando los comandos mas usados en un Makefile.

.PHONY: up down build logs db-shell db-migrate db-seed test

up:
	docker compose up -d

down:
	docker compose down

build:
	docker compose build --no-cache

logs:
	docker compose logs -f app

db-shell:
	docker compose exec db psql -U postgres -d myapp

db-migrate:
	docker compose exec app npx prisma migrate dev

db-seed:
	docker compose exec app npx prisma db seed

test:
	docker compose -f docker-compose.yml -f docker-compose.test.yml run --rm app

clean:
	docker compose down -v --remove-orphans

Resumen

Con Docker Compose, todo el equipo puede reproducir facilmente el mismo entorno de desarrollo. Aprovechando Claude Code, puedes construir eficientemente la configuracion de infraestructura, incluyendo configuracion de servicios, optimizacion de Dockerfile y separacion por entornos.

Para una mayor integracion de entornos de desarrollo en contenedores, consulta la guia de configuracion de Dev Container, y para la integracion con pipelines CI/CD, consulta la guia de configuracion de CI/CD. Revisa tambien la documentacion oficial de Docker Compose.