================================================================================ 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 ================================================================================