Ch 2. 로컬 환경 셋업¶

1. 로컬 실행 구조 이해¶

hera-v4는 MSA 구조라서 실행에 필요한 서비스가 여러 개입니다. 다만 신규 개발자가 처음부터 모든 서비스를 로컬에 띄울 필요는 없습니다.

이 챕터의 목표는 hera-webapp을 로컬에서 띄우고 사내 개발 서버 백엔드에 붙이는 것입니다.

2. 사전 요구사항¶

2.1 JDK 25¶

hera-v4는 Java 25의 Virtual Thread를 사용하므로 JDK 25가 필수입니다.

java -version
# 출력 예: openjdk version "25" ...

JDK 25가 없으면 Amazon Corretto 25 또는 팀에서 제공하는 JDK 배포본을 설치합니다.

JDK가 여러 버전 깔려 있는 경우 JAVA_HOME이 JDK 25를 가리키는지 확인합니다.

echo $JAVA_HOME
# 예(macOS): /Library/Java/JavaVirtualMachines/amazon-corretto-25.jdk/Contents/Home

2.2 IntelliJ IDEA¶

hera-v4 팀의 주 IDE는 IntelliJ IDEA입니다. Gradle 멀티 모듈 프로젝트를 제대로 임포트하려면 IntelliJ를 사용하세요.

2.3 라이선스 파일¶

hera-v4는 내부 프레임워크 라이선스 파일이 필요합니다. 팀 리더 또는 선임 개발자에게 다음 파일을 받아 {레포 루트}/_temp/certs/ 경로에 둡니다.

hera-v4/
└── _temp/
    └── certs/
        ├── hera-license.lic         # 프레임워크 라이선스
        ├── hera-certs-public.ks     # 공개 키스토어
        └── hera-ks.p12              # webapp HTTPS용 키스토어

3. 레포 클론¶

사내 Git 서버에서 hera-v4 레포 주소를 확인한 뒤 클론합니다.

git clone {hera-v4 레포 주소}
cd hera-v4
mkdir -p _temp/certs

4. Nexus 의존성 확인¶

hera-v4는 사내 Maven 저장소(Nexus)에서 내부 라이브러리를 내려받습니다. gradle.properties에 Nexus 접속 정보가 이미 들어 있어 별도 설정은 필요 없습니다.

사내망에 접속한 상태에서 nexus.dandisoft.co.kr에 닿으면 의존성 다운로드가 자동으로 진행됩니다.

5. 빌드¶

5.1 Gradle Wrapper로 빌드¶

처음 빌드할 때는 Nexus에서 의존성을 내려받느라 시간이 걸립니다. -x test 옵션으로 테스트를 건너뛰면 빌드 시간이 줄어듭니다.

./gradlew build -x test

빌드 성공 메시지 예:

BUILD SUCCESSFUL in 2m 14s

5.2 IntelliJ로 임포트¶

1. IntelliJ에서 File → Open → hera-v4 루트 디렉토리 선택
2. "Open as Gradle Project" 선택
3. Gradle 빌드가 끝날 때까지 대기 (우하단 진행 표시줄 확인)

빌드가 끝나면 좌측 프로젝트 트리에 14개 모듈이 보입니다. Project SDK가 JDK 25로 잡혀 있는지 확인합니다 (File → Project Structure → SDK).

Unsupported class file major version 69

6. hera-webapp 로컬 실행¶

6.1 실행 전 확인¶

실행 전에 다음 두 가지를 반드시 확인합니다.

6.2 실행¶

./gradlew :hera-webapp:bootRun

IntelliJ에서 실행하는 경우: hera-webapp/src/main/java/…/HeraWebappApplication.java → 우클릭 → Run 'HeraWebappApplication'

6.3 기동 확인¶

로그에서 다음 메시지를 확인합니다.

Started HeraWebappApplication in X.XXX seconds

6.4 브라우저 접속¶

https://localhost:8000

로그인 화면이 뜨면 로컬 실행에 성공한 것입니다.

7. 실행 흐름 확인¶

로그인 화면에서 사내 계정으로 로그인한 뒤, 브라우저 개발자 도구의 Network 탭을 열고 /api/sys/ 경로로 시작하는 요청을 확인합니다.

요청이 정상 응답(200)을 받으면 webapp → API Gateway → bootstrap-system 연결이 정상이라는 뜻입니다.

8. 백엔드도 로컬에서 실행하는 경우¶

사내 개발 서버 없이 모든 서비스를 로컬에서 띄워야 하는 경우(예: 오프라인 개발) 순서입니다. 일반적인 개발 환경에서는 필요 없습니다.

# 1. Service Discovery (Eureka) — 포트 8761
./gradlew :_msa-service-discovery:bootRun

# 2. API Gateway — 포트 18000
./gradlew :_msa-api-gateway:bootRun

# 3. System 서비스 — 포트 18010
./gradlew :bootstrap-system:bootRun

# 4. Webapp — 포트 8000
./gradlew :hera-webapp:bootRun

Service Discovery가 가장 먼저 떠 있어야 합니다. 이후 서비스가 Eureka에 자신을 등록하기 때문입니다.

bootstrap-system을 로컬에서 띄울 때는 application-routes.yml에서 sys 엔드포인트를 로컬 주소로 바꿉니다.

# hera-webapp/src/main/resources/application-routes.yml
api-gateway:
  sys: http://127.0.0.1:18010   # 주석 처리된 줄을 활성화

9. 서비스 포트 요약¶

10. 자주 발생하는 문제¶

11. 이 챕터 요약¶