d3ro-voice/docs/deployment/nas-deploy-runbook.md
Yun Chan 6791e29f27 fix(ops): send apikey with push drain, read the web push public key from release/, record 2026-11-17 backlog evidence
The scheduled push drain got HTTP 401 because modern Supabase service keys need the apikey
header next to Bearer. NAS deploy scripts fall back to release/webpush-vapid-public.key
(public key only). Map, mobile SSOT and deployment runbooks are synced with the verified
operations run in docs/evidence/2026-11-17-backlog-operations.md.
2026-11-20 15:16:19 +09:00

3.4 KiB

NAS Deployment & Rollback Runbook (docker-compose.nas.yml)

Canonical operations runbook for deploying apps/api-server, apps/admin, apps/web, and whisper on the NAS (kd-nas). Resolves GAP-INFRA-02 by documenting the canonical manual/SSH deployment and rollback procedure instead of an ephemeral DinD CI job.


1. Architecture & Canonical Files

  • Compose manifest: docker-compose.nas.yml
  • NAS host path: /volume1/docker/d3ro/
  • Containers:
    • d3ro_voice_api (apps/api-server, port 5000, healthcheck http://localhost:5000/health)
    • d3ro_voice_admin (apps/admin, port 3001, healthcheck http://127.0.0.1:3001/login)
    • d3ro_voice_web (apps/web, port 3002, healthcheck http://127.0.0.1:3002/app/login)
    • d3ro_voice_whisper (faster-whisper-server, port 8000)
  • Ingress: Cloudflare Tunnel (kd-nas) routes:
    • d3ro.chanpaca.net/app* → http://localhost:3002
    • d3ro.chanpaca.net/api* & /health → http://localhost:5000
    • d3ro-admin.chanpaca.net/* → http://localhost:3001

2. Pre-Deploy Checklist

  1. Verify main passes CI (npm run verify:all).
  2. Confirm /volume1/docker/d3ro/.env on the NAS defines all required fail-closed variables:
    • JWT_SECRET
    • SUPABASE_URL
    • SUPABASE_ANON_KEY
    • SUPABASE_SERVICE_ROLE_KEY
    • ADMIN_BOOTSTRAP_TOKEN
    • OPENAI_API_KEY (if direct OpenAI proxy is used)

3. Deployment Procedure

# 1. SSH into NAS and navigate to deployment root
cd /volume1/docker/d3ro

# 2. Tag current running images for instant rollback
STAMP="$(date +%Y%m%d-%H%M%S)"
for svc in api-server admin web; do
  IMG_ID="$(docker compose -f docker-compose.nas.yml images -q "$svc" 2>/dev/null || true)"
  if [ -n "$IMG_ID" ]; then
    docker tag "$IMG_ID" "d3ro-${svc}:rollback-${STAMP}"
  fi
done
cp docker-compose.nas.yml "docker-compose.nas.yml.before-${STAMP}"

# 3. Sync repository changes and rebuild containers
git pull --ff-only
docker compose -f docker-compose.nas.yml up -d --build

# 4. Verify container health checks
docker compose -f docker-compose.nas.yml ps
curl -fsS http://127.0.0.1:5000/health
curl -fsSI http://127.0.0.1:3001/login | head -n 1
curl -fsSI http://127.0.0.1:3002/app/login | head -n 1

Windows에서 로컬 Docker 데몬 없이 SSH 빌드하는 현재 경로(2026-11-17 전체 빌드, 2026-11-18 선택 빌드 검증):

$env:DOCKER_HOST = "ssh://yunchan-nas"
pwsh -NoProfile -File scripts/deploy-nas.ps1 -BuildOnly
ssh yunchan-nas "cd /volume1/docker/d3ro && docker compose up -d"

-BuildOnly는 기본적으로 API·Admin·Web 이미지를 원격 Docker에 만들고 tar/배포용 .env 패키징은 생략한다. 이미 완료된 이미지를 유지하며 하나만 다시 빌드할 때는 -Services web처럼 api/admin/web을 선택한다(2026-11-18). Web Push 공개키는 NEXT_PUBLIC_VAPID_PUBLIC_KEY/WEBPUSH_VAPID_PUBLIC_KEY가 비어 있으면 release/webpush-vapid-public.key에서 읽는다. 로컬 JWT_SECRET 없이도 빌드할 수 있으며 NAS의 기존 .env는 그대로 유지한다.


4. Rollback Procedure

If any health check fails after deployment:

cd /volume1/docker/d3ro
cp "docker-compose.nas.yml.before-${STAMP}" docker-compose.nas.yml
git checkout HEAD~1
docker compose -f docker-compose.nas.yml up -d --build
docker compose -f docker-compose.nas.yml ps