Despliegue con Docker

Ejecute Sinaptic® DROID+ en producción con Docker. La imagen oficial es mínima (<15MB), se ejecuta como usuario no root e incluye una verificación de estado (healthcheck) integrada.

Imágenes

Registro	Imagen	Comando pull
Docker Hub (principal)	sinapticai/droid	docker pull sinapticai/droid:latest
GHCR (espejo)	ghcr.io/sinapticai/droid	docker pull ghcr.io/sinapticai/droid:latest

Etiquetas: latest, 0.5.0, 0.5, 0 (semver), además de sha-<commit> para fijar una versión específica.

Inicio rápido

docker run -d \
  --name droid \
  -p 8080:8080 \
  -p 8081:8081 \
  -v ./droid.yaml:/etc/droid/droid.yaml \
  -v ./configs/agents:/etc/droid/agents \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  sinapticai/droid

Esto inicia Sinaptic® DROID+ con:

• Puerto 8080: API compatible con OpenAI
• Puerto 8081: API de gestión + Interfaz de usuario Agent Builder
• Su configuración local y archivos de agentes montados en el contenedor
• Clave API pasada a través de una variable de entorno

Configuración

El contenedor espera dos rutas:

Ruta	Propósito	Por defecto
/etc/droid/droid.yaml	Configuración de ejecución	Requerido (monte el suyo propio)
/var/lib/droid	Directorio de datos (RAG, logs, auditoría)	Creado automáticamente

Sobrescriba la ruta de configuración con DROID_CONFIG y el directorio de datos con las variables de entorno DROID_DATA_DIR.

Variables de entorno

Pase las claves API y las sobrescrituras a través de variables de entorno. El archivo de configuración admite la sintaxis ${VAR}:

docker run -d \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GEMINI_API_KEY=AIza... \
  -e GROK_API_KEY=xai-... \
  sinapticai/droid

Docker Compose

Para despliegues en producción, utilice Docker Compose:

# docker-compose.yml
version: "3.8"

services:
  droid:
    image: sinapticai/droid:latest
    ports:
      - "8080:8080"   # API compatible con OpenAI
      - "8081:8081"   # API de gestión + Builder UI
    volumes:
      - ./droid.yaml:/etc/droid/droid.yaml:ro
      - ./configs/agents:/etc/droid/agents:ro
      - droid-data:/var/lib/droid
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
    restart: unless-stopped
    healthcheck:
      test: ["/usr/local/bin/droid", "health", "--openai-port", "8080"]
      interval: 30s
      timeout: 3s
      start_period: 5s
      retries: 3

volumes:
  droid-data:

Iniciar:

docker compose up -d

Verificaciones de estado (Health Checks)

El contenedor incluye una verificación de estado integrada que ejecuta droid health cada 30 segundos. También puede verificar el estado manualmente:

# Desde fuera del contenedor
curl http://localhost:8081/health

# Inspección de Docker
docker inspect --format='{{.State.Health.Status}}' droid

Recomendaciones para producción

Volúmenes

Monte su configuración como solo lectura (:ro) y use un volumen con nombre para los datos:

-v ./droid.yaml:/etc/droid/droid.yaml:ro
-v ./configs/agents:/etc/droid/agents:ro
-v droid-data:/var/lib/droid

Seguridad

El contenedor se ejecuta como no root por defecto (imagen distroless). Para mayor seguridad:

• No exponga el puerto 8081 públicamente: la API de gestión y la interfaz Builder UI son para uso interno.
• Utilice secretos de Docker o un depósito (vault) para las claves API en lugar de variables de entorno.
• Habilite SinapticAI en modo de bloqueo para todos los agentes de producción.

# Solo exponga externamente el puerto de la API
ports:
  - "8080:8080"
# Mantenga el puerto 8081 solo en la red interna

Límites de recursos

Sinaptic® DROID+ en sí mismo es ligero, pero las respuestas de LLM pueden consumir memoria durante el streaming. Mínimos recomendados:

deploy:
  resources:
    limits:
      memory: 512M
      cpus: "1.0"
    reservations:
      memory: 128M
      cpus: "0.25"

Registro (Logging)

Sinaptic® DROID+ genera registros JSON estructurados en stdout por defecto. Captúrelos con su agregador de registros preferido:

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Redes

Si ejecuta varias instancias de Sinaptic® DROID+ o se conecta a LLM locales (Ollama, LM Studio):

services:
  droid:
    # ... configuración de droid ...
    networks:
      - droid-net

  ollama:
    image: ollama/ollama:latest
    networks:
      - droid-net

networks:
  droid-net:
    driver: bridge

Luego haga referencia a Ollama por el nombre del servicio en droid.yaml:

ollama:
  base_url: "http://ollama:11434/v1"

Actualización

docker pull sinapticai/droid:latest
docker compose up -d

El contenedor es sin estado (stateless): toda la configuración está en archivos montados y todos los datos están en el volumen. Puede reemplazar el contenedor de forma segura en cualquier momento.

Compilación desde la fuente

Si prefiere compilar la imagen de Docker usted mismo:

git clone https://github.com/SinapticAI/droid-community.git
cd droid-community
docker build -t droid:local .

Solución de problemas

El contenedor se cierra inmediatamente: Revise los registros con docker logs droid. Causa más común: falta el archivo droid.yaml o no es válido.

Falla la verificación de estado: Asegúrese de que el puerto 8080 sea accesible dentro del contenedor y que el archivo de configuración sea un YAML válido.

No se puede conectar al LLM local: Si Ollama o LM Studio se ejecutan en el host, use host.docker.internal en lugar de localhost:

ollama:
  base_url: "http://host.docker.internal:11434/v1"

Permiso denegado en los volúmenes: El contenedor se ejecuta como no root. Asegúrese de que los directorios montados sean legibles por el UID 65534 (nobody).