# 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/)