2.5 KiB
2.5 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
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