accura/wbx-spring
1
0
포크 0
코드 이슈 풀 리퀘스트 Actions 패키지 프로젝트 릴리즈 위키 활동
파일
85aaebe134af81a685fa0bfc7905439d8f4722d6
wbx-spring/wbx-spring-core/docs/개발환경_사전설치_가이드.txt
accura0117 cda5f9591e feat: React 18 프론트엔드 추가 및 프로젝트 구조 정리 
- wtm-frontend → wtm-frontend-vue 이름 변경
- wtm-frontend-react 추가 (React 18 + PrimeReact + Zustand)
  - 동일한 모듈 구조 및 API 연동 (Vue 버전과 기능 동일)
  - Vue:5173 / React:5174 포트 분리
- 개발자 가이드에 React 프론트엔드 안내 추가
- .gitignore: Claude/OMC, 문서 생성 스크립트, package-lock 제외
- 불필요 파일 git 추적 제거 (.omc, generate_*.py, regenerate_*.py)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-30 20:50:23 +09:00

365 줄
14 KiB
Plaintext
Raw Blame 히스토리

================================================================================
WBX Spring Framework - 개발환경 사전 설치 가이드
Developer Quick Setup Guide v1.0
아큐라시스템 | 2026년 3월
================================================================================
이 문서는 WBX Spring Framework 개발을 시작하기 전에 필요한
소프트웨어 설치 및 환경 설정을 안내합니다.
TIP: scripts\install.bat (Windows) 또는 scripts/install.sh (Linux/macOS)를
실행하면 JDK 자동 설치, 빌드 검증, .env 생성까지 한번에 처리됩니다.
--------------------------------------------------------------------------------
1. 필수 소프트웨어
--------------------------------------------------------------------------------
[1-1] JDK 21 (Eclipse Temurin LTS 권장)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
용도: Spring Boot 3.5 런타임
* Windows
winget install --id EclipseAdoptium.Temurin.21.JDK
* macOS
brew install --cask temurin@21
* Ubuntu/Debian
sudo apt update && sudo apt install -y temurin-21-jdk
(Adoptium 저장소 미등록 시 https://adoptium.net 참고)
* RHEL/Rocky
sudo yum install -y temurin-21-jdk
설치 확인:
java -version
→ openjdk version "21.x.x" 이 출력되면 정상
[1-2] Git
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
용도: 소스 코드 버전 관리, Gitea 저장소 연동
* Windows
winget install --id Git.Git
* macOS
brew install git
* Linux
sudo apt install -y git (Ubuntu)
sudo yum install -y git (RHEL)
설치 확인:
git --version
초기 설정:
git config --global user.name "홍길동"
git config --global user.email "hong@accurasoft.co.kr"
[1-3] IDE (택 1)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------+----------------+------------------------------------+
| IDE | 권장 대상 | 핵심 장점 |
+------------------+----------------+------------------------------------+
| IntelliJ IDEA | 메인 개발 | Spring Boot 최적, 리팩터링, DB |
| VS Code | 경량/FE 병행 | Extension Pack, DevContainer |
| Eclipse/STS | 무료/레거시 | Spring Tool Suite 플러그인 |
+------------------+----------------+------------------------------------+
IntelliJ 필수 플러그인:
- Spring Boot, Lombok, JPA Buddy, GitToolBox, .env, SonarLint
- Settings > Build > Compiler > Annotation Processor 활성화
VS Code 필수 Extension:
- Java Pack, Spring Boot Pack, Lombok, Gradle, REST Client, GitLens
--------------------------------------------------------------------------------
2. 선택 소프트웨어 (권장)
--------------------------------------------------------------------------------
[2-1] Docker Desktop (선택 — DB 컨테이너 사용 시에만 필요)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
용도: 로컬 개발용 DB(MySQL/PostgreSQL)를 컨테이너로 실행
※ Redis는 Embedded Redis가 자동 구동되므로 Docker 불필요
* Windows
winget install --id Docker.DockerDesktop
(설치 후 재부팅 필요)
* macOS
brew install --cask docker
설치 확인:
docker --version
docker compose version
주의: Docker Desktop은 대규모 기업(250명+/매출 $10M+) 유료 라이선스입니다.
대안으로 Rancher Desktop, Podman Desktop 사용 가능합니다.
[2-2] DB 직접 설치 (Docker 미사용 시)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
아래 중 프로젝트에 맞는 DBMS 1개를 선택하여 설치합니다.
+------------------+----------+------------------------------------------+
| DBMS | 버전 | 설치 |
+------------------+----------+------------------------------------------+
| MySQL | 8.0+ | winget install Oracle.MySQL |
| PostgreSQL | 14+ | winget install PostgreSQL.PostgreSQL |
| Oracle | 19c+ | 고객 DBA 설치/관리 |
| MSSQL | 2019+ | winget install Microsoft.SQLServer.2022 |
+------------------+----------+------------------------------------------+
DB 생성 예시 (MySQL):
CREATE DATABASE mos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'jsh'@'%' IDENTIFIED BY 'jsh@';
GRANT ALL ON mos.* TO 'jsh'@'%';
[2-3] Node.js (프론트엔드 개발 시 필요)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
용도: WTM 프론트엔드 개발 서버 실행 (Vue 3 또는 React 18)
* Windows
winget install --id OpenJS.NodeJS.LTS
* macOS
brew install node@22
* Linux
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs
설치 확인:
node -v → v22.x.x
npm -v → 10.x.x
프론트엔드 선택:
+----------------------+------------------+----------+---------------------+
| 프로젝트 | 프레임워크 | 포트 | UI 라이브러리 |
+----------------------+------------------+----------+---------------------+
| wtm-frontend-vue | Vue 3 + Vite | 5173 | PrimeVue 4 |
| wtm-frontend-react | React 18 + Vite | 5174 | PrimeReact 10 |
+----------------------+------------------+----------+---------------------+
두 프론트엔드는 동일한 백엔드 API(wtm-api :8081)에 연결됩니다.
프로젝트 상황에 맞는 프레임워크를 선택하세요.
빠른 시작:
# Vue 3 버전
cd wtm-frontend-vue
npm install && npm run dev → http://localhost:5173
# React 18 버전
cd wtm-frontend-react
npm install && npm run dev → http://localhost:5174
[2-4] Redis (설치 불필요)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
용도: 캐시, 세션 저장소
※ WBX Spring Framework에 Embedded Redis가 내장되어 있어 별도 설치가
필요하지 않습니다. 앱 시작 시 다음 순서로 자동 동작합니다:
1) 외부 Redis 감지 → 그대로 사용 (운영 환경)
2) 외부 Redis 없음 → Embedded Redis 자동 시작 (개발 환경)
3) Embedded Redis 실패 → 인메모리 캐시 전환 (최후 안전장치)
운영 환경에서 외부 Redis를 사용하려면 .env에 설정:
SPRING_DATA_REDIS_HOST=redis.company.com
--------------------------------------------------------------------------------
3. 빠른 시작 (Quick Start)
--------------------------------------------------------------------------------
아래 명령어를 순서대로 실행하면 개발 환경이 완성됩니다.
[방법 A] Docker 사용 (권장, 3분)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# 1) 소스 클론
git clone https://git.wbx.kr/accura/wbx-spring-core.git
cd wbx-spring-core
# 2) 설치 스크립트 실행 (JDK 자동 설치 + 빌드 + .env 생성)
scripts\install.bat (Windows)
./scripts/install.sh (Linux/macOS)
# 3) Docker로 MySQL 시작 (Redis는 Embedded Redis 자동 구동)
docker compose -f docker-compose-dev.yml up -d
# 4) .env 파일 수정 (DB 비밀번호를 docker-compose 설정에 맞춤)
# DB_USER=jsh
# DB_PASS=jsh@
# JWT_SECRET=dev-secret-key-for-local-development-only
# 5) 앱 실행
gradlew.bat bootRun (Windows)
./gradlew bootRun (Linux/macOS)
# 6) 확인
http://localhost:8080/actuator/health → {"status":"UP"}
http://localhost:8080/swagger-ui → API 문서
http://localhost:8080/admin/login → 관리 콘솔
[WTM 프로젝트 사용 시]
cd wtm-api
gradlew.bat :wtm-api:bootRun (Windows)
./gradlew :wtm-api:bootRun (Linux/macOS)
http://localhost:8081/actuator/health → {"status":"UP"}
http://localhost:8081/swagger-ui → WTM API 문서
http://localhost:8081/admin/login → WTM 관리 콘솔
[WTM 프론트엔드 실행 — Vue 3 또는 React 18 중 택 1]
# Vue 3 버전
cd wtm-frontend-vue
npm install && npm run dev
http://localhost:5173 → WTM 프론트엔드 (Vue 3)
# React 18 버전
cd wtm-frontend-react
npm install && npm run dev
http://localhost:5174 → WTM 프론트엔드 (React 18)
[방법 B] DB 직접 설치 (Docker 없이)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# 1~2) 위와 동일 (클론 + install 스크립트)
# 3) MySQL/PostgreSQL 설치 후 DB 생성
# 위 [2-2] 참고
# (Redis는 Embedded Redis 자동 구동 — 설치 불필요)
# 4) .env 파일을 실제 DB 정보에 맞게 수정
# 5~6) 앱 실행 및 확인 (위와 동일)
--------------------------------------------------------------------------------
4. Docker Compose 서비스 구성
--------------------------------------------------------------------------------
docker-compose-dev.yml 에 포함된 서비스:
+------------------+--------+----------+------------------------------+
| 서비스 | 포트 | 계정 | 비고 |
+------------------+--------+----------+------------------------------+
| MySQL 8.0 | 3306 | jsh | PW: jsh@ (기본 프로필) |
| | | | root PW: rootpassword |
| PostgreSQL 16 | 5432 | jsh | PW: jsh@ (--profile pg) |
| Redis 7 | 6379 | - | Embedded Redis 자동 구동 |
+------------------+--------+----------+------------------------------+
프로필별 실행:
docker compose -f docker-compose-dev.yml up -d # MySQL + Redis
docker compose -f docker-compose-dev.yml --profile pg up -d # PostgreSQL + Redis
--------------------------------------------------------------------------------
5. .env 설정 가이드
--------------------------------------------------------------------------------
.env 파일은 install 스크립트가 자동 생성합니다.
아래 항목을 환경에 맞게 수정하세요.
[필수 수정]
JWT_SECRET 운영: 256bit 이상 랜덤 키
개발: dev-secret-key-for-local-development-only
DB_PASS 실제 DB 비밀번호
[환경별 수정]
SPRING_PROFILES_ACTIVE 프로필 조합 (아래 참고)
DB_HOST / DB_PORT DB 서버 주소
CORS_ORIGINS 프론트엔드 URL (Vue: 5173, React: 5174)
[프로필 조합 예시]
로컬 개발 (MySQL) : local,mysql
로컬 개발 (PostgreSQL): local,postgresql
운영 (Azure + MSSQL) : prod,azure,mssql
운영 (AWS + PG) : prod,aws,postgresql
운영 (On-Premise) : prod,mysql 또는 prod,oracle
--------------------------------------------------------------------------------
6. 네트워크 포트 요약
--------------------------------------------------------------------------------
+--------+------------------+------------------------------------------+
| 포트 | 서비스 | 비고 |
+--------+------------------+------------------------------------------+
| 8080 | wbx-spring-core | API, Admin, Health, Swagger |
| 8081 | wtm-api | WTM API, Admin, Swagger |
| 3306 | MySQL | 기본 DB (mysql 프로필) |
| 5432 | PostgreSQL | 대안 DB (postgresql 프로필) |
| 6379 | Redis | Embedded Redis 자동 구동 (별도 설치 불필요)|
| 5173 | wtm-frontend-vue | Vue 3 개발 서버 |
| 5174 | wtm-frontend-react| React 18 개발 서버 |
| 8001 | WBX FastAPI | 선택, 그룹웨어 동시 운영 시 |
+--------+------------------+------------------------------------------+
--------------------------------------------------------------------------------
7. 트러블슈팅
--------------------------------------------------------------------------------
Q: install.bat 실행 시 "java 명령어 없음"
A: 스크립트가 자동으로 JDK 21을 설치합니다. 실패 시 수동 설치:
winget install --id EclipseAdoptium.Temurin.21.JDK
Q: gradlew.bat 실행 시 "not recognized"
A: 프로젝트 루트(wbx-spring-core/) 에서 실행하세요.
또는 scripts\run-install.bat 을 사용하세요.
Q: bootRun 시 DB 연결 실패
A: 1) docker compose -f docker-compose-dev.yml up -d 로 DB 시작
2) .env 파일의 DB_HOST, DB_PORT, DB_PASS 확인
3) telnet localhost 3306 으로 연결 가능 여부 확인
Q: Redis 관련 로그가 나옴
A: Embedded Redis가 자동 구동됩니다. 별도 조치 불필요.
로그에 "[WBX] Embedded Redis 시작" 출력 시 정상 동작.
포트 6379가 이미 사용 중이면 외부 Redis를 자동 감지하여 사용합니다.
Q: Lombok 관련 컴파일 에러
A: IDE에서 Annotation Processor 활성화 필요
IntelliJ: Settings > Build > Compiler > Annotation Processors > Enable
Q: 포트 충돌 (8080 이미 사용 중)
A: netstat -ano | findstr :8080 으로 프로세스 확인 후 종료
또는 application.yml에서 server.port 변경
Q: 프론트엔드(Vue/React) npm install 실패
A: Node.js 22 LTS가 설치되어 있는지 확인: node -v
node_modules 삭제 후 재설치: rm -rf node_modules && npm install
Q: 프론트엔드에서 API 호출 시 CORS 에러
A: wtm-api의 application.yml에서 CORS 설정 확인:
cors.allowed-origins에 http://localhost:5173, http://localhost:5174 포함 필요
또는 .env에서 CORS_ORIGINS 설정
Q: Vue(5173)와 React(5174) 동시 실행 가능한가?
A: 네, 포트가 다르므로 동시 실행 가능합니다. 둘 다 동일한 wtm-api(:8081)에
연결되며 API 프록시가 각각 설정되어 있습니다.
--------------------------------------------------------------------------------
8. 참고 문서
--------------------------------------------------------------------------------
docs/WBX_Spring_Framework_개발자가이드.pdf 개발자 상세 가이드
docs/WBX_Spring_Framework_설치가이드_OnPremise.pdf 운영 서버 설치 가이드
docs/WBX_Spring_Framework_설치가이드_Cloud.pdf 클라우드 배포 가이드
================================================================================
문의: accura@accurasoft.co.kr
================================================================================
새 Issue에서 참조 Git Blame 보기 고유 링크 복사