d3ro-voice/docs/deployment/nas-deploy-runbook.md

2.5 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

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