accura0117
df723f1d59
Phase 0: wbx-spring-core 라이브러리 전환 - java-library 플러그인, WbxAutoConfiguration, Admin 조건부 활성화 - 루트 settings.gradle + build.gradle (멀티모듈) Phase 1: wtm-api 모듈 생성 - 23개 JPA Entity, 14개 Controller, 79개 API 엔드포인트 - Flyway V100~V107 MySQL 마이그레이션 - TimesheetRuleEngine, TimesheetApprovalHandler, P6WbsParser Phase 2: wtm-frontend (Vue 3 + PrimeVue 4) - 10개 도메인 모듈, 17개 View, 5개 서브컴포넌트 - 반응형 레이아웃 (AppLayout, AppSidebar, AppTopbar) - BaseCrudTable, BaseFormDialog, BasePageHeader 표준 컴포넌트 - JWT 인터셉터, 역할 기반 메뉴 필터링 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
290 줄
11 KiB
Plaintext
290 줄
11 KiB
Plaintext
================================================================================
|
|
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(MySQL/PostgreSQL) + Redis를 컨테이너로 실행
|
|
|
|
* 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] Redis
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
용도: 캐시, 세션 저장소
|
|
|
|
* Windows (Docker 권장, 네이티브 미지원)
|
|
docker run -d -p 6379:6379 redis:7-alpine
|
|
|
|
* macOS
|
|
brew install redis && brew services start redis
|
|
|
|
* Linux
|
|
sudo apt install -y redis-server (Ubuntu)
|
|
sudo yum install -y redis (RHEL)
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
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 시작
|
|
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 → 관리 콘솔
|
|
|
|
|
|
[방법 B] DB 직접 설치 (Docker 없이)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
# 1~2) 위와 동일 (클론 + install 스크립트)
|
|
|
|
# 3) MySQL/PostgreSQL 설치 후 DB 생성
|
|
# 위 [2-2] 참고
|
|
|
|
# 4) Redis 설치
|
|
# 위 [2-3] 참고
|
|
|
|
# 5) .env 파일을 실제 DB 정보에 맞게 수정
|
|
|
|
# 6~7) 앱 실행 및 확인 (위와 동일)
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
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 | - | 인증 없음 (개발용) |
|
|
+------------------+--------+----------+------------------------------+
|
|
|
|
프로필별 실행:
|
|
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
|
|
|
|
[프로필 조합 예시]
|
|
로컬 개발 (MySQL) : local,mysql
|
|
로컬 개발 (PostgreSQL): local,postgresql
|
|
운영 (Azure + MSSQL) : prod,azure,mssql
|
|
운영 (AWS + PG) : prod,aws,postgresql
|
|
운영 (On-Premise) : prod,mysql 또는 prod,oracle
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
6. 네트워크 포트 요약
|
|
--------------------------------------------------------------------------------
|
|
|
|
+--------+------------------+------------------------------------------+
|
|
| 포트 | 서비스 | 비고 |
|
|
+--------+------------------+------------------------------------------+
|
|
| 8080 | Spring Boot | API, Admin, Health, Swagger |
|
|
| 3306 | MySQL | 기본 DB (mysql 프로필) |
|
|
| 5432 | PostgreSQL | 대안 DB (postgresql 프로필) |
|
|
| 6379 | Redis | 캐시, 세션 |
|
|
| 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: docker ps 에서 redis 컨테이너 실행 중인지 확인
|
|
또는 Redis를 직접 설치하고 기본 포트(6379) 확인
|
|
|
|
Q: Lombok 관련 컴파일 에러
|
|
A: IDE에서 Annotation Processor 활성화 필요
|
|
IntelliJ: Settings > Build > Compiler > Annotation Processors > Enable
|
|
|
|
Q: 포트 충돌 (8080 이미 사용 중)
|
|
A: netstat -ano | findstr :8080 으로 프로세스 확인 후 종료
|
|
또는 application.yml에서 server.port 변경
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
8. 참고 문서
|
|
--------------------------------------------------------------------------------
|
|
|
|
docs/WBX_Spring_Framework_개발자가이드.pdf 개발자 상세 가이드
|
|
docs/WBX_Spring_Framework_설치가이드_OnPremise.pdf 운영 서버 설치 가이드
|
|
docs/WBX_Spring_Framework_설치가이드_Cloud.pdf 클라우드 배포 가이드
|
|
|
|
|
|
================================================================================
|
|
문의: accura@accurasoft.co.kr
|
|
================================================================================
|