[Deploy] PostgreSQL·AI Runtime 기반 데모 배포 구성

[hywznn]

한 줄 목표

시연자 PC의 LM Studio 없이 Spring Boot Server + PostgreSQL + 별도 AI Runtime을 재현 가능한 HTTPS demo 환경에 연결합니다.

배포 구조

Client → Spring Boot Server → PostgreSQL
                  │
                  └→ AI Runtime → External LLM API / Cloud Endpoint
                           └→ pinned Knowledge Bundle

Server image에는 LLM Provider SDK와 API Key를 넣지 않습니다. Server는 AI Runtime base URL과 service credential만 압니다.

Server 저장소 구현 범위

• multi-stage Dockerfile, non-root user, health check
• local integration용 Compose: Server + PostgreSQL + 선택적 AI Runtime URL
• prod profile, Flyway validate, connection pool 제한
• Actuator liveness/readiness와 공개 /health 분리
• AI_RUNTIME_BASE_URL, service credential, timeout/concurrency, required contract/knowledge version 구성
• AI Runtime 장애를 readiness 전체 실패가 아닌 degraded dependency로 관측
• HTTPS, 최소 CORS origin, secret injection
• AiRun/outbox의 application restart 복구 확인
• image rollback과 forward-compatible migration 절차
• 배포 후 Smoke와 수동 처리 runbook

설정 소유권

설정	소유
DB URL/credential, JWT, CORS	Server deployment
AI Runtime URL/service auth/deadline	Server deployment
Provider API Key/model/prompt/agent	AI Runtime deployment
Context Pack/Workflow Catalog bundle version	Knowledge release, AI Runtime pin

Smoke 흐름

1. /health와 DB readiness
2. Login·tenant isolation
3. POST /api/v1/ai-runs → 202 + aiRunId
4. Server → AI Runtime contract/version 확인
5. 후보 결정 → Task 검토·승인 → Worker Link → 응답·완료
6. Server 재시작 뒤 미완료 Run/Event 복구
7. AI Runtime timeout에서 가짜 후보 없이 수동 처리 가능

완료 조건

• 깨끗한 환경에서 동일 image와 migration으로 실행됩니다.
• LM Studio와 개발자 PC가 꺼져도 demo가 동작합니다.
• Provider secret은 Server 환경·image·log에 없습니다.
• AI Runtime 장애가 일반 HR API resource를 고갈시키지 않습니다.
• HTTPS Product Smoke와 rollback rehearsal가 통과합니다.

경계 밖

• Provider/Model/Prompt 배포: fowoco/ai
• Knowledge bundle release: fowoco/knowledge
• Kubernetes/Kafka/실제 Blue-Green Agent Router
• 완성형 collector/dashboard: Infra roadmap 및 [Observability] Server Workflow·AI Runtime 경계 추적 구현 #26 연결

관계

• Hard blocker: GitHub native dependency 참조
• Integration prerequisite: [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7, [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11, [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, #25와 AI Runtime 배포
• 후속: [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

2026-08-04 · 배포 실패를 성공처럼 숨기지 않기

현재 배포 Workflow의 kubectl ... || echo 형태는 실제 rollout 실패도 성공한 Job처럼 보이게 할 수 있으므로 제거합니다.

• 대상 Deployment가 없으면 명확히 실패하고 최초 배포는 infra runbook으로 안내
• kubectl set image 뒤 kubectl rollout status --timeout=... 확인
• rollout·health·대표 API smoke 중 하나라도 실패하면 Actions Job을 실패 처리
• GHCR image pull 권한과 필요한 환경변수 이름을 README/runbook에 문서화
• 배포 성공은 “명령 실행”이 아니라 새 image의 readiness와 smoke 통과로 판단