================================================================================ 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] 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 관리 콘솔 [방법 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 [프로필 조합 예시] 로컬 개발 (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 3 개발 서버 | | 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 변경 -------------------------------------------------------------------------------- 8. 참고 문서 -------------------------------------------------------------------------------- docs/WBX_Spring_Framework_개발자가이드.pdf 개발자 상세 가이드 docs/WBX_Spring_Framework_설치가이드_OnPremise.pdf 운영 서버 설치 가이드 docs/WBX_Spring_Framework_설치가이드_Cloud.pdf 클라우드 배포 가이드 ================================================================================ 문의: accura@accurasoft.co.kr ================================================================================