개발 환경 설정
프로젝트를 처음 받아 실행하기까지의 전 과정입니다.
필수 도구
| 도구 | 버전 | 설치 방법 |
|---|---|---|
| JDK | 21 | SDKMAN |
| Node.js | 22.22+ 또는 24.12+ | nvm |
| Gradle | — | 설치 불필요 (wrapper 포함) |
JDK 는 반드시 21 이어야 합니다
Spring Boot 4.x 는 JDK 17 에서 동작하지 않습니다.
SDKMAN + JDK
여러 프로젝트를 오가면 JDK 버전도 여러 개가 필요합니다. SDKMAN 으로 전환하며 쓰는 것을 권장합니다.
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk list java # 설치 가능 목록
sdk install java 21.0.5-tem
sdk use java 21.0.5-tem # 현재 셸에만 적용
sdk default java 21.0.5-tem # 기본값으로
java -version # 확인프로젝트별 자동 전환
프로젝트 루트에 .sdkmanrc 를 두면 디렉토리 진입 시 자동 전환됩니다.
java=21.0.5-temnvm + Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install lts/jod # Node 22.22+
nvm use lts/jod
node -v # v22.22.0 이상 확인두 프론트엔드 모두 Node 22.22 이상이 필요합니다
@quasar/app-vite 3 이 ^22.22.0 || >=24.12.0 을 요구합니다. Node 20 은 지원되지 않습니다.
node -v # v22.22.0 이상이어야 합니다.nvmrc 가 있는 디렉토리에서는 nvm use 만 치면 맞는 버전으로 전환됩니다.
Gradle 은 설치하지 않습니다
프로젝트에 wrapper 가 포함돼 있습니다. 항상 ./gradlew 를 쓰세요.
./gradlew --version # Gradle 8.14왜 wrapper 를 쓰나
팀원마다 다른 Gradle 버전을 쓰면 빌드 결과가 달라질 수 있습니다. wrapper 는 프로젝트가 요구하는 버전을 자동으로 내려받아 사용합니다.
macOS 준비 (Mac 사용자)
Xcode Command Line Tools 가 있어야 git 등 기본 개발 도구가 동작합니다.
xcode-select --install프로젝트 실행
1. 빌드
./gradlew build # 전체 빌드
./gradlew :iflex-core:publishToMavenLocal # core 를 로컬 저장소에 설치2. 백엔드 실행
# 관리자 API
./gradlew :iflex-cms-backend:bootRun
# 프로필 지정 (local(기본) / dev / staging / prod)
./gradlew :iflex-cms-backend:bootRun -PactiveProfiles=dev,redis
# 사용자 API
./gradlew :iflex-channel-vue-backend:bootRunJVM 옵션이 없으면 기동에 실패합니다
-Duser.timezone=UTC 가 없으면 애플리케이션이 의도적으로 기동을 거부합니다. 프로젝트가 시각을 UTC 로 고정해 다루기 때문입니다.
./gradlew bootRun 으로 실행하면 자동 적용되지만, IntelliJ 의 Run Configuration 으로 직접 실행할 때는 직접 넣어야 합니다.
-Duser.timezone=UTC
--add-opens java.desktop/java.awt.font=ALL-UNNAMED
--add-opens java.base/java.text=ALL-UNNAMED
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.io=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.util.concurrent=ALL-UNNAMED--add-opens 가 빠지면 리플렉션 관련 에러가 납니다. 테스트를 IntelliJ 자체 러너로 돌릴 때도 -Duser.timezone=UTC 가 필요합니다.
3. 프론트엔드 실행
# 관리자 UI (CSR)
cd cms/frontend
npm install
npm run dev
# 사용자 UI (SSR)
cd channel-vue/frontend
npm install
npm run dev:ssr프론트 개발 서버는 /api 요청을 백엔드로 프록시합니다. 대상 주소는 .env 의 VITE_API_BASE_URL 로 지정합니다.
4. 데이터베이스
neo-sql/{dbms}/ 의 스크립트를 순서대로 실행합니다.
neo-sql/mysql/
├── 01.*.sql
├── ...
└── 99.etc.sql ← nv_attach 등 공통 테이블Docker 로 띄우기
docker/ 에 환경별 docker-compose 파일이 있습니다. DB·Redis 를 한 번에 올릴 수 있습니다.
IntelliJ 설정
Run/Debug Configuration
| 항목 | 값 |
|---|---|
| Working directory | $MODULE_WORKING_DIR$ |
| VM options | 위 JVM 옵션 블록 전체 (백엔드 실행 절 참고) |
코드 스타일
프로젝트 루트의 .editorconfig 가 적용됩니다. 별도 설정 없이 자동 반영됩니다.
//@formatter:off 마커를 활성화하세요
SQL DSL 코드는 키워드 우측정렬 규칙을 씁니다. IntelliJ 자동 포맷이 이를 망가뜨리지 않도록 .editorconfig 에 포맷터 마커가 설정돼 있습니다.
Preferences → Editor → Code Style → Enable formatter markers in comments 가 켜져 있는지 확인하세요.
디렉토리 구성 (선택)
여러 프로젝트를 다루게 되므로, 정리 규칙을 하나 정해두면 편합니다. 팀에서 쓰는 구성은 다음과 같습니다.
~/Project/
├── 01.current/ 진행 중
└── 02.archive/ 보관
/Applications/Tools/
├── build/
└── was/TIP
어디까지나 참고입니다. 본인에게 편한 구성이 있으면 그대로 쓰셔도 됩니다.
자주 겪는 문제
기동하자마자 타임존 관련 에러로 죽습니다
-Duser.timezone=UTC 가 빠졌습니다. 백엔드 실행 절의 JVM 옵션 참고. application.timezone.enforce-utc=true 가 기본값이라 의도적으로 기동을 막는 것입니다.
InaccessibleObjectException 같은 리플렉션 에러가 납니다
--add-opens 옵션이 빠졌습니다. 6줄 전부 필요합니다.
npm install 이 실패합니다
Node 버전을 확인하세요. 두 프론트엔드 모두 22.22 미만에서는 동작하지 않습니다.
node -v
nvm use lts/jodcore 를 고쳤는데 다른 모듈에 반영이 안 됩니다
core 는 라이브러리 모듈이라 로컬 저장소에 다시 설치해야 할 수 있습니다.
./gradlew :iflex-core:publishToMavenLocal