12.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. 서버 시작¶

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

2. 관리자 계정 생성¶

브라우저에서 http://localhost:8001에 접속합니다. 서버는 관리자 계정이 없는 것을 감지하고 초기 설정 화면을 표시합니다. 사용자 이름과 안전한 비밀번호(12자 이상, 숫자 또는 기호 포함)를 입력하면 즉시 관리자 계정이 생성되고 로그인됩니다.

이후 브라우저 방문 시에는 로그인 화면으로 이동합니다. SDK와 curl 클라이언트는 로그인 후 설정 > API 키에서 생성한 액세스 키와 X-API-Key 또는 Authorization: Bearer를 사용합니다.

Docker Compose¶

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

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

# 서버 시작
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_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