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.
3.4 KiB
3.4 KiB
NAS Deployment & Rollback Runbook (docker-compose.nas.yml)
Canonical operations runbook for deploying
apps/api-server,apps/admin,apps/web, andwhisperon the NAS (kd-nas). ResolvesGAP-INFRA-02by 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, port5000, healthcheckhttp://localhost:5000/health)d3ro_voice_admin(apps/admin, port3001, healthcheckhttp://127.0.0.1:3001/login)d3ro_voice_web(apps/web, port3002, healthcheckhttp://127.0.0.1:3002/app/login)d3ro_voice_whisper(faster-whisper-server, port8000)
- Ingress: Cloudflare Tunnel (
kd-nas) routes:d3ro.chanpaca.net/app*→http://localhost:3002d3ro.chanpaca.net/api*&/health→http://localhost:5000d3ro-admin.chanpaca.net/*→http://localhost:3001
2. Pre-Deploy Checklist
- Verify
mainpasses CI (npm run verify:all). - Confirm
/volume1/docker/d3ro/.envon the NAS defines all required fail-closed variables:JWT_SECRETSUPABASE_URLSUPABASE_ANON_KEYSUPABASE_SERVICE_ROLE_KEYADMIN_BOOTSTRAP_TOKENOPENAI_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