본문으로 건너뛰기

Windows Docker 배포 환경 설정

등록일: 2026-04-26

1. 개요​

NEXUS 프로젝트를 도커 컨테이너 기반의 배포 환경으로 전환하기 위한 로컬 개발 환경 구축 가이드임. 로컬 윈도우 환경에서 도커 이미지를 빌드하고 검증할 수 있는 환경을 조성하는 것을 목적으로 함.

2. 필수 구성 요소 설치​

2.1. VS Code Extension​

  • Docker: Dockerfile 및 docker-compose.yml 문법 하이라이팅, 컨테이너 관리 기능을 제공함.
  • WSL: VS Code에서 WSL 리눅스 환경에 직접 접속하여 개발할 수 있게 함.

2.2. Docker Desktop 설치​

  • 설치 방식: 설치 파일 우클릭 후 '관리자 권한으로 실행' 필수.
  • 설정 주의사항:
    • Use WSL 2 instead of Hyper-V: 반드시 체크함.
    • Allow Windows containers...: 리눅스 기반 배포가 목적이므로 체크하지 않음.

3. WSL2 리소스 최적화 (.wslconfig)​

WSL2가 윈도우 램을 과도하게 점유하여 게임(WoW 등)이나 다른 작업에 지장을 주는 것을 방지하기 위해 상한선을 설정함.

3.1. 설정 파일 생성​

  • 경로: C:\Users\{사용자명}\.wslconfig (예: C:\Users\이현석\.wslconfig)
  • 내용:
[wsl2]
# WSL2가 사용할 최대 메모리 제한 (전체 램 용량에 따라 조절, 4~8GB 권장)
memory=6GB

# 사용하지 않는 메모리를 윈도우로 자동 반납
autoMemoryReclaim=gradual

# GUI 앱 지원이 필요 없는 경우 리소스 절약을 위해 비활성화
guiApplications=false

3.2. 설정 적용​

  • 설정 파일 저장 후 터미널(CMD/PowerShell)에서 아래 명령어 실행하여 WSL 종료.
wsl --shutdown
  • Docker Desktop을 재시작하면 설정이 적용됨.

4. 로컬 빌드 및 실행 테스트​

도커 이미지를 빌드하고 로컬 환경에서 컨테이너를 구동하여 정상 동작 여부를 확인함. 모든 명령어는 프로젝트 루트(nexus/) 경로에서 실행해야 함.

4.1. Docker 이미지 빌드​

모듈별 Dockerfile 경로를 지정하여 이미지를 생성함.

# 1. System 모듈 빌드
docker build -t nexus-system:docker-local -f module-system/Dockerfile .

# 2. Workout 모듈 빌드
docker build -t nexus-workout:docker-local -f module-workout/Dockerfile .

# 3. Raid 모듈 빌드
docker build -t nexus-raid:docker-local -f module-raid/Dockerfile .

# 4. AI Bot Toolkit 빌드
docker build -t nexus-aibot-toolkit:docker-local -f module-aibot/aibot-toolkit/Dockerfile .

# 5. AI Bot Interface 빌드
docker build -t nexus-aibot-iface:docker-local -f module-aibot/aibot-iface/Dockerfile .

4.2. 컨테이너 실행 (Git Bash 기준)​

윈도우 Git Bash 환경에서 실행 시, 볼륨 마운트 경로는 //c/ 형식을 사용해야 함. secrets 폴더를 연결하여 로컬 설정을 주입함.

# System 컨테이너 (8001)
docker run --rm -p 8001:8001 \
  -e SPRING_PROFILES_ACTIVE=docker-local \
  -v "//c/dev/workspaces/nexus/secrets:/app/secrets" \
  nexus-system:docker-local

# Workout 컨테이너 (8003)
docker run --rm -p 8003:8003 \
  -e SPRING_PROFILES_ACTIVE=docker-local \
  -v "//c/dev/workspaces/nexus/secrets:/app/secrets" \
  nexus-workout:docker-local

# Raid 컨테이너 (8009)
docker run --rm -p 8009:8009 \
  -e SPRING_PROFILES_ACTIVE=docker-local \
  -v "//c/dev/workspaces/nexus/secrets:/app/secrets" \
  nexus-raid:docker-local

# AI Bot Interface 컨테이너 (8002)
docker run --rm -p 8002:8002 \
  -e SPRING_PROFILES_ACTIVE=docker-local \
  -v "//c/dev/workspaces/nexus/secrets:/app/secrets" \
  nexus-aibot-iface:docker-local

# AI Bot Toolkit 컨테이너 (8005)
docker run --rm -p 8005:8005 \
  -e SPRING_PROFILES_ACTIVE=docker-local \
  -v "//c/dev/workspaces/nexus/secrets:/app/secrets" \
  nexus-aibot-toolkit:docker-local

5. 향후 개발 워크플로우​

5.1. 브랜치 전략​

  • 도커 관련 작업은 반드시 별도의 브랜치(예: feature/docker-deployment)를 생성하여 진행함.
  • main 브랜치에 직접 수정하지 않고 Pull Request(PR)를 통해 검증 후 합침.

5.2. 빌드 및 배포 테스트​

  • 로컬 검증: 로컬 도커 환경에서 상기 명령어로 정상 구동 확인.
  • 이미지 저장소: 비공개(Private) 설정을 위해 GitHub Container Registry(GHCR) 사용 권장.
  • 자동 배포: GitHub Actions를 연동하여 특정 시점(PR 머지 또는 수동 트리거)에 배포 자동화 구현.

주의: 윈도우 환경에서 볼륨 경로(-v) 지정 시 드라이브 문자 앞의 슬래시 개수(//c/)에 주의할 것. 또한 wslconfig를 통한 메모리 제한은 시스템 전체 성능 유지를 위해 필수적임.