Docker-Deployment

Betreiben Sie Sinaptic® DROID+ produktiv mit Docker. Das offizielle Image ist minimal (<15MB), wird als Nicht-Root-Benutzer ausgeführt und enthält einen integrierten Healthcheck.

Images

Registry	Image	Pull-Befehl
Docker Hub (primär)	sinapticai/droid	docker pull sinapticai/droid:latest
GHCR (Mirror)	ghcr.io/sinapticai/droid	docker pull ghcr.io/sinapticai/droid:latest

Tags: latest, 0.5.0, 0.5, 0 (semver) sowie sha-<commit> zur Fixierung einer bestimmten Version.

Schnellstart

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

Dies startet Sinaptic® DROID+ mit:

• Port 8080: OpenAI-kompatible API
• Port 8081: Management-API + Agent Builder UI
• Ihrer lokalen Konfiguration und den Agent-Dateien, die in den Container gemountet werden
• API-Key, der über eine Umgebungsvariable übergeben wird

Konfiguration

Der Container erwartet zwei Pfade:

Pfad	Zweck	Standard
/etc/droid/droid.yaml	Runtime-Konfiguration	Erforderlich (eigenen Pfad mounten)
/var/lib/droid	Datenverzeichnis (RAG, Logs, Audit)	Wird automatisch erstellt

Überschreiben Sie den Konfigurationspfad mit DROID_CONFIG und das Datenverzeichnis mit den Umgebungsvariablen DROID_DATA_DIR.

Umgebungsvariablen

Übergeben Sie API-Keys und Overrides via Umgebungsvariablen. Die Konfigurationsdatei unterstützt die ${VAR}-Syntax:

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

Verwenden Sie für den Produktiveinsatz Docker Compose:

# docker-compose.yml
version: "3.8"

services:
  droid:
    image: sinapticai/droid:latest
    ports:
      - "8080:8080"   # OpenAI-kompatible API
      - "8081:8081"   # Management-API + 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:

Starten:

docker compose up -d

Healthchecks

Der Container enthält einen integrierten Healthcheck, der alle 30 Sekunden droid health ausführt. Sie können den Status auch manuell prüfen:

# Von außerhalb des Containers
curl http://localhost:8081/health

# Docker inspect
docker inspect --format='{{.State.Health.Status}}' droid

Empfehlungen für den Produktiveinsatz

Volumes

Mounten Sie Ihre Konfiguration als schreibgeschützt (:ro) und verwenden Sie ein benanntes Volume für die Daten:

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

Sicherheit

Der Container wird standardmäßig als Nicht-Root-Benutzer ausgeführt (Distroless-Image). Für zusätzliche Sicherheit:

• Port 8081 nicht öffentlich zugänglich machen — die Management-API und das Builder UI sind für den internen Gebrauch bestimmt.
• Docker Secrets oder einen Vault für API-Keys anstelle von Umgebungsvariablen verwenden.
• SinapticAI im Block-Modus für alle Produktions-Agenten aktivieren.

# Nur den API-Port extern freigeben
ports:
  - "8080:8080"
# Port 8081 nur im internen Netzwerk belassen

Ressourcenlimits

Sinaptic® DROID+ selbst ist leichtgewichtig, aber LLM-Antworten können während des Streamings Speicher verbrauchen. Empfohlene Mindestwerte:

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

Logging

Sinaptic® DROID+ gibt standardmäßig strukturierte JSON-Logs auf stdout aus. Erfassen Sie diese mit Ihrem bevorzugten Log-Aggregator:

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

Netzwerk

Wenn Sie mehrere Sinaptic® DROID+-Instanzen betreiben oder Verbindungen zu lokalen LLMs (Ollama, LM Studio) herstellen:

services:
  droid:
    # ... droid Konfiguration ...
    networks:
      - droid-net

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

networks:
  droid-net:
    driver: bridge

Referenzieren Sie Ollama dann über den Servicenamen in der droid.yaml:

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

Aktualisieren

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

Der Container ist zustandslos — die gesamte Konfiguration befindet sich in gemounteten Dateien und alle Daten im Volume. Sie können den Container jederzeit sicher ersetzen.

Build aus dem Quellcode

Wenn Sie das Docker-Image lieber selbst erstellen möchten:

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

Fehlerbehebung

Container wird sofort beendet: Prüfen Sie die Logs mit docker logs droid. Häufigste Ursache: fehlende oder ungültige droid.yaml.

Healthcheck schlägt fehl: Stellen Sie sicher, dass Port 8080 innerhalb des Containers erreichbar ist und die Konfigurationsdatei valides YAML ist.

Verbindung zum lokalen LLM nicht möglich: Wenn Ollama oder LM Studio auf dem Host ausgeführt wird, verwenden Sie host.docker.internal anstelle von localhost:

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

Zugriff auf Volumes verweigert (Permission denied): Der Container wird als Nicht-Root-Benutzer ausgeführt. Stellen Sie sicher, dass gemountete Verzeichnisse für die UID 65534 (nobody) lesbar sind.