Servidor de Ollama y ejecución en Docker

El servidor de Ollama

En la arquitectura de Ollama, el servidor es el proceso que carga los modelos, ejecuta la inferencia y atiende las peticiones de la CLI y de la API. Cuando usas la aplicación de escritorio o un comando como ollama run, el cliente se comunica con ese servidor. En una instalación típica en tu máquina, el servidor se inicia en segundo plano de forma automática la primera vez que lo necesitas, no hace falta arrancarlo manualmente para el uso diario.

flowchart LR
    A["Cliente<br/>CLI, API, app"] -->|"HTTP<br/>puerto 11434"| B["Servidor Ollama"]
    B --> C["Modelo cargado<br/>en memoria"]
    subgraph Despliegue["Opciones de despliegue"]
        direction TB
        D["Nativo<br/>ollama serve"]
        E["Docker<br/>ollama/ollama"]
        F["Servicio del sistema<br/>systemd, etc."]
    end
    D --> B
    E --> B
    F --> B

Si quieres control explícito (por ejemplo en un servidor sin interfaz gráfica o para asegurarte de que escucha en una interfaz concreta), puedes lanzar el servidor con:

ollama serve

El proceso queda en primer plano y escucha las peticiones. En este modo es útil ver los logs en la terminal para depurar o comprobar qué modelos se cargan. En entornos de producción o en máquinas dedicadas, suele configurarse como servicio del sistema (systemd en Linux, servicio de Windows, etc.) para que el servidor arranque al iniciar el equipo y se reinicie si falla.

Puerto y dirección por defecto

Por defecto el servidor de Ollama escucha en localhost en el puerto 11434. Cualquier cliente (navegador, script, aplicación) que quiera usar la API debe enviar las peticiones a esa dirección, por ejemplo http://localhost:11434.

La variable de entorno OLLAMA_HOST controla en qué dirección y puerto se enlaza el servidor. Si necesitas que acepte peticiones desde otros equipos de la red (por ejemplo, para servir la API desde una máquina en la LAN), puedes configurar OLLAMA_HOST con la interfaz y el puerto deseados (por ejemplo 0.0.0.0:11434 para escuchar en todas las interfaces). Si cambias el puerto o la interfaz, todos los clientes (CLI, aplicación de escritorio, código que use la API) deben conocer la nueva base URL para conectarse al servidor.

Ejecución en Docker

Ejecutar Ollama dentro de un contenedor Docker es útil cuando quieres aislar el entorno, desplegarlo en un servidor sin instalar el binario directamente o tener varias instancias con distintas configuraciones. La imagen oficial de Ollama en Docker Hub permite arrancar el servidor en un contenedor con un comando similar a:

docker run -d -v ollama:/root/.ollama -p 11434:11434 ollama/ollama

El flag -v ollama:/root/.ollama persiste los modelos descargados en un volumen con nombre, de modo que no se pierden al eliminar el contenedor. El flag -p 11434:11434 expone el puerto del servidor en el host. Desde la máquina host, la API queda disponible en http://localhost:11434 como en una instalación nativa. Si quieres que el servidor dentro del contenedor acepte conexiones desde fuera del host (por ejemplo desde otra máquina de la red), puedes pasar además la variable de entorno OLLAMA_HOST=0.0.0.0 en el docker run para que el servidor escuche en todas las interfaces del contenedor.

Si tu host tiene GPU y quieres que el contenedor la use para acelerar la inferencia, hay que añadir los flags correspondientes (por ejemplo --gpus all en Docker con NVIDIA). La documentación de Ollama y de Docker describe las opciones exactas según el tipo de GPU y el sistema operativo.

Usar Docker no es obligatorio: en un equipo de desarrollo o personal, la instalación nativa suele ser más sencilla. Docker compensa cuando necesitas el servidor en un servidor remoto, en un entorno reproducible o junto con otros servicios en una pila de contenedores.

Variables de entorno del servidor

Además de OLLAMA_HOST, el servidor acepta varias variables de entorno para ajustar su comportamiento:

| Variable | Descripción | |----------|-------------| | OLLAMA_HOST | Dirección y puerto donde escucha (por defecto 127.0.0.1:11434). | | OLLAMA_MODELS | Directorio de almacenamiento de modelos (por defecto ~/.ollama/models). | | OLLAMA_KEEP_ALIVE | Tiempo que un modelo permanece cargado en memoria tras la última petición (por ejemplo 5m, 1h). | | OLLAMA_NUM_PARALLEL | Número máximo de peticiones que se procesan en paralelo. | | OLLAMA_MAX_LOADED_MODELS | Número máximo de modelos cargados simultáneamente en memoria. | | OLLAMA_NO_CLOUD | Si es 1, desactiva la conexión con Ollama Cloud. |

Estas variables se pasan al contenedor Docker con el flag -e (por ejemplo -e OLLAMA_HOST=0.0.0.0:11434) o se definen en un archivo .env si usas Docker Compose.

Docker Compose con servicios adicionales

En proyectos donde Ollama forma parte de una pila de servicios (por ejemplo, junto con una base de datos vectorial para RAG o una interfaz web), puedes usar Docker Compose para orquestar todo:

services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      - OLLAMA_HOST=0.0.0.0
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama_data:

El bloque deploy.resources.reservations.devices expone las GPU NVIDIA al contenedor. Para AMD (ROCm) se usa la imagen ollama/ollama:rocm y la configuración correspondiente de dispositivos. Si no tienes GPU, basta con omitir ese bloque y el servidor ejecutará los modelos en CPU.

Servidor como servicio del sistema

En entornos de producción o en servidores dedicados, conviene que el servidor de Ollama arranque automáticamente con el sistema operativo y se reinicie si falla. En Linux, el script de instalación oficial crea un servicio systemd que gestiona el ciclo de vida del proceso:

# Ver estado del servicio
sudo systemctl status ollama

# Reiniciar el servicio
sudo systemctl restart ollama

# Ver logs recientes
journalctl -u ollama --no-pager -n 50

En Windows, el servidor se ejecuta como servicio del sistema cuando se instala con el instalador oficial. Se puede gestionar desde el administrador de servicios o desde la bandeja del sistema. En macOS, la aplicación de escritorio actúa como gestor del servidor y lo arranca al abrirse.

Comprobar que el servidor responde

Antes de empezar a trabajar con un servidor recién levantado, conviene verificar que responde correctamente. Tres comprobaciones rápidas son más que suficientes:

# 1. ¿Está abierto el puerto?
curl -s http://localhost:11434/ || echo "no responde"

# 2. ¿Qué versión corre?
curl -s http://localhost:11434/api/version

# 3. ¿Qué modelos tiene cargados ahora mismo?
curl -s http://localhost:11434/api/ps

La raíz del servidor (GET /) devuelve un mensaje fijo cuando el proceso está activo, lo que permite usarlo como health check en un balanceador o en un docker healthcheck. El endpoint /api/version es útil para detectar desfases entre cliente y servidor, y /api/ps muestra los modelos actualmente cargados en memoria junto a su tiempo restante de keep-alive.

Dentro de un docker-compose.yml el health check quedaría así:

services:
  ollama:
    image: ollama/ollama
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:11434/ || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

Tabla comparativa: instalación nativa, Docker y servicio del sistema

| Criterio | Nativo (instalador oficial) | Docker | systemd / servicio | |----------|----------------------------|--------|---------------------| | Complejidad inicial | Muy baja | Media | Media | | Aislamiento | Ninguno | Alto | Bajo | | Reinicio automático | Depende del SO | Sí con --restart=always | Sí | | Portabilidad | Ligada al SO | Muy alta | Ligada al SO | | GPU | Directo | Requiere --gpus all | Directo | | Ideal para | Desarrollo en tu máquina | Servidores compartidos, CI/CD | Producción en servidor propio |

En la práctica, la combinación más habitual es nativo en portátil de desarrollo y Docker o systemd en servidor. Mantén la misma versión en ambos entornos para evitar sorpresas con modelos o parámetros que se comportan distinto entre releases.

Errores comunes al levantar el servidor

• «address already in use» al ejecutar ollama serve: otro proceso (o el propio servicio de Ollama ya iniciado) está usando el puerto 11434. Libera el puerto o cambia OLLAMA_HOST.
• El contenedor no ve la GPU: suele faltar el paquete nvidia-container-toolkit o el flag --gpus all. Comprueba con nvidia-smi dentro del contenedor que la tarjeta está accesible.
• Modelos perdidos tras recrear el contenedor: olvidaste mapear el volumen. Usa siempre -v ollama:/root/.ollama para persistir descargas.
• Lentitud después de horas funcionando: el servidor puede tener modelos cargados que no estás usando. Ajusta OLLAMA_KEEP_ALIVE o OLLAMA_MAX_LOADED_MODELS para liberar memoria antes.
• Peticiones rechazadas desde otra máquina: OLLAMA_HOST está en 127.0.0.1 (por defecto). Cámbialo a 0.0.0.0 y protégelo con firewall o VPN antes de exponer el puerto.
• Conflictos con Docker Desktop en Windows/macOS: la aplicación de escritorio puede entrar en conflicto con un contenedor escuchando en el mismo puerto. Ejecuta una de las dos instalaciones a la vez.

Mejores prácticas

1. Un servidor, un propósito: evita compartir un mismo servidor entre equipos con cargas muy distintas. Es más fácil dimensionar y auditar si cada servicio tiene su instancia.
2. Define siempre OLLAMA_MODELS fuera del volumen del sistema para evitar llenar el disco raíz.
3. Limita OLLAMA_NUM_PARALLEL al número real de peticiones que puedes atender sin saturar la GPU. Un valor demasiado alto degrada más que ayuda.
4. Monitoriza logs y métricas: en Linux con journalctl -u ollama -f durante una prueba y con Prometheus o Grafana en producción cuando tengas tráfico real.
5. Actualiza con plan: antes de actualizar el servidor en producción, prueba la nueva versión en un entorno de staging con los mismos modelos; así evitas cambios de comportamiento inesperados.
6. Haz copias de seguridad del volumen de modelos si has cuantizado o creado variantes propias con ollama create: reconstruirlas lleva tiempo.

Con un servidor bien configurado, estable y con los accesos controlados, Ollama se integra sin fricciones en cualquier arquitectura moderna, desde una estación de trabajo individual hasta una infraestructura compartida por varios equipos.