# 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 ```