설치

quant-ai 스택을 새 환경에 올리기 위한 단계별 가이드입니다. 본 페이지는 요구 사항과 구성도를 다루며, 실제 명령은 하위 페이지에서 단계별로 설명합니다.

개요

quant-ai는 단일 호스트 Docker Compose 토폴로지로 설계되어 있어, 로컬 개발자 PC와 운영 VM에서 동일한 docker-compose.*.yml이 동작합니다. Compose 파일은 두 가지가 있습니다.

• docker-compose.yml — 로컬 / 단일 VM용. 이미지를 로컬에서 빌드.
• docker-compose.prod.yml — Azure VM용. ACR(Azure Container Registry)에 푸시된 이미지를 pull, 강화된 시크릿 검증, json-file 로그 회전, ALLOW_LIVE 킬 스위치 적용.

사전 요구 사항

항목	최소 버전	비고
Docker Engine	24+	Compose v2 플러그인 포함
Docker Compose	v2.20+	docker compose (스페이스, 하이픈 아님)
Python	3.11	컨테이너 내부에서 사용. 호스트에 별도 설치 불요
디스크	20GB+	TimescaleDB / Redis / Grafana 볼륨 + 이미지
RAM	4GB+ (로컬), 8GB+ (Azure VM B2s)	analysis-worker가 PyTorch CPU 사용

Azure VM 배포를 한다면 추가로 다음이 필요합니다.

• az CLI (ACR 로그인용)
• docker buildx (Apple Silicon → linux/amd64 크로스 빌드)
• VM에 SSH 키 등록

컨테이너 토폴로지

┌─────────────────────────────────────────────────────────────────┐
│ host:80                host:3000              host:5432         │
│ (web nginx)            (grafana)              (timescaledb)     │
└─────┬─────────────────────┬─────────────────────┬──────────────┘
      │                     │                     │
      │              ┌──────┴──────┐              │
      │              │  network    │              │
      └──────────────┤  (compose)  ├──────────────┘
                     └──┬──────┬───┘
                        │      │
              ┌─────────┴─┐  ┌─┴────────────┐
              │   api     │  │ analysis-    │
              │  :8000    │  │   worker     │
              └─────────┬─┘  └──────┬───────┘
                        │            │
                  ┌─────┴───────┐    │
                  │ position-   │    │
                  │ reconciler  │    │
                  └─────────────┘    │
                                     │
                        ┌────────────┴───┐
                        │     redis      │
                        │     :6379      │
                        └────────────────┘

컨테이너	책임	스케일
timescaledb	OHLCV 하이퍼테이블 + 멀티테넌트 메타데이터	1
redis	분석 큐, WebSocket pubsub, 캐시	1
grafana	5종 대시보드 + Unified Alerting	1
api	FastAPI + WebSocket. 모든 외부 트래픽의 진입점	1 (rolling restart)
web	React 대시보드 nginx	1
analysis-worker	LLM 분석 큐 컨슈머	1~3 (수평 확장 가능)
position-reconciler	broker vs DB 포지션 일치 검증	1 (싱글톤 권장)

자세한 컨테이너별 환경변수는 환경변수 카탈로그를 참고하세요.

설치 흐름

flowchart LR
    A[clone repo] --> B[.env 작성]
    B --> C[docker compose up]
    C --> D[alembic upgrade head]
    D --> E[/health 확인]
    E --> F[Grafana 첫 로그인]
    F --> G[운영 시작]

상세 절차는 사용 환경에 따라 두 갈래입니다.

• 노트북 / 단일 VM: Docker Compose 설치
• Azure VM amd64: Azure VM 배포
• 가이드 사이트(이 docs)만 따로 배포: Azure Static Web Apps

마이그레이션 적용/롤백은 두 경로 모두 동일하므로 Alembic 마이그레이션에서 단일 출처로 관리합니다.

검증

설치가 끝났다면 다음 모두 OK여야 합니다.

# 1. 컨테이너 모두 running
docker compose ps

# 2. 마이그레이션이 head
docker compose exec api alembic current

# 3. API 헬스체크 200
curl -fsS http://localhost:8000/health

# 4. Grafana 접근 (admin/admin → 즉시 비밀번호 변경)
curl -I http://localhost:3000/api/health

자동화된 헬스체크는 헬스체크 cron에서 다룹니다.

트러블슈팅

증상	페이지
docker compose up 직후 api가 unhealthy	DB 마이그레이션 실패
Grafana 대시보드가 비어 있음	Grafana 대시보드 §6
거래소 키 등록 시 401	브로커 401
KIS 토큰이 24h 후 만료	KIS 토큰 만료

관련 페이지

• Docker Compose 설치
• Azure VM 배포
• Azure Static Web Apps (가이드 사이트)
• Alembic 마이그레이션
• 환경변수 카탈로그