diff --git a/docs/개발환경_사전설치_가이드.txt b/docs/개발환경_사전설치_가이드.txt new file mode 100644 index 0000000..3d43e02 --- /dev/null +++ b/docs/개발환경_사전설치_가이드.txt @@ -0,0 +1,289 @@ +================================================================================ + 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 wbx_spring CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + CREATE USER 'wbxapp'@'localhost' IDENTIFIED BY 'password'; + GRANT ALL ON wbx_spring.* TO 'wbxapp'@'localhost'; + + + [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=wbxapp + # DB_PASS=password + # JWT_SECRET=dev-secret-key-for-local-development-only + + # 5) 앱 실행 + gradlew.bat bootRun (Windows) + ./gradlew bootRun (Linux/macOS) + + # 6) 확인 + http://localhost:8080/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 | wbxapp | PW: password (기본 프로필) | + | | | | root PW: rootpassword | + | PostgreSQL 16 | 5432 | wbxapp | PW: password (--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 +================================================================================