---
name: docker-deployment
description: Docker 이미지 빌드 및 배포 가이드
---
# Docker 배포 가이드
## 개요
이 skill은 MCP OpenDART 프로젝트를 Docker로 빌드하고 배포하는 방법을 설명합니다. streamable-http로 실행하여 원격 서버에서 사용할 수 있습니다.
## 사용 시나리오
- 원격 서버에 배포
- 프로덕션 환경 실행
- 컨테이너 기반 배포
- Docker 이미지 빌드 및 관리
## Dockerfile 구조
### 주요 단계
```dockerfile
# 1. Python 3.10-slim 베이스 이미지
FROM python:3.10-slim
# 2. 시스템 의존성 설치 (gcc 등)
RUN apt-get update && apt-get install -y gcc
# 3. 소스 코드 복사
COPY pyproject.toml README.md ./
COPY src/ ./src/
# 4. Python 패키지 설치
RUN pip install --no-cache-dir -e .
# 5. 서버 실행
CMD ["python", "-c", "from mcp_opendart.server import main; main()"]
```
### 중요 포인트
1. **소스 코드 복사 순서**
- `pyproject.toml`, `README.md` 먼저 복사
- `src/` 그 다음 복사
- `pip install`은 소스 코드 복사 후 실행
2. **CORPCODE.xml 포함**
- `.dockerignore`에서 예외 처리 필요
- 필수 데이터이므로 이미지에 포함
3. **CMD 실행 방식**
- `python -m mcp_opendart.server`는 작동하지 않음
- `python -c "from mcp_opendart.server import main; main()"` 사용
## 빌드 및 실행
### 1. 이미지 빌드
```bash
docker build -t mcp-opendart:latest .
```
### 2. 기본 실행
```bash
docker run -d \
--name mcp-opendart \
-p 8000:8000 \
-e OPENDART_API_KEY=your-api-key \
-e TRANSPORT=http \
mcp-opendart:latest
```
### 3. .env 파일 사용
```bash
# .env 파일 생성
cat > .env << EOF
OPENDART_API_KEY=your-api-key
TRANSPORT=http
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
EOF
# .env 파일로 실행
docker run -d \
--name mcp-opendart \
-p 8000:8000 \
--env-file .env \
mcp-opendart:latest
```
### 4. 캐시 데이터 볼륨 마운트
```bash
docker run -d \
--name mcp-opendart \
-p 8000:8000 \
-v $(pwd)/src/mcp_opendart/utils/data/disclosure_cache:/app/src/mcp_opendart/utils/data/disclosure_cache \
--env-file .env \
mcp-opendart:latest
```
## 환경 변수
### 필수 변수
- `OPENDART_API_KEY`: OpenDART API 키 (필수)
### 선택 변수
- `TRANSPORT`: "http" 또는 "stdio" (기본값: "stdio")
- `HOST`: 서버 호스트 (기본값: "0.0.0.0")
- `PORT`: 서버 포트 (기본값: 8000)
- `LOG_LEVEL`: 로깅 레벨 (기본값: "INFO")
- `MCP_SERVER_NAME`: 서버 이름 (기본값: "opendart-mcp")
## 문제 해결
### 1. 컨테이너가 시작되지 않음
**증상**: 컨테이너가 즉시 종료
**확인**:
```bash
docker logs mcp-opendart
```
**원인 및 해결**:
- `OPENDART_API_KEY` 누락 → 환경변수 확인
- `main()` 함수 호출 실패 → Dockerfile CMD 확인
- 모듈 import 실패 → 소스 코드 복사 확인
### 2. Tools가 0개로 표시됨
**증상**: `tools/list` 응답이 빈 배열
**확인**:
```bash
# 컨테이너 내부에서 모듈 import 테스트
docker exec -it mcp-opendart python -c "from mcp_opendart.tools import disclosure_tools; print('OK')"
# 로그에서 ImportError 확인
docker logs mcp-opendart | grep -i "import\|error"
```
**원인 및 해결**:
- Tool 모듈 import 실패 → `server.py`의 import 확인
- 경로 문제 → 소스 코드 복사 확인
### 3. CORPCODE.xml 파일 없음
**증상**: "CORPCODE.xml 파일이 없습니다" 에러
**확인**:
```bash
docker exec -it mcp-opendart ls -la /app/src/mcp_opendart/utils/data/CORPCODE.xml
```
**원인 및 해결**:
- `.dockerignore`에서 제외됨 → 예외 처리 확인
- 이미지 재빌드 필요
### 4. 컨테이너가 실행 중이지만 응답 없음
**증상**: 컨테이너는 실행 중이지만 HTTP 요청 실패
**확인**:
```bash
# 컨테이너 상태 확인
docker ps | grep mcp-opendart
# 포트 확인
docker port mcp-opendart
# 로그 확인
docker logs mcp-opendart --tail=50
```
**원인 및 해결**:
- 포트 매핑 오류 → `-p 8000:8000` 확인
- TRANSPORT 설정 → `TRANSPORT=http` 확인
- 서버 시작 실패 → 로그에서 에러 확인
## Docker Compose 사용
### docker-compose.yml
```yaml
version: '3.8'
services:
mcp-opendart:
build: .
container_name: mcp-opendart
ports:
- "8000:8000"
environment:
- OPENDART_API_KEY=${OPENDART_API_KEY}
- TRANSPORT=http
- HOST=0.0.0.0
- PORT=8000
- LOG_LEVEL=INFO
volumes:
- ./src/mcp_opendart/utils/data/disclosure_cache:/app/src/mcp_opendart/utils/data/disclosure_cache
restart: unless-stopped
```
### 실행
```bash
docker-compose up -d
```
## 프로덕션 배포 팁
### 1. 이미지 태깅
```bash
docker build -t mcp-opendart:v0.1.0 .
docker tag mcp-opendart:v0.1.0 mcp-opendart:latest
```
### 2. 이미지 저장소에 Push
```bash
docker tag mcp-opendart:latest your-registry/mcp-opendart:latest
docker push your-registry/mcp-opendart:latest
```
### 3. 원격 서버에서 실행
```bash
# 이미지 Pull
docker pull your-registry/mcp-opendart:latest
# 실행
docker run -d \
--name mcp-opendart \
-p 8000:8000 \
--env-file .env \
--restart unless-stopped \
your-registry/mcp-opendart:latest
```
### 4. 헬스체크
Dockerfile에 헬스체크 포함:
```dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD python -c "import requests; requests.get('http://localhost:${PORT}/mcp', timeout=5)" || exit 1
```
## 주의사항
1. **API 키 보안**
- 환경변수로만 전달
- `.env` 파일을 git에 커밋하지 않음
- Docker secrets 사용 고려 (프로덕션)
2. **캐시 데이터 관리**
- `disclosure_cache/`는 볼륨 마운트 권장
- 컨테이너 삭제 시 캐시 유지
3. **리소스 제한**
- 메모리 및 CPU 제한 설정 고려
- 대용량 XML 처리 시 메모리 필요
4. **로그 관리**
- 로그 볼륨 마운트 또는 로그 드라이버 사용
- 로그 로테이션 설정
5. **네트워크 설정**
- 방화벽 규칙 확인
- 포트 노출 최소화
## 관련 파일
- [Dockerfile](Dockerfile) - Docker 이미지 정의
- [.dockerignore](.dockerignore) - 빌드 제외 파일
- [src/mcp_opendart/server.py](src/mcp_opendart/server.py) - 서버 메인 로직
