Docker 배포

Sinaptic® DROID+를 Docker를 사용하여 운영 환경에서 실행하세요. 공식 이미지는 매우 가벼우며(<15MB), root 권한이 아닌 사용자로 실행되고, 빌트인 상태 확인(healthcheck) 기능을 포함하고 있습니다.

이미지 정보

레지스트리	이미지명	다운로드(Pull) 명령어
Docker Hub (기본)	`sinapticai/droid`	`docker pull sinapticai/droid:latest`
GHCR (미러)	`ghcr.io/sinapticai/droid`	`docker pull ghcr.io/sinapticai/droid:latest`

태그: latest, 0.5.0, 0.5, 0 (유의적 버전), 그리고 특정 버전 고정을 위한 sha-<commit>.

빠른 시작

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

이 명령은 다음 설정으로 Sinaptic® DROID+를 시작합니다:

8080 포트: OpenAI 호환 API
8081 포트: 관리 API + 에이전트 빌더(Agent Builder) UI
로컬 설정 및 에이전트 파일이 컨테이너에 마운트됨
환경 변수를 통해 API 키 전달

설정 방법

컨테이너는 다음 두 경로를 사용합니다:

경로	용도	기본값
`/etc/droid/droid.yaml`	런타임 설정	필수 (사용자 파일 마운트)
`/var/lib/droid`	데이터 디렉토리 (RAG, 로그, 감사)	자동 생성됨

DROID_CONFIG 환경 변수로 설정 경로를, DROID_DATA_DIR 환경 변수로 데이터 디렉토리 경로를 변경할 수 있습니다.

환경 변수

API 키 및 설정 덮어쓰기는 환경 변수를 통해 수행합니다. 설정 파일은 ${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

운영 환경에서는 Docker Compose 사용을 권장합니다:

# docker-compose.yml
version: "3.8"

services:
  droid:
    image: sinapticai/droid:latest
    ports:
      - "8080:8080"   # OpenAI 호환 API
      - "8081:8081"   # 관리 API + 빌더 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:

실행:

docker compose up -d

상태 확인 (Health Checks)

컨테이너에는 30초마다 droid health를 실행하는 빌트인 상태 확인 기능이 포함되어 있습니다. 수동으로 확인할 수도 있습니다:

# 컨테이너 외부에서 확인
curl http://localhost:8081/health

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

운영 환경 권장 사항

볼륨 설정

설정 파일은 읽기 전용(:ro)으로 마운트하고, 데이터 저장에는 이름이 지정된 볼륨(named volume)을 사용하세요.

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

보안

컨테이너는 기본적으로 root가 아닌 사용자로 실행됩니다(distroless 이미지). 추가 보안을 위해 다음을 고려하세요:

8081 포트를 외부에 노출하지 마세요. 관리 API와 빌더 UI는 내부용입니다.
환경 변수 대신 Docker 비밀 정보(secrets)나 Vault를 사용하여 API 키를 관리하세요.
모든 운영 에이전트에 대해 SinapticAI 차단(block) 모드를 활성화하세요.

# 외부에는 API 포트만 노출
ports:
  - "8080:8080"
# 8081 포트는 내부 네트워크에서만 유지

자원 제한

Sinaptic® DROID+ 자체는 가볍지만, LLM 응답 스트리밍 중에 메모리 사용량이 늘어날 수 있습니다. 권장 최소 사양은 다음과 같습니다:

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

로깅

Sinaptic® DROID+는 기본적으로 구조화된 JSON 로그를 stdout으로 출력합니다. 선호하는 로그 수집기를 사용하여 캡처하세요.

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

네트워킹

여러 개의 Sinaptic® DROID+ 인스턴스를 실행하거나 로컬 LLM(Ollama, LM Studio)에 연결하는 경우:

services:
  droid:
    # ... droid 설정 ...
    networks:
      - droid-net

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

networks:
  droid-net:
    driver: bridge

그 후 droid.yaml에서 서비스 이름으로 Ollama를 참조하세요:

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

업데이트 방법

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

컨테이너는 상태를 저장하지 않습니다(stateless). 모든 설정은 마운트된 파일에, 모든 데이터는 볼륨에 저장되므로 언제든지 안전하게 컨테이너를 교체할 수 있습니다.

소스에서 빌드하기

Docker 이미지를 직접 빌드하려는 경우:

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

문제 해결

컨테이너가 즉시 종료됨: docker logs droid로 로그를 확인하세요. 가장 흔한 원인은 droid.yaml 파일이 없거나 형식이 잘못된 경우입니다.

상태 확인 실패: 컨테이너 내부에서 8080 포트에 접근 가능한지, 설정 파일이 올바른 YAML 형식인지 확인하세요.

로컬 LLM에 연결할 수 없음: Ollama나 LM Studio가 호스트 머신에서 실행 중이라면 localhost 대신 host.docker.internal을 사용하세요.

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

볼륨 권한 거부 (Permission denied): 컨테이너는 root가 아닌 사용자로 실행됩니다. 마운트된 디렉토리가 UID 65534(nobody) 사용자에 의해 읽기 가능한지 확인하세요.

이미지 정보​

빠른 시작​

설정 방법​

환경 변수​

Docker Compose​

상태 확인 (Health Checks)​

운영 환경 권장 사항​

볼륨 설정​

보안​

자원 제한​

로깅​

네트워킹​

업데이트 방법​

소스에서 빌드하기​

문제 해결​