Módulo 2: Local & Container Deployment

1. Introducción: Local & Container Deployment

Descripción

Esta es la primera cápsula del Módulo 2. Aquí vas a entender por qué deployment local con Docker Compose multi-container es la base de todo lo que viene en esta guía — y por qué "local" no significa "juguete". Un entorno local bien configurado replica producción con fidelidad: misma estructura de servicios, misma configuración de networking, mismos health checks. La diferencia con producción es dónde corre, no cómo está configurado.

Por qué importa: Ya tomaste una decisión informada en el Módulo 1 con tu decision matrix. Independientemente de qué estrategia elegiste, dominar deployment local con Docker Compose es fundamental. Es tu entorno de desarrollo, tu staging, y para muchos casos es producción legítima. Los módulos 4 (LocalStack), 6 (migration), y 8 (integrador) construyen sobre el Compose que configuras aquí.

¿Dónde Estamos en la Guía?

Contexto

Phase 1: Deployment Strategies (Módulos 1-3)
├── Módulo 1: Understanding Deployment Options    ✅ COMPLETADO
├── Módulo 2: Local & Container Deployment        ← ESTÁS AQUÍ
└── Módulo 3: Serverless & Lambda for AI

Phase 2: Cloud Infrastructure & Migration (Módulos 4-6)
Phase 3: Alternatives & Production (Módulos 7-8)

Transición desde Módulo 1

En el Módulo 1 construiste un framework para decidir. Aquí empiezas a implementar. La primera estrategia que dominas es deployment local porque:

Es la base de tu desarrollo diario
Docker Compose es portable a cualquier plataforma
Tu entorno local debe replicar producción
LocalStack (M4) se integra como servicio en tu Compose

Qué Es Docker Compose Multi-Container para AI

De un container a un sistema

La guía de Docker (#15) te enseñó a containerizar tu app: un Dockerfile, un container, un servicio. Pero una app AI de producción no es un solo container:

App AI simple (1 container):
└── FastAPI + OpenAI SDK

App AI de producción (3-5 containers):
├── FastAPI (API gateway)
├── Redis (cache de responses)
├── ChromaDB/Qdrant (vector store)
├── Worker (procesamiento async)
└── Nginx (reverse proxy + SSL)

Docker Compose orquesta todos estos containers como un sistema: los levanta en el orden correcto, conecta sus redes, comparte volúmenes, y verifica que cada uno está healthy antes de aceptar tráfico.

La analogía del restaurante

Un solo container es como un chef que cocina, sirve, y cobra. Funciona si tienes 5 clientes. Docker Compose es como un restaurante organizado: chef en la cocina, meseros sirviendo, cajero cobrando, cada uno con su rol y comunicándose entre sí. Si el chef no está listo, los meseros esperan. Si la caja falla, el restaurante sigue cocinando pero no cobra.

Cada categoría en código

Para que veas la diferencia concreta, así se ve cada patrón:

# Un solo container (guía Docker #15)
docker run -p 8000:8000 my-ai-app

# Docker Compose multi-container (este módulo)
# docker-compose.yml
services:
  api:
    build: ./api
    ports:
      - "8000:8000"
    depends_on:
      cache:
        condition: service_healthy
  cache:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

# Un comando levanta todo el sistema
docker compose up -d

# Un comando lo apaga
docker compose down

La diferencia clave: con docker run gestionas cada container manualmente. Con Compose, declaras tu sistema completo en un archivo y Compose lo orquesta por ti.

Tecnologías de Este Módulo

Herramienta	Versión	Qué hace en este módulo
Docker Compose	v2.20+	Orquesta multi-container
FastAPI	0.115+	API gateway de tu app AI
Redis	7.x	Cache de responses LLM
Python	3.10+	Lenguaje de la app
OpenAI SDK	1.0+	Llamadas a LLM
Pydantic	2.0+	Validación de config y requests
curl	-	Health checks y testing

Arquitectura de referencia

                    ┌──────────────────────────────────────────┐
                    │         Docker Compose Network           │
                    │                                          │
  User Request ──→  │  ┌─────────┐      ┌─────────┐           │
                    │  │ FastAPI  │ ←──→ │  Redis   │           │
                    │  │ :8000   │      │  :6379  │           │
                    │  │         │      │ (cache) │           │
                    │  │ /health │      └─────────┘           │
                    │  │ /ask    │                             │
                    │  └─────────┘                             │
                    │       │                                  │
                    │       ↓                                  │
                    │  OpenAI API (externo)                    │
                    └──────────────────────────────────────────┘

Cada servicio corre en su propio container, con su propio filesystem, su propia red interna, y sus propios health checks. Docker Compose se encarga de que el orden, la comunicación, y la persistencia funcionen sin intervención manual.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Diseñar un Docker Compose file para una app AI multi-container (FastAPI + Redis + servicio AI)
✅ Implementar environment configuration por entorno (dev, staging, prod)
✅ Configurar volumes para datos persistentes y networking entre servicios
✅ Implementar health checks que verifican readiness real de cada servicio
✅ Definir dependency ordering correcto entre servicios
✅ Debuggear deployment local con docker compose logs, exec, y troubleshooting
✅ Manejar secrets y API keys de forma segura sin commitear a Git

Objetivo profesional

Cuando necesites mostrar tu app AI a un colega, a un manager, o a un inversor, harás docker compose up y en 30 segundos tendrás un sistema multi-servicio corriendo con health checks, cache, y configuración production-like. Eso es deployment local profesional.

Roadmap del Módulo

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	Context, objetivos, setup	Intro
02	Docker Compose para AI Apps	Compose file, servicios, redes, volúmenes	Técnica
03	Environment Configuration	Variables por entorno, .env files, overrides	Técnica
04	Health Checks y Dependencies	Readiness checks, dependency ordering, restart policies	Técnica
05	Networking y Comunicación	Redes internas, puertos, service discovery	Técnica
06	Debugging Deployment Local	Logs, exec, troubleshooting de AI apps	Técnica
07	Secrets y Seguridad Local	API keys, .env, Docker secrets, gitignore	Técnica
08	Proyecto: Local Multi-Container AI App	Compose completo con FastAPI + Redis + AI	Proyecto

Duración estimada: 1.25-1.5 horas.

Prerequisitos

Lo que ya sabes (de la guía Docker #15)

✅ Qué es un Dockerfile, image, container
✅ Cómo buildear y correr un container
✅ Comandos básicos: docker build, docker run, docker ps
✅ Dockerizar una app FastAPI

Lo que aprenderás aquí (nuevo)

Docker Compose multi-service (no solo un container)
Orquestación: ordering, health checks, dependencies
Environment config por entorno
Debugging de deployment local
Secrets management local

Setup Técnico

Verificar herramientas

# Docker
docker --version
# Docker version 24.0+ esperado

# Docker Compose (v2, integrado en Docker Desktop)
docker compose version
# Docker Compose version v2.20+ esperado

# Python
python --version
# Python 3.10+ esperado

Crear estructura del proyecto

mkdir -p module-02/{api,worker}
cd module-02

# Estructura inicial
# module-02/
# ├── api/
# │   ├── main.py
# │   ├── requirements.txt
# │   └── Dockerfile
# ├── worker/
# │   ├── worker.py
# │   ├── requirements.txt
# │   └── Dockerfile
# ├── docker-compose.yml
# ├── docker-compose.override.yml
# ├── .env
# └── .env.example

API key de OpenAI

Necesitas una API key de OpenAI para los ejemplos de este módulo. Si no tienes una:

Ve a platform.openai.com
Crea una cuenta (o usa la existente)
Ve a API Keys → Create new secret key
Copia la key (empieza con sk-proj-...)

# Crea un archivo .env en tu directorio de trabajo
echo "OPENAI_API_KEY=sk-proj-tu-key-aqui" > .env

# NUNCA commitees este archivo a Git
echo ".env" >> .gitignore

Los ejemplos usan gpt-4o-mini que es el modelo más económico (~$0.15/1M input tokens). Un módulo completo de práctica no debería costarte más de $0.50.

Verificación rápida

# Verifica que Docker funciona
docker run --rm hello-world

# Verifica que Compose funciona
echo 'services:
  test:
    image: alpine
    command: echo "Compose works!"' > test-compose.yml

docker compose -f test-compose.yml up
# Output esperado: "Compose works!"

rm test-compose.yml

Verificar todo junto

# Script rápido de verificación completa
echo "=== Docker ===" && docker --version \
  && echo "=== Compose ===" && docker compose version \
  && echo "=== Python ===" && python --version \
  && echo "=== OpenAI key ===" && ([ -f .env ] && echo ".env exists ✅" || echo ".env missing ❌") \
  && echo "=== All checks passed ==="

Si todo muestra versiones correctas y .env exists, estás listo para la cápsula 02.

Conexión con el Proyecto

Proyecto de este módulo: Local Multi-Container AI App

Construirás un Docker Compose completo con:

FastAPI como API gateway (recibe requests, los procesa)
Redis como cache de responses (evita llamadas repetidas a LLM)
Worker (opcional) para procesamiento asíncrono

User Request
    ↓
┌─────────────────────┐
│ FastAPI (api)        │
│ Puerto 8000          │
│ ├── /health          │
│ ├── /ask             │──→ Check Redis cache
│ └── /ask (cache miss)│──→ Call OpenAI → Store in Redis
└─────────────────────┘
         ↕
┌─────────────────────┐
│ Redis (cache)        │
│ Puerto 6379 (interno)│
│ Cache de responses   │
└─────────────────────┘

Este Compose se extiende en módulos posteriores:

M4: Agregar LocalStack como servicio (S3, Lambda locales)
M6: Usar como entorno de desarrollo para migration a AWS
M8: Base del sistema desplegado en producción

Evolución del Compose a lo largo de la guía:

M2: FastAPI + Redis (base)
 ↓
M4: FastAPI + Redis + LocalStack (S3/Lambda local)
 ↓
M6: Mismo Compose, código que funciona contra LocalStack Y AWS
 ↓
M8: Compose local → CI/CD → Plataforma de producción

El Compose que construyes en este módulo no es un ejercicio desechable. Es el artefacto central de la guía — la base sobre la que añades capas de complejidad módulo a módulo.

Que NO es prerequisito (lo aprendes aquí)

Algunos conceptos que podrías pensar que necesitas saber pero que este módulo te enseña:

Concepto	¿Lo necesitas antes?	Dónde lo aprendes
Docker Compose syntax	No	Cápsula 02
.env files y overrides	No	Cápsula 03
Health checks	No	Cápsula 04
Docker networking	No	Cápsula 05
Docker debugging	No	Cápsula 06
Secrets management	No	Cápsula 07

Límites: Qué NO Cubre Este Módulo

❌ Docker desde cero — Prerequisite: Docker Essentials Guide (#15)
❌ Kubernetes — Orquestación a escala enterprise, fuera de scope
❌ Deployment a cloud — Eso viene en Módulos 3-8
❌ Docker Swarm — Compose es suficiente para el scope de esta guía
❌ CI/CD setup — Prerequisite: CI/CD for AI Systems Guide (#16)

Evidencia de Éxito

Al terminar este módulo:

✅ docker compose up levanta tu app AI multi-container en <30 segundos
✅ Los health checks verifican que cada servicio está operativo
✅ Redis cachea responses y reduces llamadas a LLM
✅ Puedes cambiar entre configuración dev y staging con un flag
✅ Sabes diagnosticar cuando un servicio no arranca (logs, exec, networking)
✅ Las API keys no están en tu código ni en Git

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar el módulo, lo dominaste:

¿Por qué una app AI necesita más de un container?
¿Qué problema resuelve depends_on con condition: service_healthy?
¿Cuál es la diferencia entre ports y expose en Compose?
¿Cómo cambias entre configuración de dev y staging sin modificar el Compose file?
¿Qué es lo primero que haces cuando un servicio no arranca?

Si alguna te parece difícil ahora, no te preocupes — las respuestas quedan claras a lo largo de las 8 cápsulas.

Resumen

Docker Compose multi-container es la base de deployment profesional para AI apps.
Un entorno local bien configurado replica producción — no es un juguete.
Una app AI típica tiene 3-5 servicios: API, cache, vector store, worker, reverse proxy.
Este módulo cubre las 7 habilidades clave: Compose files, env config, health checks, networking, debugging, secrets, y proyecto integrador.
Este módulo construye el Compose que se reutiliza en M4 (LocalStack), M6 (migration), y M8 (producción).
El proyecto final es una app AI multi-container con FastAPI + Redis funcional.
Prerequisito: Docker Essentials Guide (#15). Si sabes hacer docker build y docker run, estás listo.

Recursos Adicionales

Docker Compose Documentation — Referencia oficial completa
Docker Compose File Reference — Especificación del archivo Compose
FastAPI Docker Deployment — Guía oficial de FastAPI con Docker
Redis Docker Hub — Imagen oficial de Redis
Docker Networking Overview — Networking en Docker
Docker Compose Best Practices — Compose en producción

← Anterior8. Proyecto: Deployment Decision Workshop Siguiente →2. Docker Compose para AI Apps