feat: 프로젝트 기본 구조 구축

2025-10-04 22:11:32 +09:00
parent 01403c7df4
commit ab99abad8a
36 changed files with 32356 additions and 199 deletions
--- a/DEPLOYMENT_GUIDE.md
+++ b/DEPLOYMENT_GUIDE.md
@@ -0,0 +1,448 @@
+# 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/)