executor/DEPLOYMENT_GUIDE.md

# Docker 배포 가이드

## 📋 목차

1. [사전 요구사항](#사전-요구사항)
2. [빠른 시작](#빠른-시작)
3. [배포 파일 구조](#배포-파일-구조)
4. [배포 방법](#배포-방법)
5. [설정](#설정)
6. [유용한 명령어](#유용한-명령어)
7. [문제 해결](#문제-해결)

---

## 🔧 사전 요구사항

### 필수 소프트웨어
- **Docker**: 20.10 이상
- **Docker Compose**: 2.0 이상

### 설치 확인
```bash
docker --version
docker-compose --version
```

---

## 🚀 빠른 시작

### 1. 자동 배포 스크립트 사용

```bash
./deploy.sh
```

스크립트 실행 후 배포 모드 선택:
- `1` - Production (포트 8000)
- `2` - Development (포트 8001)
- `3` - 모두

### 2. 수동 배포

```bash
# 환경 변수 설정
cp .env.example .env
nano .env  # 필요한 설정 수정

# Docker 이미지 빌드 및 실행
docker-compose up -d web
```

### 3. 접속 확인

```bash
# Production
curl http://localhost:8000/strategies/

# Development
curl http://localhost:8001/strategies/
```

---

## 📁 배포 파일 구조

```
executor/
├── Dockerfile              # Docker 이미지 정의
├── docker-compose.yml      # 컨테이너 오케스트레이션
├── docker-entrypoint.sh    # 컨테이너 시작 스크립트
├── .dockerignore           # Docker 빌드 시 제외할 파일
├── .env.example            # 환경 변수 템플릿
├── deploy.sh               # 자동 배포 스크립트
└── DEPLOYMENT_GUIDE.md     # 이 파일
```

---

## 📦 배포 방법

### Production 배포

```bash
# 1. 이미지 빌드
docker-compose build web

# 2. 컨테이너 시작
docker-compose up -d web

# 3. 로그 확인
docker-compose logs -f web
```

**접속:** http://localhost:8000

### Development 배포

```bash
# Development 프로파일로 실행
docker-compose --profile dev up -d web-dev

# 로그 확인
docker-compose logs -f web-dev
```

**접속:** http://localhost:8001

### 동시 배포 (Production + Development)

```bash
docker-compose --profile dev up -d
```

---

## ⚙️ 설정

### 환경 변수 (.env)

```bash
# .env.example을 복사하여 시작
cp .env.example .env
```

**주요 설정:**

```bash
# Django 보안
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com

# 환경
DJANGO_ENV=production

# 타임존
TIME_ZONE=Asia/Seoul
```

### Docker Compose 설정

**포트 변경:**
```yaml
services:
  web:
    ports:
      - "9000:8000"  # 외부:내부
```

**Worker 수 조정:**
```yaml
services:
  web:
    command: gunicorn --bind 0.0.0.0:8000 --workers 8 executor.wsgi:application
```

**볼륨 추가:**
```yaml
services:
  web:
    volumes:
      - ./data:/app/data
```

---

## 🛠️ 유용한 명령어

### 컨테이너 관리

```bash
# 컨테이너 상태 확인
docker-compose ps

# 컨테이너 중지
docker-compose down

# 컨테이너 재시작
docker-compose restart web

# 컨테이너 완전 제거 (볼륨 포함)
docker-compose down -v
```

### 로그 확인

```bash
# 실시간 로그
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f web

# 마지막 100줄
docker-compose logs --tail=100 web
```

### Django 명령어 실행

```bash
# 마이그레이션
docker-compose exec web python manage.py migrate

# 전략 초기화
docker-compose exec web python manage.py init_strategies

# 슈퍼유저 생성
docker-compose exec web python manage.py createsuperuser

# Shell 접속
docker-compose exec web python manage.py shell

# 전략 목록 확인
docker-compose exec web python list_strategies.py
```

### 데이터베이스 백업

```bash
# SQLite 백업
docker-compose exec web sqlite3 /app/db.sqlite3 .dump > backup.sql

# 복원
cat backup.sql | docker-compose exec -T web sqlite3 /app/db.sqlite3
```

### 이미지 관리

```bash
# 이미지 재빌드 (캐시 무시)
docker-compose build --no-cache web

# 이미지 정리
docker image prune -a

# 미사용 리소스 정리
docker system prune -a
```

---

## 🔍 문제 해결

### 1. 포트가 이미 사용 중인 경우

**증상:**
```
Error: bind: address already in use
```

**해결:**
```bash
# 사용 중인 프로세스 확인
lsof -i :8000

# docker-compose.yml에서 포트 변경
ports:
  - "8001:8000"
```

### 2. 마이그레이션 오류

**증상:**
```
django.db.utils.OperationalError: no such table
```

**해결:**
```bash
# 컨테이너에서 마이그레이션 재실행
docker-compose exec web python manage.py migrate --run-syncdb

# 또는 DB 초기화
docker-compose down -v
docker-compose up -d
```

### 3. 전략이 초기화되지 않음

**해결:**
```bash
# 수동으로 전략 초기화
docker-compose exec web python manage.py init_strategies

# 컨테이너 재시작
docker-compose restart web
```

### 4. 정적 파일이 로드되지 않음

**해결:**
```bash
# 정적 파일 수집
docker-compose exec web python manage.py collectstatic --noinput

# 권한 확인
docker-compose exec web ls -la /app/staticfiles/
```

### 5. 컨테이너가 즉시 종료됨

**확인:**
```bash
# 로그에서 오류 확인
docker-compose logs web

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

### 6. Health check 실패

**증상:**
```
Status: unhealthy
```

**해결:**
```bash
# 수동으로 health check 테스트
docker-compose exec web curl -f http://localhost:8000/strategies/

# health check 비활성화 (임시)
# docker-compose.yml에서 healthcheck 섹션 주석 처리
```

---

## 🔐 보안 권장사항

### Production 환경

1. **SECRET_KEY 변경**
   ```bash
   # .env 파일에서 반드시 변경
   DJANGO_SECRET_KEY=$(python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())')
   ```

2. **DEBUG 모드 비활성화**
   ```bash
   DJANGO_DEBUG=False
   ```

3. **ALLOWED_HOSTS 설정**
   ```bash
   DJANGO_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
   ```

4. **방화벽 설정**
   ```bash
   # 필요한 포트만 개방
   ufw allow 8000/tcp
   ```

---

## 📊 모니터링

### 컨테이너 리소스 사용량

```bash
# 실시간 모니터링
docker stats

# 특정 컨테이너
docker stats quantbench-executor
```

### 디스크 사용량

```bash
# Docker 전체 사용량
docker system df

# 상세 정보
docker system df -v
```

---

## 🔄 업데이트

### 코드 업데이트

```bash
# 1. Git에서 최신 코드 가져오기
git pull origin main

# 2. 이미지 재빌드
docker-compose build web

# 3. 컨테이너 재시작
docker-compose up -d web

# 4. 마이그레이션 실행
docker-compose exec web python manage.py migrate
```

### Rolling 업데이트 (무중단 배포)

```bash
# 1. 새 컨테이너 시작
docker-compose up -d --scale web=2 --no-recreate

# 2. 헬스 체크 확인
docker-compose ps

# 3. 이전 컨테이너 종료
docker-compose up -d --scale web=1
```

---

## 📝 추가 정보

### BAA 전략 테스트

```bash
# 컨테이너 내부에서 테스트
docker-compose exec web python test_baa.py

# API 테스트
docker-compose exec web bash baa_api_examples.sh
```

### 전략 목록 확인

```bash
docker-compose exec web python list_strategies.py
```

---

## 🆘 지원

문제가 발생하면:
1. 로그 확인: `docker-compose logs -f`
2. 컨테이너 상태: `docker-compose ps`
3. GitHub Issues에 보고

---

## 📚 참고 문서

- [Django Deployment Checklist](https://docs.djangoproject.com/en/5.2/howto/deployment/checklist/)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
- [Gunicorn Documentation](https://docs.gunicorn.org/)