`apps/status` — Uptime Kuma · `status.pregoi.com` 실행 기획

상태: apps/status에 Compose·README 반영됨
목표: Prego/apps/status에 Uptime Kuma를 Docker로 운영할 수 있는 최소 단위 아티팩트(docker-compose.yml, README.md)를 두고, **status.pregoi.com**으로 외부 접근 가능하도록 역프록시·DNS·엣지 절차를 문서화한다.

1. 배경·범위

Uptime Kuma: 오픈소스 가동 시간·모니터링 대시보드(Web UI, WebSocket 사용).
저장소 위치: 모노레포 apps/status/ (기존 apps/www, apps/admin-web 등과 동일한 apps/ 하위 운영 스택 디렉터리로 둠). 이 폴더는 Next.js 앱이 아닐 수 있음 — Docker·Compose 중심 정적 문서로 관리.
요구(프롬프트 요약):
- 데이터: 호스트 ./data에 바인드 마운트(또는 명명 볼륨 + README에 경로 명시).
- 포트: 컨테이너 노출 3001 (호스트 3001:3001 등).
- 문서: Nginx 또는 Zuplo 설정 가이드를 README에 포함.

2. 디렉터리·파일 구조 (구현 시 권장)

apps/status/
├── README.md                 # 실행 방법, DNS, Nginx, Zuplo/대안, 보안
├── docker-compose.yml        # Uptime Kuma 서비스 정의
├── .env.example              # (선택) UPTIME_KUMA_PORT 등
├── .gitignore                # data/, .env
└── data/                     # 런타임 생성 — git에 커밋하지 않음

data/: Uptime Kuma SQLite 등 영속 데이터. .gitignore에 data/ 필수.
루트 .gitignore: 필요 시 apps/status/data/ 한 줄 추가 여부는 팀 규칙에 따름(이미 data/ 패턴이 있으면 중복 방지).

3. `docker-compose.yml` 설계 요건 (구현 체크리스트)

항목	요구
이미지	공식 권장: `louislam/uptime-kuma` (또는 문서화된 안정 태그 `1` / 구체 버전 핀)
포트	`3001:3001` (Kuma 기본이 3001인지 확인 후 맞춤; 공식 문서 기준)
볼륨	`./data:/app/data` (공식 문서의 데이터 경로와 일치시킬 것)
재시작	`restart: unless-stopped` 권장
네트워크	단일 서비스면 기본 bridge로 충분; 추후 exporter 추가 시 네트워크 분리 검토
최적화	불필요한 권한 금지(`user`/`read_only`는 Kuma 호환 여부 확인 후); 리소스 `deploy.resources`는 선택

주의: Uptime Kuma 버전·데이터 경로는 공식 Docker 문서와 맞출 것. 구현 시 한 번 docker compose up으로 로컬 검증.

4. `README.md`에 포함할 목차 (가이드 범위)

개요 — 무엇을 위해 있는지, status.pregoi.com과의 관계.
로컬 실행 — docker compose up -d, 접속 URL http://localhost:3001, 최초 관리자 계정 생성.
프로덕션 배포 개요 — Docker 호스트(전용 VM, 기존 Ansible 대상 서버 등)에 두고, TLS 종료는 역프록시에서 처리하는 패턴 권장.
DNS — status.pregoi.com → (A/AAAA) 서버 공인 IP 또는 Cloudflare Tunnel/로드밸런서 엔드포인트.
Nginx 가이드 (권장 경로)
- listen 443 ssl + 인증서(Let’s Encrypt 등).
- location / → proxy_pass http://127.0.0.1:3001;
- WebSocket 헤더 (Upgrade, Connection) — Uptime Kuma 대시보드에 필요.
- proxy_set_header Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto 설정.
- (선택) IP 허용 목록, Basic Auth.
Zuplo 관련 서술 (현실적인 범위)
- Zuplo는 플랫폼에서 API 게이트웨이·OpenAPI 라우팅 용도(prego-zuplo)로 쓰이며, 장기 TCP/WebSocket 세션이 있는 풀스크린 웹 대시보드를 그대로 올리는 용도와는 맞지 않는 경우가 많음.
- 권장: status.pregoi.com은 Nginx/Caddy 등으로 원본 서버의 3001로 직접(또는 Cloudflare Tunnel로) 노출.
- Zuplo를 언급해야 할 때:
  - “공개 HTTP는 모두 Zuplo를 통과해야 한다”는 조직 정책이 있으면, 별도 설계(예: 동일 호스트에 Nginx만 두고 외부는 Tunnel/방화벽으로 제한, Zuplo는 다른 API 전용 호스트 유지)를 README에 트레이드오프로 명시.
  - prego-zuplo에 새 호스트를 추가하는 것은 OpenAPI·라우트·운영 승인 범위가 큼 — 기본 가이드에서는 Nginx + DNS를 주 경로로 두고, Zuplo는 “일반적으로 권장하지 않음 / 예외 시 아키텍처 검토 필요” 수준으로 안내.
보안 — 관리자 비밀번호, 업데이트(docker compose pull), 방화벽(3001은 로컬호스트만 바인드하고 Nginx만 공개하는 패턴 권장).
백업 — ./data 디렉터리 정기 스냅샷.

5. 모노레포 정합성

AGENTS.md / CI: apps/status는 Docker 전용이면 루트 pnpm 워크스페이스에 패키지로 넣지 않아도 됨 — apps/README.md에 한 줄 링크만 추가하는 수준으로 충분할 수 있음.
플랫폼 허브: 공개 API 계약 변경이 아니므로 prego-zuplo OpenAPI 필수 규칙은 해당 없음. 인프라는 prego-ansible / 호스트 운영 절차와 맞춰 링크만 README에 적을 것.

6. 구현 프롬프트 실행 순서 (에이전트용)

apps/status/ 생성, .gitignore에 data/, .env 등.
docker-compose.yml 작성 후 로컬에서 docker compose config 및 기동 스모크.
README.md 작성 — 위 목차 반영, Nginx 스니펫은 검증 가능한 최소 예시, Zuplo는 위 §4.6 정책 문구 포함.
(선택) apps/README.md에 status 항목 추가.

7. 오픈 이슈 (배포 전 결정)

실제 호스트: 전용 VM vs 기존 모니터링 서버 vs Kubernetes — compose는 VM 기준으로 작성하고 K8s는 “별도 매니페스트”로 분리할지.
TLS: Let’s Encrypt 자동화(certbot)를 같은 README에 넣을지, 링크만 할지.
인증: Kuma 자체 2FA·리버스 프록시 Basic Auth 중 선택.

8. 관련 링크 (구현 시 참고)

Uptime Kuma 공식 Docker / GitHub (이미지·볼륨 경로 확인).
Prego 플랫폼: API gateway & BFF governance — Zuplo 역할 구분 시 참고.
prego-zuplo runbook: 브라우저 CORS·ALLOWED_ORIGINS는 API 클라이언트 맥락; status 대시보드는 별 트래픽으로 취급하는 것이 일반적.

apps/status — Uptime Kuma · status.pregoi.com 실행 기획