10.6. Docker 배포¶

클라우드 서버, CI/CD 파이프라인, Kubernetes 클러스터 등 컨테이너화된 환경에 Backend.AI GO 서버를 배포합니다.

aigo-server 바이너리는 Backend.AI GO의 헤드리스 서버 컴포넌트입니다. 데스크톱 GUI 없이 실행되며, Management API와 OpenAI 호환 추론 API를 제공합니다.

빠른 시작¶

단일 명령으로 서버를 실행합니다:

docker run -d \
  --name aigo-server \
  -p 8001:8001 \
  -p 8000:8000 \
  -v aigo-models:/data/models \
  ghcr.io/lablup/backend-ai-go-server:latest

이후 브라우저에서 http://localhost:8001에 접속하면 웹 UI를 사용할 수 있습니다.

사전 요구사항¶

Docker Engine 24.0 이상
최소 8 GB RAM (대형 모델의 경우 16 GB 이상 권장)
GPU 가속의 경우: GPU 설정 섹션을 참조하세요

초기 설정¶

1. 관리자 API 키 생성¶

서버를 처음 시작하기 전에 마스터 키를 생성합니다:

docker run --rm ghcr.io/lablup/backend-ai-go-server:latest --generate-admin-key

생성된 키를 안전하게 저장하세요 — 한 번만 표시됩니다.

2. 마스터 키로 시작¶

환경 변수로 키를 전달합니다:

docker run -d \
  --name aigo-server \
  -p 8001:8001 \
  -p 8000:8000 \
  -e AIGO_MASTER_KEY=sk-admin-your-key-here \
  -v aigo-models:/data/models \
  -v aigo-data:/data \
  ghcr.io/lablup/backend-ai-go-server:latest

Docker Compose¶

프로젝트에는 전체 설정을 위한 docker-compose.yml이 포함되어 있습니다:

# 저장소 클론 (또는 docker-compose.yml 다운로드)
git clone https://github.com/lablup/backend.ai-go.git
cd backend.ai-go

# 관리자 키 생성 및 저장
docker compose run --rm aigo-server --generate-admin-key

# 마스터 키를 환경 변수로 설정
export AIGO_MASTER_KEY=sk-admin-your-generated-key

# 서버 시작
docker compose up -d

# 로그 확인
docker compose logs -f

# 종료
docker compose down

http://localhost:8001에서 웹 UI에 접속합니다.

설정¶

환경 변수¶

모든 설정 옵션을 환경 변수로 지정할 수 있습니다:

변수	기본값	설명
`AIGO_HOST`	`0.0.0.0`	바인드 주소
`AIGO_PORT`	`8001`	Management API 포트
`AIGO_ROUTER_PORT`	`8000`	추론 라우터 포트
`AIGO_MODELS_DIR`	`/data/models`	모델 저장 디렉터리
`AIGO_ENGINES_DIR`	`/data/engines`	추론 엔진 디렉터리
`AIGO_STATIC_DIR`	`/var/www/aigo`	웹 UI 정적 파일 디렉터리
`AIGO_MASTER_KEY`	(없음)	초기 관리자 설정을 위한 마스터 API 키
`AIGO_LOG_LEVEL`	`info`	로그 수준: `trace`, `debug`, `info`, `warn`, `error`
`AIGO_CONFIG`	(자동)	TOML 설정 파일 경로

설정 파일¶

고급 설정의 경우 TOML 파일을 마운트합니다:

# 예제 설정 생성
docker run --rm ghcr.io/lablup/backend-ai-go-server:latest --generate-config > aigo-server.toml

# 설정 편집
nano aigo-server.toml

# 설정 파일로 시작
docker run -d \
  --name aigo-server \
  -p 8001:8001 \
  -p 8000:8000 \
  -v $(pwd)/aigo-server.toml:/data/config/config.toml:ro \
  -v aigo-models:/data/models \
  -v aigo-data:/data \
  ghcr.io/lablup/backend-ai-go-server:latest \
  --config /data/config/config.toml --external

설정 검증¶

시작 전에 설정을 테스트합니다:

docker run --rm \
  -v $(pwd)/aigo-server.toml:/data/config/config.toml:ro \
  ghcr.io/lablup/backend-ai-go-server:latest \
  --validate-config --config /data/config/config.toml

영구 저장소¶

모델 파일은 크기가 큽니다 (4~80+ GB). 컨테이너를 재시작해도 유지되도록 항상 명명된 볼륨이나 바인드 마운트를 사용하세요.

명명된 볼륨 (권장)¶

docker volume create aigo-models
docker volume create aigo-data

docker run -d \
  -v aigo-models:/data/models \
  -v aigo-data:/data \
  ghcr.io/lablup/backend-ai-go-server:latest

바인드 마운트 (파일시스템 직접 접근)¶

docker run -d \
  -v /mnt/storage/models:/data/models \
  -v /mnt/storage/data:/data \
  ghcr.io/lablup/backend-ai-go-server:latest

GPU 설정¶

NVIDIA GPU¶

NVIDIA Container Toolkit을 설치한 후 GPU 지원 컴포즈 파일을 사용합니다:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

또는 Docker로 직접 실행:

docker run -d \
  --gpus all \
  --name aigo-server \
  -p 8001:8001 \
  -p 8000:8000 \
  -v aigo-models:/data/models \
  ghcr.io/lablup/backend-ai-go-server:latest

GPU 접근 확인:

docker exec aigo-server nvidia-smi

AMD GPU (ROCm)¶

AMD GPU 지원을 위해 ROCm 디바이스 파일을 노출합니다:

docker run -d \
  --device /dev/kfd:/dev/kfd \
  --device /dev/dri:/dev/dri \
  --group-add video \
  --group-add render \
  --name aigo-server \
  -p 8001:8001 \
  -p 8000:8000 \
  -v aigo-models:/data/models \
  ghcr.io/lablup/backend-ai-go-server:latest

Apple Silicon

Apple Silicon(Metal) 가속은 macOS 네이티브 데스크톱 애플리케이션에서만 사용할 수 있습니다. Docker 이미지는 Linux(amd64)를 대상으로 하며 Metal을 지원하지 않습니다.

TLS / HTTPS¶

서버는 TLS를 직접 종료하지 않습니다. 앞에 리버스 프록시를 사용하세요.

nginx¶

server {
    listen 443 ssl http2;
    server_name aigo.example.com;

    ssl_certificate     /etc/ssl/certs/aigo.crt;
    ssl_certificate_key /etc/ssl/private/aigo.key;

    location / {
        proxy_pass         http://localhost:8001;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

Caddy (자동 HTTPS)¶

aigo.example.com {
    reverse_proxy localhost:8001
}

Traefik (Docker 레이블 사용)¶

docker-compose.yml의 aigo-server 서비스에 레이블을 추가합니다:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.aigo.rule=Host(`aigo.example.com`)"
  - "traefik.http.routers.aigo.entrypoints=websecure"
  - "traefik.http.routers.aigo.tls.certresolver=myresolver"
  - "traefik.http.services.aigo.loadbalancer.server.port=8001"

상태 모니터링¶

헬스 체크 엔드포인트¶

# 서버 상태 확인
curl http://localhost:8001/api/v1/health

# 예상 응답:
# {"status":"ok","version":"1.2.0"}

Docker 헬스 상태¶

docker inspect aigo-server --format='{{.State.Health.Status}}'

업데이트¶

새 이미지 가져오기¶

docker compose pull
docker compose up -d

업데이트 전 백업¶

# 데이터 볼륨 백업
docker run --rm \
  -v aigo-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/aigo-data-$(date +%Y%m%d).tar.gz /data

# 모델 목록 백업 (모델 파일 자체는 크기가 크므로 메타데이터만 백업)
docker exec aigo-server ls /data/models > models-list-$(date +%Y%m%d).txt

Kubernetes¶

프로덕션 Kubernetes 배포에는 k8s/ 디렉터리의 매니페스트를 사용합니다:

# 네임스페이스 생성 및 배포
kubectl apply -f k8s/persistent-volumes.yaml
kubectl apply -f k8s/secrets.yaml     # 실제 키로 먼저 편집
kubectl apply -f k8s/deployment.yaml

# 상태 확인
kubectl get pods -n aigo
kubectl logs -n aigo deploy/aigo-server

# 테스트용 포트 포워딩
kubectl port-forward -n aigo svc/aigo-server 8001:8001

Ingress 컨트롤러를 통한 HTTPS 설정:

kubectl apply -f k8s/ingress.yaml

Kubernetes에서 NVIDIA GPU 지원:

kubectl apply -f k8s/nvidia-gpu-deployment.yaml

문제 해결¶

컨테이너가 즉시 종료됨¶

# 컨테이너 로그 확인
docker logs aigo-server

# 일반적인 원인:
# - 포트 이미 사용 중: -p 8001:8001을 -p 8002:8001로 변경
# - 볼륨 권한 거부: 볼륨 소유권 확인
# - 잘못된 설정: 먼저 --validate-config 실행

모델 디렉터리 권한 오류¶

# 볼륨 소유권 수정
docker run --rm -u root \
  -v aigo-models:/data/models \
  debian:bookworm-slim \
  chown -R 1000:1000 /data/models

컨테이너 외부에서 접속 불가¶

컨테이너가 0.0.0.0에 바인딩되어 있는지 확인합니다 (127.0.0.1 아님):

docker run -d \
  -e AIGO_HOST=0.0.0.0 \
  -p 8001:8001 \
  ghcr.io/lablup/backend-ai-go-server:latest --external

방화벽에서 포트 8001에 대한 트래픽을 허용하는지 확인합니다.

GPU가 감지되지 않음¶

# NVIDIA: 툴킷 설치 확인
nvidia-container-cli --version
docker run --rm --gpus all nvidia/cuda:12.3-base-ubuntu22.04 nvidia-smi

# AMD: 디바이스 접근 확인
ls -la /dev/kfd /dev/dri