harness/plugins/zio-harness/knowledge/kintex/docs/ENV_SETUP.md

킨텍스 자동전시시스템 — 개발환경 구축 가이드

WISE(UIWS) 참조 — workspace/uiws의 backend/README.md·db/README_DB연동.md·DEV_HANDOFF.md 세팅 절차를 킨텍스 스택(MyBatis·PostGIS·Redis·나노바나나 Python 워커)에 맞춰 정리했다. ⚠️ 본 문서의 환경변수 이름은 표준 컨벤션(신규 코드가 준수할 규약)이며, 실제 비밀값·서버 포트는 저장소에 두지 않는다(Phase A SA/DEV 및 사내 비밀관리에서 확정).

---

1. 사전 요구 도구

도구	버전	용도
JDK 17	17.x (LTS)	Spring Boot 3.x 백엔드 빌드/실행(gradlew)
Node.js	18+ (LTS)	Vite 빌드(Node 16은 vite build 불가 — WISE 함정)
npm	Node 동봉	프론트 의존성
PostgreSQL	15+/16	kintex_db
PostGIS	3.x	공간 확장(부스 polygon·트렌치 point·배선 LineString)
Redis	6+/7	작업 큐(RenderJob·서류·알림)
Python	3.11+	나노바나나 워커 사이드카
Git	2.x	Gitea(zio/kintex)

Gradle Wrapper(gradlew)가 없으면 로컬 Gradle 8.x로 gradle wrapper --gradle-version 8.7 1회 실행해 생성(WISE 관행).

---

2. 초기 세팅

git clone <gitea>/zio/kintex.git
cd kintex

# 백엔드 (JDK17)
cd src/backend && ./gradlew build          # Phase B-0 스캐폴드 이후

# 프론트 (Node 18+)
cd ../frontend && npm install

# 나노바나나 Python 워커
cd ../../tools/nanobanana
pip install google-genai Pillow

---

3. PostgreSQL + PostGIS (kintex_db)

WISE와 동일하게 공유 PostgreSQL 인스턴스에 전용 DB + 전용 계정을 두어 타 솔루션과 물리 분리한다.

-- 관리자(postgres/sudo) 권한으로 실행
CREATE ROLE kintex LOGIN PASSWORD '<개발용-임시-변경대상>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE;
CREATE DATABASE kintex_db OWNER kintex ENCODING 'UTF8';
-- kintex_db 접속 후 PostGIS 활성화
\c kintex_db
CREATE EXTENSION IF NOT EXISTS postgis;

• 콜레이션은 서버 인스턴스 컨벤션에 맞춤(WISE는 en_US.UTF-8; UTF8이라 한글 저장/조회 정상).
• 스키마/시드는 Flyway 순번 마이그레이션(백로그 B-0)으로 적용. ddl 수동 검증이 필요하면 SET ROLE kintex; 후 마이그 SQL 실행.
• 원격 DB 접속(개발 PC): 5432가 외부 차단이면 SSH 로컬 포워딩 —

  ssh -L 5432:localhost:5432 <shell계정>@<db-host> -N
  # 앱은 jdbc:postgresql://localhost:5432/kintex_db 로 접속
  

---

4. Redis

로컬 기본 포트 6379. 큐 키 예: kintex:renderjob:queue(백엔드 발행 → Python 워커 소비). 개발 중 워커 미가동 시 큐잉·상태는 동작(발행까지).

---

5. 환경변수 목록 (표준 컨벤션)

비밀값은 하드코딩 금지 — 모두 환경변수/application.yml 프로퍼티로 주입. .env·*.key는 gitignore.

5-1. 백엔드(Spring Boot)

변수	필수	설명
KINTEX_DB_PASSWORD	필수	PostgreSQL kintex 계정 비밀번호
KINTEX_JWT_SECRET	권장	JWT HMAC(HS256) 시크릿(최소 32바이트). 미설정 시 개발용 기본값(운영 금지)
SERVER_PORT	선택	백엔드 포트(운영 포트는 G2 게이트에서 확정 — GUARDiA 인프라와 별개 도메인)
REDIS_HOST / REDIS_PORT	선택	기본 localhost / 6379
RENDER_WORKER_TOKEN	워커 연동 시	/api/internal/render/callback 공유 시크릿(X-Worker-Token)
ANTHROPIC_API_KEY	AI(Claude) 사용 시	Claude 텍스트 AI. 키는 env only — DB/코드/로그/커밋/응답 기록 금지, 실패 시 Ollama 폴백
ADMIN_PASSWORD_ENC / ADMIN_KEY_FILE	운영	admin 비번 AES-256-GCM 암호문 + 별도 키파일(root 600) → 기동 시 BCrypt 재시드
SMTP_HOST·SMTP_PORT·SMTP_USERNAME·SMTP_PASSWORD·KINTEX_MAIL_FROM	메일 발송 시	2차 인증 EMAIL 코드·알림 발송. 미설정 시 로컬 로그 모드

5-2. 나노바나나 Python 워커

변수	필수	설명
GEMINI_API_KEY	실호출 시(G1 승인 대상)	Gemini 이미지 생성 키. 워커에서만 로드 — 백엔드 미취급, 코드/로그/커밋 금지
NANOBANANA_MODEL	선택	기본 gemini-3.1-flash-image-preview 오버라이드

G1 게이트: Gemini 외부 호출은 소유자 승인 대상. 미승인 시 워커는 목/degraded로 동작(import·구조 성립, 실이미지 미생성).

---

6. 실행

# 백엔드
export KINTEX_DB_PASSWORD='****'
export KINTEX_JWT_SECRET='****-32bytes이상****'
cd src/backend && ./gradlew bootRun          # 또는 java -jar build/libs/kintex-*.jar

# 프론트 (개발 서버 — axios baseURL=/api, 프록시로 백엔드 연결)
cd src/frontend && npm run dev

# 나노바나나 워커 (G1 승인 후 실호출; 미승인 시 목)
export GEMINI_API_KEY='****'
python -m tools.nanobanana.worker      # 큐 소비 → 콜백(RENDER_WORKER_TOKEN)

헬스체크: GET /health → { "success": true, "data": { "status": "UP", "service": "kintex-backend" } }.

---

7. 참조

• 빌드/배포 개요: BUILD_DEPLOY.md
• 개발 표준: DEVELOPMENT_GUIDE.md
• 나노바나나 워커: ../tools/nanobanana/README.md
• WISE 세팅 원본(참조): workspace/uiws/backend/README.md·workspace/uiws/db/README_DB연동.md