1ef2235939
- SessionStart hook (scripts/graphify_setup.py): auto-install graphifyy[sql], build knowledge graph on first run (graphify extract --code-only, local AST), incremental graphify update thereafter — install-only smartness - knowledge/kintex/: all 183 KINTEX md docs bundled (planning/design/analysis) - knowledge/guardia/: distilled GUARDiA-wide knowledge from 2,483 md files (solutions-catalog, standard-framework, operations-cicd, lessons-learned; credentials/IP-free curated) - SKILL.md: graph-first codebase query rules + knowledge base loading guide Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.0 KiB
4.0 KiB
킨텍스 자동전시시스템 — 빌드/실행 개요
WISE(UIWS) 참조 — 빌드·배포 흐름(프론트 vite build → 백엔드 번들 / systemd / webhook 자동배포)은
workspace/uiws/deploy/README_배포.md·DEV_HANDOFF.md를 따른다. 본 문서는 빌드/실행 개요만 다룬다. 상세 CI/CD 파이프라인(Gitea webhook·deploy_server·systemd·nginx·롤백)은 Phase Ekintex-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 패턴을 준용해 파이프라인을 보호한다:
- 시크릿 파일 커밋 차단(
.env·*.key·*-adminsdk-*.json— gitignore 유지) - Flyway 마이그레이션 번호 충돌 검사(신규 = 최대+1)
- 변경분 백엔드
compileJava/ 프론트·워커tsc·lint — 실패 시 push 차단 - 자동배포 경고(파이프라인 연결 시 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