docs: add Phase 5 deployment automation design spec

docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md

@@ -0,0 +1,143 @@
+# galaxis-agent Phase 5: Oracle VM 배포 자동화 설계 문서
+
+## 개요
+
+galaxis-agent를 Oracle VM (A1, 4코어 ARM64, 24GB)에 배포하기 위한 자동화 스크립트를 작성한다. Docker Compose 기반으로 서비스를 시작하고, health check로 배포 성공을 검증한다.
+
+## 범위
+
+- `deploy.sh` — pre-flight 체크, 이미지 빌드, 서비스 시작, health check 검증
+- `build-sandbox.sh` — 샌드박스 이미지 빌드 (배포와 분리)
+- `.env.example` 업데이트 — Phase 4에서 추가된 환경변수 반영
+
+## 범위 밖
+
+- Ansible / CI/CD 파이프라인
+- 모니터링 대시보드 (Grafana)
+- 멀티 리포 지원
+- autonomous 모드 전환
+- `docker-compose.prod.yml` 수정 (CLAUDE.md 금지)
+
+---
+
+## 1. deploy.sh
+
+SSH로 Oracle VM에 접속한 후 실행하는 배포 스크립트.
+
+### Pre-flight 체크
+
+```
+1. Docker 설치 확인 (docker --version)
+2. Docker Compose 설치 확인 (docker compose version)
+3. galaxis-net 네트워크 존재 확인 → 없으면 생성
+4. .env 파일 존재 확인 → 없으면 에러 + .env.example 복사 안내
+5. 필수 환경변수 검증:
+   - ANTHROPIC_API_KEY
+   - GITEA_TOKEN
+   - GITEA_WEBHOOK_SECRET
+   - DISCORD_TOKEN
+   - DISCORD_CHANNEL_ID
+   - FERNET_KEY
+```
+
+### 배포 단계
+
+```
+1. galaxis-agent 이미지 빌드 (docker compose build)
+2. 서비스 시작 (docker compose up -d)
+3. 30초 대기
+4. Health check 검증:
+   - GET /health → status == "ok"
+   - GET /health/gitea → 연결 확인
+   - GET /health/discord → 연결 확인
+   - GET /health/costs → 응답 확인
+5. 결과 출력 (성공/실패 + 로그 안내)
+```
+
+### --dry-run 옵션
+
+실제 Docker 명령을 실행하지 않고, 어떤 명령이 실행될지만 출력한다. 로컬에서 스크립트 검증용.
+
+### 에러 처리
+
+- pre-flight 실패 시: 구체적 에러 메시지 + 해결 방법 안내 후 종료
+- 빌드 실패 시: 에러 로그 출력 후 종료
+- health check 실패 시: `docker compose logs` 안내 후 종료 (자동 롤백 없음)
+
+---
+
+## 2. build-sandbox.sh
+
+샌드박스 이미지를 빌드하는 독립 스크립트.
+
+```
+1. Dockerfile.sandbox 존재 확인
+2. docker build -f Dockerfile.sandbox -t galaxis-sandbox:latest .
+3. 빌드 성공 확인 + 이미지 크기 출력
+```
+
+---
+
+## 3. .env.example 업데이트
+
+Phase 4에서 추가된 환경변수를 `.env.example`에 반영:
+
+```bash
+# Logging
+LOG_FORMAT=json
+
+# Cost Guard
+DAILY_COST_LIMIT_USD=10.0
+PER_TASK_COST_LIMIT_USD=3.0
+```
+
+`COST_GUARD_DB`와 `TASK_HISTORY_DB`는 Docker volume `/data/` 내 기본 경로를 사용하므로 `.env.example`에 포함하지 않는다.
+
+---
+
+## 4. 파일 구조
+
+```
+galaxis-agent/
+├── deploy.sh              # 신규: 배포 스크립트
+├── build-sandbox.sh       # 신규: 샌드박스 이미지 빌드
+├── .env.example           # 수정: Phase 4 변수 추가
+├── docker-compose.yml     # 기존 (변경 없음)
+├── Dockerfile             # 기존 (변경 없음)
+└── Dockerfile.sandbox     # 기존 (변경 없음)
+```
+
+---
+
+## 5. 배포 절차 (사용자 관점)
+
+```bash
+# 1. Oracle VM에 SSH 접속
+ssh oracle-vm
+
+# 2. 리포 클론 (최초) 또는 pull
+cd ~/galaxis-agent && git pull
+
+# 3. 환경변수 설정 (최초만)
+cp .env.example .env
+# .env 편집
+
+# 4. 샌드박스 이미지 빌드 (최초 또는 Dockerfile.sandbox 변경 시)
+./build-sandbox.sh
+
+# 5. 배포
+./deploy.sh
+
+# 6. Gitea webhook 등록 (최초만, 웹 UI)
+# URL: http://galaxis-agent:8000/webhooks/gitea
+```
+
+---
+
+## 6. 테스트 전략
+
+셸 스크립트이므로 Python 테스트 체계와 분리한다:
+
+- `deploy.sh --dry-run` — pre-flight 체크 + 명령 출력만 (실행 안 함)
+- `build-sandbox.sh --dry-run` — 명령 출력만
+- 실제 배포 검증은 VM에서 수동 실행으로 확인