Deploy API 설계

Mac mini 위에서 돌아가는 여러 서비스를 같은 방식으로 배포하고, 그 결과를 이 macmini-deploy-status 레포에 릴리즈 노트로 남기기 위한 API 설계입니다.

목적

• GitHub Actions, 수동 curl, 또는 내부 도구에서 하나의 HTTP API로 배포를 트리거합니다.
• PM2 서비스별 배포 절차를 deploy.config.json에 선언해 반복 가능한 형태로 관리합니다.
• 배포 실행 결과를 PostgreSQL에 저장합니다.
• 사람이 읽기 쉬운 릴리즈 노트를 이 레포의 releases/YYYY-MM-DD/<service>/ 아래에 Markdown/JSON으로 기록합니다.
• Docusaurus Pages에서 최신 릴리즈 노트와 API 설계를 바로 확인합니다.

구성 요소

GitHub Actions / operator
  └─ POST https://pm2-deploy.dongholab.com/deploy/<service>
       └─ Caddy HTTPS reverse proxy
            └─ deploy-api @ 127.0.0.1:3300
                 ├─ service repo git pull/build
                 ├─ PM2 reload
                 ├─ health check
                 ├─ PostgreSQL deploy_runs insert
                 └─ macmini-deploy-status release note commit/push

공개 엔드포인트

Base URL:

https://pm2-deploy.dongholab.com

Method	Path	설명	인증
GET	/health	Deploy API 상태 확인	없음
GET	/services	배포 가능한 서비스 목록	없음 또는 내부 확인용
POST	/deploy/:service	지정 서비스 배포 실행	필요

인증

배포 트리거는 둘 중 하나의 헤더가 필요합니다.

Authorization: Bearer <DEPLOY_TOKEN>
x-deploy-token: <DEPLOY_TOKEN>

실제 토큰 값은 이 레포에 기록하지 않습니다.

서비스 설정 모델

서비스별 설정은 /Users/dongho/pm2-multi-service-starter/deploy.config.json에서 관리합니다.

개념 모델:

{
  "services": {
    "qrstay": {
      "repoPath": "/Users/dongho/qr-stay",
      "branch": "main",
      "installCommand": "npm ci",
      "buildCommand": "npm run build",
      "reloadCommand": "pm2 reload /Users/dongho/qr-stay/ecosystem.config.cjs --only qrstay --update-env",
      "healthcheckUrl": "https://qrstay.dongholab.com/"
    }
  }
}

배포 실행 순서

현재 표준 실행 단계는 다음과 같습니다.

1. git fetch origin <branch>
2. git checkout <branch>
3. git pull --ff-only origin <branch>
4. install command
5. build command
6. PM2 reload command
7. health check with retry
8. deploy_runs DB 기록
9. macmini-deploy-status 릴리즈 노트 기록

릴리즈 노트 출력 규격

자동 기록 위치:

releases/YYYY-MM-DD/<service>/
├── latest.md
└── runs/
    ├── <timestamp>-<run-id>.md
    └── <timestamp>-<run-id>.json

Docusaurus에서 사람이 보는 요약 문서는 docs/releases/<date>.md에 둡니다.

실행 결과 JSON 개념

{
  "runId": "c7d539ef-835",
  "service": "qrstay",
  "status": "success",
  "startedAt": "2026-07-04T08:36:07.443Z",
  "finishedAt": "2026-07-04T08:36:19.000Z",
  "steps": [
    {"name": "git fetch", "status": "success"},
    {"name": "npm ci", "status": "success"},
    {"name": "npm run build", "status": "success"},
    {"name": "pm2 reload", "status": "success"},
    {"name": "healthcheck", "status": "success"}
  ],
  "summaryMarkdownPath": "releases/2026-07-04/qrstay/latest.md"
}

새 서비스 추가 체크리스트

1. 서비스 레포에 production PM2 ecosystem 파일을 둡니다.
2. 서비스가 localhost 포트에서 안정적으로 뜨는지 확인합니다.
3. Caddy에 도메인 → 127.0.0.1:<port> reverse proxy를 추가합니다.
4. deploy.config.json에 서비스 entry를 추가합니다.
5. POST /deploy/<service>로 배포를 테스트합니다.
6. releases/YYYY-MM-DD/<service>/latest.md와 DB 기록을 확인합니다.
7. 이 Docusaurus 문서에 도메인/서비스 문서를 추가합니다.

설계상 주의점

• PM2 reload는 앱 이름만 쓰지 말고, 서비스 repo의 ecosystem.config.cjs를 명시합니다.
• Health check는 PM2 reload 직후 transient 502를 고려해 retry를 둡니다.
• Secret 값은 Markdown 릴리즈 노트와 JSON 기록에 남기지 않습니다.
• 실패한 배포도 원인 분석을 위해 DB와 릴리즈 노트에 남기는 편이 좋습니다.