# 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 ``` Windows에서 로컬 Docker 데몬 없이 SSH 빌드하는 현재 경로(2026-11-17 전체 빌드, 2026-11-18 선택 빌드 검증): ```powershell $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: ```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 ```