배포 파이프라인 (Deployment Pipeline)

작성: 2026-08-31 · 2026-09-07 현행화 · 문서 소유: docs/ops 상태: 2026-09-01 NAS 수동 실배포 완료 / NAS 자동배포 구성 잔여. 당시 증거이지 현재 live 상태 확인은 아니다.

목표 아키텍처 (소유자 지시)

이 PC(개발 워크스테이션)
   │  push (master)
   ▼
Forgejo git.chanpaca.net  ──────  소스 SSOT (이관 완료 2026-08-31)
   │  ├─ 미러(백업) ── github.com (private 유지)   [현행 origin]
   │  └─ 배포 ──▶ NAS Production (vignette-prod)
   │                  docker-compose.nas.yml (SSOT-host=nas, runtime-class=production)
   │
Cloudflare tunnel은 소유자 지시에 따라 제거 대상이다. 다만 현재 NAS ingress가 이를 경유하므로, 대체 ingress의 보안·가용성·OAuth 경계를 검증하기 전에는 제거하지 않는다.

나는 이 PC를 개발 전용으로만 사용한다. 배포 대상은 반드시 NAS Production이다.
github.com은 private로 백업/미러만 유지한다 (제거 아님).
git 관리·배포 파이프라인은 git.chanpaca.net (Forgejo) 이 소유한다.

1. 저장소 (소스 SSOT)

원격	URL	역할	상태
`origin`	https://github.com/yunchan8804-blip/vignette.git	private 백업/미러	유지
`forgejo`	ssh://git@git.chanpaca.net:2222/yunchan/vignette.git	소스 SSOT·배포	✅ 이관 완료

Forgejo 레포: yunchan/vignette (id 14, public, default master)
2026-09-01 배포 당시 기준 커밋: dce85620. 현재 master/로컬 HEAD는 실행 전에 별도로 확인한다.
Forgejo 접근: SSH 키(~/.ssh/id_ed25519, Host git.chanpaca.net → 192.168.0.38:2222) · API 토큰(infra/.env.deploy의 FORGEJO_API_TOKEN, gitignore)

2. 로컬 브랜치 규칙

master = Forgejo master와 동기화 (배포 기준선)
기능/scoped 브랜치 = 개발용, 검증 후 master로 합침

3. NAS Production 배포 흐름 (수동 절차 실증, 자동화 구성 예정)

[Forgejo] 승인된 master 후보 SHA
   ▼
[NAS] git 컨테이너로 해당 SHA clone·검증
   ▼
[NAS] API/Web build → online migration → docker compose 재생성
   ▼
vignette-prod (api/web/engine/db/proxy) readiness·데이터 보존 검증
   ▼
[Cloudflare] 현재 공개 서빙 경로 유지 (대체 ingress 검증 뒤 tunnel retirement)

NAS 호스트에는 git이 없으므로 git 컨테이너로 Forgejo에서 clone한다. 2026-09-01 수동 실배포는 이 흐름으로 dce85620을 검증했다. 자동배포 hook과 tunnel retirement는 별도 열린 게이트다.

4. 검증 게이트 (배포 전)

apps/web: npm run typecheck, npm run build
apps/api: 관련 test suite
SSOT checker scripts/test_dev_dashboard_ssot.py
Forgejo master == 로컬 master (배포 무결성)
NAS: docker compose ps healthy, /api/health ok·db/engine true

5. 실증된 배포 절차 (2026-09-01 1차 실배포 완료, SHA `dce85620`)

NAS 호스트에는 git이 없으므로 git 컨테이너로 Forgejo에서 clone한다.

# NAS에서 (ssh yunchan@192.168.0.38)
cd /volume1/docker/vignette-prod
# 0) 백업: pg_dump custom + env.nas 사본 + 구 이미지 SHA 기록
docker exec vignette-prod-db-1 pg_dump -U vignette_owner -d vignette -Fc > backups/pre-deploy-<sha>-<ts>.dump
cp private/env.nas private/env.nas.before-deploy-<sha>
# 1) Forgejo master clone (git 컨테이너) + HEAD 검증
docker run --rm -v $PWD:/work alpine/git clone --depth 1 --branch master \
  http://192.168.0.38:3000/yunchan/vignette.git /work/src-<sha>
# 2) 이미지 빌드 (API 컨텍스트는 저장소 루트)
cd src-<sha> && docker build -f apps/api/Dockerfile -t vignette-nas-api:<sha> .
docker build --build-arg VITE_API_BASE=/api -t vignette-nas-web:<sha> apps/web
# 3) 새 마이그레이션은 psql로 온라인 적용(initdb 스크립트는 재실행되지 않음),
#    구 API가 의존하는 제약을 바꾸는 마이그레이션은 stop api 후 적용
# 4) private/env.nas의 VIGNETTE_NAS_API_IMAGE/WEB_IMAGE를 새 이미지 ID로 교체
docker compose -f docker-compose.nas.yml --env-file private/env.nas config --quiet
docker compose -f docker-compose.nas.yml --env-file private/env.nas up -d
# 5) readiness: public health ok·db/engine true, OpenAPI 200, /auth/me 401, 데이터 집계 전후 동일

공개 웹(Cloudflare Pages)은 별도 배포한다: apps/web에서 npm run build → node ../../scripts/preserve-assets.mjs(이전 세대 자산 보존) → npx wrangler pages deploy dist --project-name vignette --branch main.

6. 남은 구성 작업 (TODO)

Forgejo master 기준 NAS 자동배포 후크(수동 절차는 §5로 실증 완료)
Forgejo가 SSOT임을 문서에 반영, github은 private 미러 유지
cloudflare tunnel 제거 또는 유지 결정 — 현재 api-vignette는 NAS 호스트 상주 cloudflared 터널 경유다. 대체 ingress의 보안·가용성·OAuth 경계가 검증되기 전에는 제거하지 않는다.
배포 시 NAS 접근 자격(SSH 키/배포 계정)을 .env.deploy/시크릿으로 관리

5.1 KiB Raw Blame History