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>
88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 킨텍스 자동전시시스템 — 빌드/실행 개요
|
|
|
|
> **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`](ENV_SETUP.md) 참조.
|
|
|
|
```bash
|
|
# 백엔드
|
|
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`](ENV_SETUP.md) · 개발 표준: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md)
|
|
- 구현 백로그(Phase E 배포): [`IMPLEMENTATION_BACKLOG.md`](IMPLEMENTATION_BACKLOG.md)
|
|
- WISE 배포 원본(참조): `workspace/uiws/deploy/README_배포.md`·`workspace/uiws/DEV_HANDOFF.md`
|
|
- 표준 프레임워크 배포: `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md` §7
|