Docker Compose 설치
로컬 개발 PC 또는 단일 호스트(베어메탈 / 자체 VM)에 quant-ai를 처음 올릴 때 따라야 할 절차입니다. Azure VM에 배포하는 경우는 Azure VM 배포로 이동하세요.
사전 요구 사항
- Docker Engine 24+ + Compose v2 플러그인
- 디스크 20GB+, 메모리 4GB+
- git
- 외부에 노출할 포트 5개 사용 가능:
5432,6379,3000,8000,3001
설치 전체 요구 사항은 설치 개요 참조.
1. 레포지토리 클론
git clone https://github.com/genonai/quant-ai.git
cd quant-ai
2. .env 작성
.env.example을 복사한 뒤, 반드시 다음 4개 변수를 채웁니다 — 빈 값으로
두면 컨테이너가 부팅되지 않거나, 부팅되더라도 라이브 모드 자체가 거부됩니다.
cp .env.example .env
$EDITOR .env
| 변수 | 최소 요구 | 비고 |
|---|---|---|
AUTH_SECRET_KEY | 32바이트 이상 임의 문자열 | JWT 서명 키 |
ENCRYPTION_SALT | 16바이트 이상 임의 문자열 | 거래소 키 Fernet 파생 솔트 |
LIVE_CONFIRM_SECRET | 비워두면 AUTH_SECRET_KEY 폴백 | 라이브 승급 HMAC 시크릿 |
TELEGRAM_TOKEN / TELEGRAM_CHAT_ID | 옵션 | 비우면 알림 비활성. 거래는 무영향 |
생성 예시:
python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
전체 변수 카탈로그는 환경변수 참조.
플레이스홀더 검증
EXCHANGE_API_KEY=your_api_key_here 같은 플레이스홀더 값이 그대로 남아
있으면 거래소 API가 401을 반환합니다. .env.example의 더미 값은 모두
지우거나 진짜 값으로 교체하세요. 자세한 내용은
브로커 401 참조.
3. 첫 부팅
전체 스택을 백그라운드로 띄웁니다.
docker compose up -d
처음 빌드는 5~10분이 소요됩니다 (PyTorch CPU + 종속성 설치). 이후 빌드는 캐시가 있어 30초 이내로 끝납니다.
4. DB 마이그레이션
스택은 부팅되지만, 첫 부팅에서는 alembic이 자동 실행되지 않습니다. 한 번만 수동으로 실행합니다.
docker compose exec api alembic upgrade head
기존 DB가 있는 deployment(또는 metadata.create_all로 만들어진 BTC 전용
스키마)에서 멀티자산으로 올라갈 때는 alembic stamp 00_baseline 후 upgrade
하세요. 자세한 내용은
Alembic 마이그레이션 참조.
5. 검증
# 컨테이너 모두 healthy
docker compose ps
# 기대 출력 (NAMES, STATUS):
# quantai-timescaledb Up (healthy)
# quantai-redis Up (healthy)
# quantai-grafana Up
# quantai-api Up (healthy)
# quantai-web Up
# quantai-analysis-worker Up
# quantai-position-reconciler Up
# API 헬스체크
curl -fsS http://localhost:8000/health
# {"status":"ok",...}
# 마이그레이션이 head
docker compose exec api alembic current
# 10_live_gating_tables (head)
# Grafana 접속 (admin/admin → 즉시 변경)
open http://localhost:3000 # macOS
# linux: xdg-open http://localhost:3000
6. 첫 로그인
웹 대시보드는 http://localhost:3001입니다. 사용자 계정 생성과 첫 분석
실행은 10분 퀵스타트로 이어집니다.
7. 운영자 추가 작업
| 작업 | 페이지 |
|---|---|
| Grafana 비밀번호 변경 | Grafana 대시보드 |
| Telegram 봇 등록 | Telegram 알림 |
| LLM 프록시 셋업 | LiteLLM 프록시 |
| 일일 헬스체크 cron | 헬스체크 cron |
운영 명령 치트 시트
# 로그 보기 (마지막 100줄, 컨테이너별)
docker compose logs --tail=100 -f api
# api 컨테이너 안에서 셸
docker compose exec api bash
# 단일 서비스 재시작
docker compose restart analysis-worker
# 전체 종료 (볼륨 보존)
docker compose down
# 전체 종료 + 볼륨 삭제 (데이터 소실, 주의)
docker compose down -v
# analysis-worker 3개로 스케일
docker compose up -d --scale analysis-worker=3
트러블슈팅
| 증상 | 원인 / 조치 |
|---|---|
api 가 unhealthy | docker compose logs api로 alembic 또는 DB 연결 실패 확인 → DB 마이그 실패 |
5432 포트 충돌 | 호스트 Postgres가 이미 떠 있음. docker-compose.yml에서 포트 매핑을 5433:5432로 변경 |
| Grafana 대시보드가 비어 있음 | TimescaleDB에 아직 데이터 없음. 분석/거래를 한 건 실행해 보고 새로고침 |
position-reconciler 가 즉시 종료 | DB 컬럼 부재. alembic upgrade head 실행 여부 확인 |