본문으로 건너뛰기

Docker 배포 가이드

Caffeine Framework 애플리케이션을 Docker로 컨테이너화하는 가이드입니다.

📋 개요​

Docker를 사용하여 Caffeine 드라이버 및 애플리케이션을 배포합니다.

학습 시간: 30분 난이도: ⭐⭐ 중급

⚡ 원클릭 배포 (권장)​

cafe setup 위자드를 사용하면 Docker 설치 확인부터 서비스 시작까지 자동으로 처리됩니다.

# 1. Caffeine CLI 설치
dotnet tool install -g NEXCODE.Caffeine.Cli

# 2. 대화형 위자드 실행
cafe setup

위자드가 프로파일 선택, .env 생성, Compose 실행을 단계별로 안내합니다. 자세한 내용은 배포 위자드 가이드를 참조하세요.

아래 섹션은 고급 Docker 설정이 필요한 경우를 위한 참조 가이드입니다.

🐳 Dockerfile 작성​

드라이버 Dockerfile​

FROM mcr.microsoft.com/dotnet/runtime:10.0 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["src/MyDriver/MyDriver.csproj", "src/MyDriver/"]
RUN dotnet restore "src/MyDriver/MyDriver.csproj"
COPY . .
WORKDIR "/src/src/MyDriver"
RUN dotnet build "MyDriver.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "MyDriver.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD dotnet MyDriver.dll --health-check || exit 1

ENTRYPOINT ["dotnet", "MyDriver.dll"]

Multi-stage build 최적화​

# Builder stage
FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS builder
WORKDIR /source

# Restore dependencies (cached layer)
COPY *.sln .
COPY src/MyDriver/*.csproj ./src/MyDriver/
RUN dotnet restore

# Copy everything and build
COPY src/ ./src/
WORKDIR /source/src/MyDriver
RUN dotnet publish -c Release -o /app --no-restore

# Runtime stage (minimal image)
FROM mcr.microsoft.com/dotnet/runtime:10.0-alpine
WORKDIR /app
COPY --from=builder /app ./

# Non-root user for security
RUN addgroup -g 1000 caffeine && \
    adduser -D -u 1000 -G caffeine caffeine && \
    chown -R caffeine:caffeine /app

USER caffeine

ENTRYPOINT ["dotnet", "MyDriver.dll"]

🏗️ Docker Compose (프로파일 기반)​

Caffeine은 5개 프로파일로 구성된 통합 docker-compose.yml을 제공합니다. 배포 파일은 cafe setup extract로 추출하거나, CLI에 내장되어 cafe setup 실행 시 자동으로 사용됩니다.

프로파일별 실행​

# minimal: 드라이버 개발 최소 환경
docker compose --profile minimal up -d

# standard: 표준 개발환경 (권장)
docker compose --profile standard up -d

# full: 전체 기능 + Grafana
docker compose --profile full up -d

# full+monitoring: 운영 모니터링 포함
docker compose --profile "full+monitoring" up -d

# app: Caffeine 앱 이미지 포함
docker compose --profile app up -d

Production 오버레이 적용​

docker-compose.prod.yml은 리소스 제한, 로그 로테이션, 재시작 정책을 적용하는 오버레이입니다:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.prod.yml \
  --profile standard up -d

cafe setup --mode production 실행 시 자동으로 적용됩니다.

.env 파일과 시크릿 관리​

cafe setup은 .env 파일을 암호학적으로 안전한 랜덤 시크릿으로 자동 생성합니다. 수동 관리 시:

# .env.example에서 복사
cp .env.example .env

# 시크릿 직접 설정 (절대 기본값 사용 금지!)
JWT_SECRET=$(openssl rand -base64 32)
INFLUXDB_ADMIN_TOKEN=$(openssl rand -base64 32)
보안 경고

.env 파일에 admin123, changeme, password 등 기본값을 절대 사용하지 마세요. cafe setup --mode production의 보안 체크리스트에서 자동 탐지합니다.

🚀 배포​

기본 명령어​

# 서비스 시작 (cafe setup 권장)
cafe setup

# 또는 직접 Compose 실행
docker compose --profile standard up -d

# 로그 확인
docker compose logs -f

# 특정 서비스 재시작
docker compose restart caffeine-engine

# 상태 확인 (cafe setup 사용)
cafe setup status

# 서비스 중지
cafe setup down

# 볼륨까지 삭제
docker compose down -v

개별 이미지 빌드​

# 드라이버 빌드
docker build -t mycompany/modbus-driver:latest -f Dockerfile .

# 실행
docker run -d \
  --name modbus-driver \
  -e Caffeine__ServerUrl=http://192.168.1.10:5001 \
  -e Driver__Host=192.168.1.100 \
  mycompany/modbus-driver:latest

📊 모니터링​

Healthcheck​

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:5001/health || exit 1

Docker Stats​

# 실시간 리소스 사용량
docker stats

# JSON 형식
docker stats --format "{{.Container}}: {{.CPUPerc}} {{.MemUsage}}"

🔒 보안 모범 사례​

1. 비root 사용자​

RUN addgroup -g 1000 caffeine && \
    adduser -D -u 1000 -G caffeine caffeine
USER caffeine

2. Secrets 관리​

services:
  caffeine-server:
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    file: ./secrets/api_key.txt

3. 읽기 전용 파일시스템​

services:
  caffeine-server:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

📚 참고 자료​

작성일: 2026-01-28 최종 업데이트: 2026-03-02 버전: 2.0.7