Wdrożenie przez Docker

Uruchamiaj Sinaptic® DROID+ w środowisku produkcyjnym za pomocą Docker. Oficjalny obraz jest minimalny (<15MB), działa bez uprawnień roota i zawiera wbudowaną kontrolę stanu (healthcheck).

Obrazy

Rejestr	Obraz	Polecenie pobierania
Docker Hub (główny)	sinapticai/droid	docker pull sinapticai/droid:latest
GHCR (mirror)	ghcr.io/sinapticai/droid	docker pull ghcr.io/sinapticai/droid:latest

Tagi: latest, 0.5.0, 0.5, 0 (semver) oraz sha-<commit> dla precyzyjnego określenia wersji.

Szybki start

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

To polecenie uruchamia Sinaptic® DROID+ z:

• Portem 8080: API kompatybilne z OpenAI
• Portem 8081: API zarządzania + interfejs Agent Builder
• Lokalną konfiguracją i plikami agentów zamontowanymi w kontenerze
• Kluczem API przekazanym przez zmienną środowiskową

Konfiguracja

Kontener oczekuje dwóch ścieżek:

Ścieżka	Przeznaczenie	Domyślnie
/etc/droid/droid.yaml	Konfiguracja środowiska	Wymagane (zamontuj własną)
/var/lib/droid	Katalog danych (RAG, logi, audyt)	Tworzony automatycznie

Możesz nadpisać ścieżkę konfiguracji za pomocą zmiennej DROID_CONFIG oraz katalog danych za pomocą DROID_DATA_DIR.

Zmienne środowiskowe

Przekazuj klucze API i nadpisuj ustawienia za pomocą zmiennych środowiskowych. Plik konfiguracyjny wspiera składnię ${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

W przypadku wdrożeń produkcyjnych zaleca się użycie Docker Compose:

# docker-compose.yml
version: "3.8"

services:
  droid:
    image: sinapticai/droid:latest
    ports:
      - "8080:8080"   # API kompatybilne z OpenAI
      - "8081:8081"   # API zarządzania + 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:

Uruchomienie:

docker compose up -d

Kontrole stanu (Health Checks)

Kontener zawiera wbudowaną kontrolę stanu, która uruchamia polecenie droid health co 30 sekund. Możesz również sprawdzić stan ręcznie:

# Z zewnątrz kontenera
curl http://localhost:8081/health

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

Zalecenia produkcyjne

Wolumeny (Volumes)

Zamontuj konfigurację w trybie tylko do odczytu (:ro) i używaj nazwanego wolumenu dla danych:

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

Bezpieczeństwo

Kontener domyślnie działa bez uprawnień roota (obraz typu distroless). Dla dodatkowego bezpieczeństwa:

• Nie udostępniaj portu 8081 publicznie — API zarządzania i interfejs Builder UI służą do użytku wewnętrznego.
• Używaj sekretów Docker lub skarbca (vault) dla kluczy API zamiast zmiennych środowiskowych.
• Włącz SinapticAI w trybie blokowania (block mode) dla wszystkich agentów produkcyjnych.

# Udostępnij na zewnątrz tylko port API
ports:
  - "8080:8080"
# Port 8081 pozostaw tylko w sieci wewnętrznej

Limity zasobów

Sam Sinaptic® DROID+ jest lekki, ale odpowiedzi LLM mogą zużywać pamięć podczas przesyłania strumieniowego. Zalecane minima:

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

Logowanie

Sinaptic® DROID+ domyślnie generuje ustrukturyzowane logi JSON do stdout. Przechwytuj je za pomocą preferowanego agregatora logów:

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

Sieć

Jeśli uruchamiasz wiele instancji Sinaptic® DROID+ lub łączysz się z lokalnymi modelami LLM (Ollama, LM Studio):

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

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

networks:
  droid-net:
    driver: bridge

Następnie odwołuj się do Ollama poprzez nazwę usługi w pliku droid.yaml:

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

Aktualizacja

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

Kontener jest bezstanowy — cała konfiguracja znajduje się w zamontowanych plikach, a wszystkie dane w wolumenie. Możesz bezpiecznie wymienić kontener w dowolnym momencie.

Budowanie ze źródeł

Jeśli wolisz samodzielnie zbudować obraz Docker:

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

Rozwiązywanie problemów

Kontener natychmiast kończy pracę: Sprawdź logi za pomocą docker logs droid. Najczęstsza przyczyna: brakujący lub nieprawidłowy plik droid.yaml.

Kontrola stanu (healthcheck) nie przechodzi: Upewnij się, że port 8080 jest dostępny wewnątrz kontenera, a plik konfiguracyjny jest poprawnym plikiem YAML.

Nie można połączyć się z lokalnym modelem LLM: Jeśli Ollama lub LM Studio działają na hoście, użyj host.docker.internal zamiast localhost:

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

Brak uprawnień do wolumenów (Permission denied): Kontener działa bez uprawnień roota. Upewnij się, że zamontowane katalogi są czytelne dla użytkownika o UID 65534 (nobody).