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

76 lines
2.5 KiB
Markdown

# 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`](../../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
```bash
# 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:
```bash
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
```