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 모드 전환

1. deploy.sh

SSH로 Oracle VM에 접속한 후 실행하는 배포 스크립트.

Pre-flight 체크

1. Docker 설치 확인 (docker --version)
2. Docker Compose 설치 확인 (docker compose version)
3. docker-compose.yml 유효성 검증 (docker compose config --quiet)
4. galaxis-net 네트워크 존재 확인 → 없으면 생성
5. .env 파일 존재 확인 → 없으면 에러 + .env.example 복사 안내
6. 필수 환경변수 검증:
   - ANTHROPIC_API_KEY
   - GITEA_TOKEN
   - GITEA_WEBHOOK_SECRET
   - DISCORD_TOKEN
   - DISCORD_CHANNEL_ID
   - FERNET_KEY
   - AGENT_API_KEY

배포 단계

1. galaxis-agent 이미지 빌드 (docker compose build)
2. 서비스 시작 (docker compose up -d)
3. Health check 검증 (5초 간격, 최대 60초 retry):
   - GET /health → status == "ok"
   - GET /health/gitea → 연결 확인
   - GET /health/discord → 연결 확인
   - GET /health/queue → 큐 상태 확인
   - GET /health/costs → 응답 확인
4. 결과 출력 (성공/실패 + 로그 안내)

--dry-run 옵션

pre-flight 체크는 실제로 실행하되, Docker 명령(build, up, health check)은 echo만 출력한다. 로컬에서 .env 유효성 등을 검증할 수 있다.

에러 처리

pre-flight 실패 시: 구체적 에러 메시지 + 해결 방법 안내 후 종료
빌드 실패 시: 에러 로그 출력 후 종료
health check 실패 시: docker compose logs 안내 후 종료 (자동 롤백 없음)

수동 롤백

docker compose down
git checkout <이전_커밋>
./deploy.sh

2. build-sandbox.sh

샌드박스 이미지를 빌드하는 독립 스크립트.

1. Dockerfile.sandbox 존재 확인
2. docker build -f Dockerfile.sandbox -t galaxis-sandbox:latest .
   (VM에서 직접 실행하므로 네이티브 ARM64 빌드, --platform 불필요)
3. 빌드 성공 확인 + 이미지 크기 출력

--dry-run 옵션: 명령 출력만 (실행 안 함).

3. .env.example 업데이트

Phase 4에서 추가된 환경변수를 .env.example에 반영:

# 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. 배포 절차 (사용자 관점)

# 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에서 수동 실행으로 확인

4.1 KiB Raw Blame History