zio/kintex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1de3b9b269
kintex/docs/BUILD_DEPLOY.md
zio eccbeb1337 feat(v2.0): Phase A 아키텍처 + WISE 개발문서 + PM/PMO + DB 계층 + 프론트 착수 
- 거버넌스: kintex-pm·dev-pm·pmo 에이전트
- Phase A 아키텍처 5종: docs/architecture/{app,system,tech,data,network}.md (성문화·NFR·SRID0 공간표준·M16 스타스키마·보안영역)
- WISE(UIWS) 참조 개발문서 6종: README·DEVELOPMENT_GUIDE·ENV_SETUP·COMMON_CODES·API_GUIDE·BUILD_DEPLOY
- DB 계층: PostGIS 스키마 V1~V6(홀·트렌치 가정그리드·GiST) + MyBatis 매퍼 5종(ST_* 공간쿼리) + Flyway. gradlew build SUCCESS
- 프론트 착수: React/Vite 스캐폴드 + design.md 토큰 + SCR-01 로그인·SCR-03 부스 에디터. tsc/vite build EXIT 0
- R-T1 수정: 나노바나나 워커 큐키 kintex:renderjob:queue 통일(백엔드 정합, silent no-op 방지)
- 도메인/게이트: G2 해소(dev kintex.zioinfo.kr·prod kintex.wise.ai.kr), CLAUDE.md 로스터 20종

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 18:10:01 +09:00

4.0 KiB
Raw Blame History

킨텍스 자동전시시스템 — 빌드/실행 개요

WISE(UIWS) 참조 — 빌드·배포 흐름(프론트 vite build → 백엔드 번들 / systemd / webhook 자동배포)은 workspace/uiws/deploy/README_배포.md·DEV_HANDOFF.md를 따른다. 본 문서는 빌드/실행 개요만 다룬다. 상세 CI/CD 파이프라인(Gitea webhook·deploy_server·systemd·nginx·롤백)은 Phase E kintex-devops-dev 산출물이 정본이다. 운영 서버·포트는 G2 게이트(GUARDiA 인프라와 별개 도메인) 확정 후.

1. 산출물 구성

킨텍스는 3개 실행 단위로 구성된다:

단위 빌드 산출물 실행
백엔드 ./gradlew bootJar (JDK17) build/libs/kintex-*.jar java -jar(systemd 권장)
프론트(웹) npm run build (Node 18+, Vite) dist/(역할별 번들) nginx 정적 서빙(SPA 폴백)
나노바나나 워커 (Python, 빌드 없음) tools/nanobanana 모듈 큐 소비 데몬(별도 서비스)

프론트 dist를 백엔드 static에 번들하는 단일 jar 패키징(GUARDiA 표준)도 가능하나, 킨텍스는 역할별 프론트 번들 분리(PLANNING §2-1)이므로 nginx 정적 서빙 + 백엔드 API 분리를 기본으로 한다(Phase A SA가 배포 토폴로지 확정).

2. 로컬 빌드/실행

환경변수·설치는 ENV_SETUP.md 참조.

# 백엔드
cd src/backend
./gradlew build              # 컴파일+테스트
./gradlew bootRun            # 개발 실행 (또는 java -jar build/libs/kintex-*.jar)

# 프론트
cd ../frontend
npm install
npm run dev                  # 개발 서버(프록시 → /api)
npm run build                # dist/ 생성

# 나노바나나 워커 (G1 승인 후 실호출)
cd ../../tools/nanobanana
pip install google-genai Pillow
python -m tools.nanobanana.worker

3. 빌드 게이트 (push 전 — WISE 관행)

WISE .githooks/pre-push 패턴을 준용해 파이프라인을 보호한다:

  1. 시크릿 파일 커밋 차단(.env·*.key·*-adminsdk-*.json — gitignore 유지)
  2. Flyway 마이그레이션 번호 충돌 검사(신규 = 최대+1)
  3. 변경분 백엔드 compileJava / 프론트·워커 tsc·lint — 실패 시 push 차단
  4. 자동배포 경고(파이프라인 연결 시 push=배포 트리거)

4. 배포 흐름 (개요 — 상세는 Phase E)

GUARDiA 표준 배포 파이프라인 준용:

workspace/kintex ── git push ──> Gitea(zio/kintex) ── webhook ──> deploy_server
                                    └─> 빌드(gradlew bootJar · vite build) → Flyway 마이그 → jar 재기동 · dist 배포 → 헬스 게이트(GET /health)
  • Fail-Safe: 백업 → 배포 → 헬스체크(200) → 실패 시 롤백(이전 jar 유지). 깨진 jar가 서버를 죽이지 않도록 clean bootJar 검증 후 교체(WISE 배포 자기방어 패턴).
  • systemd: 백엔드 jar·워커 데몬을 유닛으로 등록(부팅 자동기동·재시작). AI env drop-in(ANTHROPIC_API_KEY·ADMIN_PASSWORD_ENC)은 표준 프레임워크 §7 방식.
  • nginx: <kintex-domain> vhost → /=프론트 정적, /api/·/ws=백엔드 포트. TLS는 certbot. (도메인·포트 = G2 확정.)
  • 운영 배포는 소유자 승인 필수.

5. 선행 게이트

게이트 내용 영향
G1 나노바나나(Gemini) 외부 호출 승인(PLANNING R12) 워커 실이미지 생성·M5 배포. 미승인 시 목/degraded
G2 배포 대상 서버·포트(별개 도메인) Phase E 배포 착수 전

6. 참조

  • 환경 구축: ENV_SETUP.md · 개발 표준: DEVELOPMENT_GUIDE.md
  • 구현 백로그(Phase E 배포): IMPLEMENTATION_BACKLOG.md
  • WISE 배포 원본(참조): workspace/uiws/deploy/README_배포.md·workspace/uiws/DEV_HANDOFF.md
  • 표준 프레임워크 배포: workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md §7