From 47c873a962a3ec23aeacf20609bfe135a9205551 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A8=B8=EB=8B=88=ED=8E=98=EB=8B=88?= Date: Fri, 20 Mar 2026 22:18:53 +0900 Subject: [PATCH] docs: add Phase 5 deployment automation design spec --- ...3-20-galaxis-agent-phase5-deploy-design.md | 143 ++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md diff --git a/docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md b/docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md new file mode 100644 index 0000000..3a6ad2c --- /dev/null +++ b/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에서 수동 실행으로 확인