Docker로 LLM 환경 구축

Docker 기본 설정

Docker 설치

macOS

# Docker Desktop 설치
brew install --cask docker

# 또는 https://www.docker.com/products/docker-desktop/ 에서 다운로드

# Docker Desktop 실행 후 확인
docker --version
docker compose version

Ubuntu/Debian

# 1. 이전 버전 제거
sudo apt remove docker docker-engine docker.io containerd runc

# 2. 저장소 설정
sudo apt update
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 3. Docker 설치
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 4. 사용자를 docker 그룹에 추가 (sudo 없이 사용)
sudo usermod -aG docker $USER
newgrp docker

# 5. 확인
docker run hello-world

Windows

# Docker Desktop 다운로드 및 설치
# https://www.docker.com/products/docker-desktop/

# WSL 2 백엔드 사용 (권장)
# Settings → General → Use WSL 2 based engine

# PowerShell에서 확인
docker --version
docker compose version

Docker 설정 최적화

macOS Docker Desktop 리소스 설정

# Docker Desktop → Settings → Resources

# 권장 설정 (LLM 워크로드용)
CPUs: 4-8 (시스템 코어의 50-75%)
Memory: 8-16 GB (LLM 모델 크기에 따라)
Swap: 2 GB
Disk image size: 100 GB+

Linux 데몬 설정 (/etc/docker/daemon.json)

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "default-runtime": "runc"
}

# 적용
sudo systemctl restart docker

Docker Compose v2와 Buildx 심화

Compose v2 핵심 정리

Compose v2는 별도 바이너리(docker-compose)가 아니라 Docker CLI 플러그인으로 통합됩니다. 실무에서는 docker compose 명령을 표준으로 사용하고, 프로젝트/환경별 설정을 파일 분리로 관리하는 패턴이 가장 안정적입니다.

# 버전/플러그인 확인
docker compose version
docker buildx version

# 현재 Compose 설정 렌더링 (병합 결과 확인)
docker compose config

# 프로젝트 단위 상태 확인
docker compose ps
docker compose ls

Compose v2 운영 패턴

1. 파일 분리 (기본 + 오버라이드)

# 기본 파일
docker compose -f compose.yml up -d

# 운영 파일 병합
docker compose -f compose.yml -f compose.prod.yml up -d

2. 프로필 기반 실행

# compose.yml
services:
  app:
    image: my-llm-app:latest
    ports:
      - "8000:8000"

  monitoring:
    image: prom/prometheus:latest
    profiles: ["ops"]

# 기본 서비스만 실행
docker compose up -d

# ops 프로필 포함 실행
docker compose --profile ops up -d

3. 프로젝트명 고정

# 같은 서버에서 스택 충돌 방지
docker compose -p llm-dev up -d
docker compose -p llm-prod up -d

Buildx 핵심 개념

Buildx는 BuildKit 기반의 고급 빌드 도구입니다. 멀티 아키텍처 이미지 빌드, 원격 캐시, 병렬 빌드, 빌드 결과 내보내기를 표준화할 수 있어 CI/CD 환경에서 특히 중요합니다.

# 빌더 목록 확인
docker buildx ls

# 전용 빌더 생성 및 사용
docker buildx create --name llm-builder --use
docker buildx inspect --bootstrap

# 단일 플랫폼 테스트 빌드 (로컬 로드)
docker buildx build --platform linux/amd64 -t my-llm-app:dev --load .

멀티 아키텍처 이미지 빌드

# Docker Hub로 멀티 아키텍처 푸시
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t username/my-llm-app:latest \
  --push .

Apple Silicon(M 시리즈) 개발 환경과 x86_64 서버를 함께 쓰는 팀에서는 linux/amd64,linux/arm64 멀티 플랫폼 태그를 기본 배포 전략으로 잡으면 "내 로컬에선 되는데 서버에서 안 됨" 문제를 크게 줄일 수 있습니다.

Buildx 캐시 전략

# 레지스트리 캐시 사용 예시
docker buildx build \
  --platform linux/amd64 \
  --cache-from type=registry,ref=username/my-llm-app:buildcache \
  --cache-to type=registry,ref=username/my-llm-app:buildcache,mode=max \
  -t username/my-llm-app:latest \
  --push .

의존성 설치 단계(npm ci, pip install)를 Dockerfile 상단에 배치하고, 앱 소스 복사는 뒤로 미루면 캐시 히트율이 올라 빌드 시간이 줄어듭니다.

Buildx Bake로 빌드 선언형 관리

docker-bake.hcl

group "default" {
  targets = ["app"]
}

target "app" {
  context = "."
  dockerfile = "Dockerfile"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["username/my-llm-app:latest"]
}

# Bake 실행
docker buildx bake --push

# 오버라이드 파일과 함께 실행 가능
docker buildx bake -f docker-bake.hcl -f docker-bake.prod.hcl --push

Docker로 Ollama 실행

기본 실행

# 1. Ollama 이미지 다운로드 및 실행 (CPU 전용)
docker run -d \
  --name ollama \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama

# 2. 컨테이너 상태 확인
docker ps

# 3. 로그 확인
docker logs ollama

# 4. 모델 다운로드
docker exec -it ollama ollama pull llama3.2:3b

# 5. 대화형 실행
docker exec -it ollama ollama run llama3.2:3b

# 6. API 테스트
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2:3b",
  "prompt": "Why is the sky blue?",
  "stream": false
}'

Docker Compose로 관리

docker-compose.yml

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped
    environment:
      - OLLAMA_HOST=0.0.0.0:11434
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  ollama-data:
    driver: local

사용법

# 시작
docker compose up -d

# 로그 확인
docker compose logs -f ollama

# 중지
docker compose down

# 데이터 포함 완전 삭제
docker compose down -v

# 모델 다운로드
docker compose exec ollama ollama pull llama3.2:3b
docker compose exec ollama ollama pull codellama:7b
docker compose exec ollama ollama pull mistral:7b

# 설치된 모델 확인
docker compose exec ollama ollama list

GPU 가속 (NVIDIA)

1. NVIDIA Docker Runtime 설치 (Linux)

# NVIDIA Container Toolkit 설치
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update
sudo apt install -y nvidia-container-toolkit

# Docker 데몬 설정
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 테스트
docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi

2. GPU 지원 docker-compose.yml

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-gpu
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all  # 또는 1 (GPU 1개만)
              capabilities: [gpu]
    environment:
      - OLLAMA_HOST=0.0.0.0:11434
      - OLLAMA_GPU_LAYERS=999  # 모든 레이어를 GPU에

volumes:
  ollama-data:

3. GPU 사용 확인

# 컨테이너 내부에서 nvidia-smi 실행
docker compose exec ollama nvidia-smi

# Ollama 로그에서 GPU 사용 확인
docker compose logs ollama | grep -i gpu
# 출력 예시: "GPU detected: NVIDIA GeForce RTX 4090"

# 모델 실행 시 GPU 사용률 모니터링
watch -n 1 nvidia-smi

개발 환경 컨테이너화

Python LLM 개발 환경

Dockerfile

# Dockerfile
FROM python:3.12-slim

# 작업 디렉토리 설정
WORKDIR /app

# 시스템 패키지 설치
RUN apt-get update && apt-get install -y \
    curl \
    git \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Python 의존성 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 애플리케이션 코드 복사
COPY . .

# 비root 사용자 생성
RUN useradd -m -u 1000 appuser && \
    chown -R appuser:appuser /app
USER appuser

# 포트 노출
EXPOSE 8000

# 시작 명령어
CMD ["python", "app.py"]

requirements.txt

# LLM 클라이언트
anthropic==0.18.1
openai==1.12.0
google-generativeai==0.3.2

# 로컬 LLM
ollama==0.1.6

# 웹 프레임워크
fastapi==0.109.2
uvicorn[standard]==0.27.1

# 유틸리티
python-dotenv==1.0.1
httpx==0.26.0
pydantic==2.6.1

docker-compose.yml (개발 환경)

version: '3.8'

services:
  app:
    build: .
    container_name: llm-dev
    ports:
      - "8000:8000"
    volumes:
      - .:/app                    # 코드 hot reload
      - /app/__pycache__          # 캐시 제외
      - /app/.venv                # venv 제외
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OLLAMA_HOST=http://ollama:11434
      - PYTHONUNBUFFERED=1
    depends_on:
      - ollama
    command: uvicorn app:app --host 0.0.0.0 --port 8000 --reload

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama

volumes:
  ollama-data:

app.py (예제)

from fastapi import FastAPI
from pydantic import BaseModel
import anthropic
import os

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    model: str = "claude-"

@app.post("/chat")
async def chat(request: ChatRequest):
    client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

    message = client.messages.create(
        model=request.model,
        max_tokens=1024,
        messages=[{"role": "user", "content": request.message}]
    )

    return {"response": message.content[0].text}

@app.get("/health")
async def health():
    return {"status": "healthy"}

사용법

# .env 파일 생성
cat > .env << EOF
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
EOF

# 빌드 및 시작
docker compose up --build

# API 테스트
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, Claude!"}'

# 로그 확인
docker compose logs -f app

Node.js LLM 개발 환경

Dockerfile

# Dockerfile
FROM node:20-slim

WORKDIR /app

# 의존성 설치
COPY package*.json ./
RUN npm ci --only=production

# 애플리케이션 코드
COPY . .

# TypeScript 빌드 (필요 시)
# RUN npm run build

EXPOSE 3000

CMD ["node", "server.js"]

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OLLAMA_HOST=http://ollama:11434
    depends_on:
      - ollama
    command: npm run dev

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama

volumes:
  ollama-data:

볼륨 관리

볼륨 유형

볼륨 사용 예제

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    volumes:
      # Named volume (모델 영구 저장)
      - ollama-models:/root/.ollama/models

      # Bind mount (커스텀 Modelfile)
      - ./modelfiles:/modelfiles:ro

      # tmpfs (임시 캐시)
      - type: tmpfs
        target: /tmp
        tmpfs:
          size: 1G

volumes:
  ollama-models:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/ssd/ollama  # SSD 경로

볼륨 관리 명령어

# 볼륨 목록
docker volume ls

# 볼륨 상세 정보
docker volume inspect ollama-data

# 볼륨 백업
docker run --rm \
  -v ollama-data:/source \
  -v $(pwd):/backup \
  alpine tar czf /backup/ollama-backup.tar.gz -C /source .

# 볼륨 복원
docker run --rm \
  -v ollama-data:/target \
  -v $(pwd):/backup \
  alpine tar xzf /backup/ollama-backup.tar.gz -C /target

# 볼륨 삭제 (주의!)
docker volume rm ollama-data

# 사용하지 않는 볼륨 정리
docker volume prune

자동 백업 스크립트

#!/bin/bash
# backup-ollama.sh

BACKUP_DIR="$HOME/backups/ollama"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/ollama-$DATE.tar.gz"

mkdir -p "$BACKUP_DIR"

docker run --rm \
  -v ollama-data:/source \
  -v "$BACKUP_DIR":/backup \
  alpine tar czf /backup/"ollama-$DATE.tar.gz" -C /source .

echo "✅ Backup completed: $BACKUP_FILE"

# 30일 이상 된 백업 삭제
find "$BACKUP_DIR" -name "ollama-*.tar.gz" -mtime +30 -delete

# cron에 등록 (매일 새벽 2시)
crontab -e
# 추가:
0 2 * * * /path/to/backup-ollama.sh

네트워킹

네트워크 유형

커스텀 네트워크 예제

version: '3.8'

services:
  frontend:
    build: ./frontend
    networks:
      - public
      - internal
    ports:
      - "3000:3000"

  backend:
    build: ./backend
    networks:
      - internal
    environment:
      - OLLAMA_HOST=http://ollama:11434

  ollama:
    image: ollama/ollama:latest
    networks:
      - internal
    volumes:
      - ollama-data:/root/.ollama

networks:
  public:
    driver: bridge
  internal:
    driver: bridge
    internal: true  # 외부 접근 차단

volumes:
  ollama-data:

네트워크 관리 명령어

# 네트워크 목록
docker network ls

# 네트워크 생성
docker network create llm-network

# 컨테이너를 네트워크에 연결
docker network connect llm-network ollama

# 네트워크 상세 정보
docker network inspect llm-network

# 네트워크에서 분리
docker network disconnect llm-network ollama

# 네트워크 삭제
docker network rm llm-network

멀티 서비스 구성

풀스택 LLM 애플리케이션

docker-compose.yml (프로덕션)

version: '3.8'

services:
  # Nginx 리버스 프록시
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      - frontend
      - backend
    networks:
      - public

  # React 프론트엔드
  frontend:
    build: ./frontend
    expose:
      - "3000"
    networks:
      - public

  # FastAPI 백엔드
  backend:
    build: ./backend
    expose:
      - "8000"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OLLAMA_HOST=http://ollama:11434
      - DATABASE_URL=postgresql://user:pass@postgres:5432/llmdb
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis
      - ollama
    networks:
      - public
      - backend

  # Ollama LLM 서버
  ollama:
    image: ollama/ollama:latest
    expose:
      - "11434"
    volumes:
      - ollama-data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - backend

  # PostgreSQL 데이터베이스
  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=llmdb
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - backend

  # Redis 캐시
  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data
    networks:
      - backend

networks:
  public:
    driver: bridge
  backend:
    driver: bridge
    internal: true

volumes:
  ollama-data:
  postgres-data:
  redis-data:

nginx.conf

upstream frontend {
    server frontend:3000;
}

upstream backend {
    server backend:8000;
}

server {
    listen 80;
    server_name example.com;

    # 프론트엔드
    location / {
        proxy_pass http://frontend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 백엔드 API
    location /api/ {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # 스트리밍 지원
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

프로덕션 배포

프로덕션 Dockerfile 최적화

멀티 스테이지 빌드

# ========== Stage 1: Build ==========
FROM node:20-alpine AS builder

WORKDIR /app

# 의존성 설치
COPY package*.json ./
RUN npm ci

# 빌드
COPY . .
RUN npm run build

# ========== Stage 2: Production ==========
FROM node:20-alpine

WORKDIR /app

# 프로덕션 의존성만 설치
COPY package*.json ./
RUN npm ci --only=production

# 빌드 결과물만 복사
COPY --from=builder /app/dist ./dist

# 보안: 비root 사용자
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001
USER nodejs

# 헬스체크
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node healthcheck.js

EXPOSE 3000

CMD ["node", "dist/server.js"]

프로덕션 Compose 설정

# docker-compose.prod.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    restart: always
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
        max_attempts: 3
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

보안 강화

1. 시크릿 관리 (Docker Swarm)

# 시크릿 생성
echo "sk-ant-api03-..." | docker secret create anthropic_key -

# docker-compose.yml
version: '3.8'

services:
  app:
    image: myapp:latest
    secrets:
      - anthropic_key
    environment:
      - ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_key

secrets:
  anthropic_key:
    external: true

2. 읽기 전용 파일 시스템

services:
  app:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

3. 리소스 제한

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G

모니터링

# docker-compose.monitoring.yml
version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana-data:/var/lib/grafana

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    ports:
      - "8080:8080"

volumes:
  prometheus-data:
  grafana-data:

문제 해결

일반적인 문제

1. 컨테이너가 시작되지 않음

# 로그 확인
docker compose logs app

# 컨테이너 상태 확인
docker ps -a

# 이미지 재빌드
docker compose build --no-cache app
docker compose up app

2. 볼륨 권한 문제

# 볼륨 소유권 변경
docker run --rm \
  -v ollama-data:/data \
  alpine chown -R 1000:1000 /data

# Dockerfile에서 USER 지정
RUN chown -R appuser:appuser /app
USER appuser

3. GPU가 인식되지 않음

# NVIDIA Docker Runtime 확인
docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi

# 데몬 설정 확인
cat /etc/docker/daemon.json

# Docker 재시작
sudo systemctl restart docker

4. 네트워크 연결 문제

# 컨테이너 간 핑 테스트
docker compose exec app ping ollama

# DNS 확인
docker compose exec app nslookup ollama

# 네트워크 재생성
docker compose down
docker network prune
docker compose up -d

성능 최적화

# 1. 빌드 캐시 활용
# Dockerfile에서 자주 변경되지 않는 것을 먼저 COPY
COPY package*.json ./
RUN npm install
COPY . .

# 2. .dockerignore 사용
# .dockerignore
node_modules
.git
.env
*.log

# 3. 멀티 스테이지 빌드로 이미지 크기 축소
# 최종 이미지에 필요한 파일만 포함

베스트 프랙티스

• 작은 베이스 이미지: alpine 또는 slim 사용
• 멀티 스테이지 빌드: 빌드 의존성 제외
• .dockerignore: 불필요한 파일 제외
• 레이어 최적화: RUN 명령어 결합
• 캐시 활용: 자주 변경되는 것을 마지막에 COPY
• 비root 사용자: 보안 강화
• 헬스체크: 컨테이너 상태 모니터링
• 로깅: 로그 로테이션 설정
• 리소스 제한: CPU/메모리 제한
• 시크릿 관리: 환경 변수 또는 Secrets 사용

핵심 정리

• Docker로 LLM 환경 구축의 핵심 개념과 흐름을 정리합니다.
• Docker 기본 설정를 단계별로 이해합니다.
• Compose v2 운영 패턴과 Buildx 기반 멀티 아키텍처 빌드 전략을 적용합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.

실무 팁

• 입력/출력 예시를 고정해 재현성을 확보하세요.
• Docker로 LLM 환경 구축 범위를 작게 잡고 단계적으로 확장하세요.
• docker compose config로 병합 결과를 항상 확인해 배포 차이를 줄이세요.
• buildx 캐시를 CI에 연결해 빌드 시간을 안정적으로 단축하세요.
• Docker 기본 설정 조건을 문서화해 대응 시간을 줄이세요.