Docker Compose para IA local

Qué cubre este artículo

• Qué es Docker Compose y cuándo utilizarlo.
• Estructura de un archivo compose.yaml.
• Cómo definir servicios, redes y volúmenes.
• Ejemplos prácticos con Ollama, Open WebUI y bases de datos.
• Consejos para operar stacks de IA local.

Introducción: Docker Compose para IA local

Docker Compose te permite describir varios contenedores en un único archivo e iniciarlos de forma conjunta. Para configuraciones de IA local es especialmente útil, porque generalmente varios servicios trabajan juntos: Ollama para modelos, Open WebUI como interfaz, PostgreSQL con pgvector para RAG, quizás un caché Redis o un servidor web. En lugar de iniciar cada contenedor por separado, defines todo en compose.yaml y gestionas el stack completo con un solo comando.

Este artículo muestra cómo estructurar archivos de Compose y proporciona ejemplos concretos para stacks de IA.

Términos clave

• Compose: Herramienta de Docker para aplicaciones multicontenedor.
• compose.yaml: Archivo de configuración del stack.
• Service: Un contenedor que forma parte del stack.
• Volume: Almacenamiento persistente para contenedores.
• Network: Red virtual que conecta contenedores.
• Profile: Opción para iniciar ciertos servicios de forma opcional.
• Override: Archivo de Compose adicional que extiende valores.

Estructura básica de una compose.yaml

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama-data:/root/.ollama
    ports:
      - "127.0.0.1:11434:11434"
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama
    restart: unless-stopped

volumes:
  ollama-data:

Claves importantes

• image: La imagen a utilizar.
• container_name: Nombre del contenedor en ejecución.
• volumes: Montajes para datos persistentes.
• ports: Redireccionamiento de puertos del host al contenedor.
• environment: Variables de entorno.
• depends_on: Define el orden de inicio.
• restart: Comportamiento ante fallos.
• networks: Define redes personalizadas.

Redes

Por defecto, Compose crea una red para el stack. Los contenedores pueden comunicarse entre sí usando el nombre del servicio:

open-webui:
  image: ghcr.io/open-webui/open-webui:main
  environment:
    - OLLAMA_BASE_URL=http://ollama:11434

También puedes definir una red personalizada:

networks:
  ki-net:
    driver: bridge

Volúmenes

Los volúmenes garantizan que los datos persistan después de reiniciar un contenedor:

volumes:
  ollama-data:
  pg-data:

Ollama y Open WebUI

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    runtime: nvidia
    volumes:
      - ollama-data:/root/.ollama
    ports:
      - "127.0.0.1:11434:11434"
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama
    restart: unless-stopped

volumes:
  ollama-data:

Con base de datos para RAG

services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: postgres
    environment:
      - POSTGRES_USER=rag
      - POSTGRES_PASSWORD=ragpass
      - POSTGRES_DB=ragdb
    volumes:
      - pg-data:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"
    restart: unless-stopped

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama-data:/root/.ollama
    ports:
      - "127.0.0.1:11434:11434"
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - DATABASE_URL=postgresql://rag:ragpass@postgres:5432/ragdb
    depends_on:
      - ollama
      - postgres
    restart: unless-stopped

volumes:
  ollama-data:
  pg-data:

Comandos importantes

Comando	Propósito
docker compose up -d	Inicia el stack en segundo plano.
docker compose down	Detiene y elimina el stack.
docker compose down -v	Elimina también los volúmenes.
docker compose ps	Muestra el estado.
docker compose logs -f	Monitorea los logs en tiempo real.
docker compose pull	Descarga las imágenes más recientes.
docker compose build	Reconstruye las imágenes.
docker compose restart	Reinicia los servicios.

Variables de entorno desde archivo

Mueve secretos y configuración a .env:

services:
  open-webui:
    env_file:
      - .env

Perfiles

Inicia servicios solo cuando sea necesario:

services:
  monitoring:
    image: prom/prometheus
    profiles:
      - monitoring

Para iniciar:

docker compose --profile monitoring up -d

Consejos para IA local

• Asigna nombres a los contenedores para alcanzarlos más fácilmente.
• Evita vincular todo a 0.0.0.0, prefiere 127.0.0.1.
• Usa volúmenes para modelos, bases de datos y configuraciones.
• Aplica depends_on correctamente para las secuencias de inicio.
• Utiliza archivos .env para secretos y rutas.
• Usa restart: unless-stopped para servicios que deben ejecutarse continuamente.

Errores comunes

• Indentación YAML: Usa espacios en lugar de tabuladores.
• Puerto ocupado: Detén otro contenedor o servicio que use el mismo puerto.
• Sin red: Los contenedores no pueden comunicarse entre sí.
• GPU no disponible: Verifica runtime: nvidia y deploy.resources.reservations.
• Volúmenes olvidados: Los datos se pierden después de reiniciar.
• Variables de entorno incorrectas: Presta atención a espacios, signos de igualdad y paréntesis.

Enlaces y recursos

• BotServ.de Comandos Docker
• BotServ.de Conceptos Docker
• BotServ.de Comandos Ollama
• BotServ.de Seguridad Ollama
• BotServ.de Proxmox LXC vs. VM

FAQ: Docker Compose para IA local

¿Cuál es la diferencia entre Docker y Docker Compose? Docker gestiona contenedores individuales, Compose gestiona varios en conjunto.

¿Necesito Compose solo para Ollama? No, un comando docker run simple es suficiente. Cuando intervienen múltiples servicios, Compose vale la pena.

¿Dónde se encuentra el archivo compose.yaml? Generalmente en el directorio del proyecto. El comando docker compose up lo busca en el directorio actual.

¿Son seguros los datos en volúmenes? Sí, si el volumen no se elimina. De todos modos, es importante hacer copias de seguridad periódicas.

¿Puedo usar Compose con GPU? Sí, a través de runtime: nvidia o mediante deploy.resources.reservations.devices en versiones más recientes.

Fuentes y lecturas adicionales

• Docker Compose Docs: https://docs.docker.com/compose/
• Compose Specification: https://compose-spec.io/
• Ollama Docker: https://hub.docker.com/r/ollama/ollama

Resumen: Docker Compose para IA local

Docker Compose es la herramienta ideal para orquestar stacks de IA local compuestos por múltiples servicios. Con compose.yaml puedes iniciar Ollama, Open WebUI, bases de datos vectoriales y otros servicios de forma reproducible. Lo importante es mantener estructuras YAML limpias, usar volúmenes para persistencia, vincular puertos de forma segura y configurar variables de entorno apropiadas. Al usar Compose ahorras largos comandos docker run y obtienes una configuración mantenible.