Skip to content

Development_Guide.md

Latest commit

 

History

History
310 lines (218 loc) · 7.87 KB

Development_Guide.md

File metadata and controls

310 lines (218 loc) · 7.87 KB

🚀 Project Nexus 개발 가이드

이 문서는 Project Nexus의 개발 환경 구성 및 실행 방법을 안내합니다.

📋 사전 요구사항

필수 소프트웨어

  • Java Development Kit (JDK): Java 21 (LTS)
  • Docker & Docker Compose: 최신 버전 (Docker Compose V2 Spec 지원)
    • 설치 확인: docker --version, docker compose version
    • 다운로드: Docker Desktop
  • Git: 버전 관리
    • 설치 확인: git --version

권장 도구

  • IDE: IntelliJ IDEA (Ultimate 또는 Community Edition) 또는 VS Code
  • API 테스트: Postman, Insomnia, 또는 curl
  • DB 클라이언트: DBeaver, pgAdmin (PostgreSQL용)

🏗️ 프로젝트 구조

NexusProject/
├── Nexus/                          # 루트 프로젝트
│   ├── order-service/              # Order Service (주문 서비스)
│   ├── inventory-service/          # Inventory Service (재고 서비스)
│   ├── compose.yaml                # Docker Compose 설정 (V2 Spec)
│   └── settings.gradle.kts        # 멀티 프로젝트 설정
├── Development_Guide.md            # 이 문서
└── Plan.md                         # 개발 계획

🚀 로컬 환경 구성

1단계: 저장소 클론 및 이동

# 프로젝트 디렉토리로 이동
cd NexusProject

2단계: Docker Compose로 인프라 실행

# PostgreSQL, Kafka, Redis 컨테이너 시작
docker compose -f Nexus/compose.yaml up -d

# 컨테이너 상태 확인
docker compose -f Nexus/compose.yaml ps

# 로그 확인
docker compose -f Nexus/compose.yaml logs -f

실행되는 서비스:

  • PostgreSQL 16: localhost:5432
    • Order DB: nexus_order (user: nexus, password: nexus123)
    • Inventory DB: nexus_inventory (user: nexus, password: nexus123)
  • Apache Kafka 3.8.0: localhost:9092
  • Redis 7.2.x: localhost:6379

3단계: 서비스 빌드 및 실행

Option A: Gradle로 직접 실행 (개발 모드)

# Order Service 실행
cd Nexus/order-service
./gradlew bootRun

# Inventory Service 실행 (새 터미널)
cd Nexus/inventory-service
./gradlew bootRun

Option B: Docker Compose로 전체 실행

# 모든 서비스 빌드 및 실행
docker compose -f Nexus/compose.yaml up --build

# 백그라운드 실행
docker compose -f Nexus/compose.yaml up -d --build

🧪 테스트 실행

단위 테스트

# 모든 서비스 테스트
cd Nexus
./gradlew test

# 특정 서비스 테스트
./gradlew :order-service:test
./gradlew :inventory-service:test

통합 테스트 (Testcontainers)

# 통합 테스트 실행 (Docker 필요)
./gradlew integrationTest

📊 모니터링 및 관찰성

Prometheus & Grafana (Week 2 이후)

# Prometheus 접속
http://localhost:9090

# Grafana 접속
http://localhost:3000
# 기본 계정: admin / admin

Actuator 엔드포인트

  • Order Service: http://localhost:8080/actuator
  • Inventory Service: http://localhost:8081/actuator
  • Prometheus 메트릭: http://localhost:8080/actuator/prometheus

🔧 개발 워크플로우

1. 코드 변경 후 재빌드

# 특정 서비스만 재빌드
./gradlew :order-service:build

# 전체 재빌드
./gradlew build

2. 데이터베이스 마이그레이션 (Flyway)

Flyway는 애플리케이션 시작 시 자동으로 실행됩니다. 수동 실행이 필요한 경우:

# Flyway 마이그레이션 정보 확인
./gradlew :order-service:flywayInfo

# Flyway 마이그레이션 실행
./gradlew :order-service:flywayMigrate

3. 로그 확인

# Docker Compose 로그
docker compose -f Nexus/compose.yaml logs -f order-service
docker compose -f Nexus/compose.yaml logs -f inventory-service

# Kafka 로그
docker compose -f Nexus/compose.yaml logs -f kafka

🐛 문제 해결

포트 충돌

다음 포트가 사용 중인 경우 변경이 필요합니다:

  • 5432 (PostgreSQL)
  • 9092 (Kafka)
  • 6379 (Redis)
  • 8080 (Order Service)
  • 8081 (Inventory Service)

compose.yaml에서 포트 매핑을 수정하세요.

데이터베이스 초기화

# 모든 컨테이너 및 볼륨 삭제
docker compose -f Nexus/compose.yaml down -v

# 재시작
docker compose -f Nexus/compose.yaml up -d

Kafka 토픽 확인

# Kafka 컨테이너 접속
docker compose -f Nexus/compose.yaml exec kafka bash

# 토픽 목록 확인
kafka-topics.sh --bootstrap-server localhost:9092 --list

# 토픽 메시지 확인
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic order-events --from-beginning

📚 추가 리소스

🔐 환경 변수

개발 환경에서는 기본값을 사용하지만, 운영 환경에서는 다음 환경 변수를 설정하세요:

# Order Service
ORDER_DB_URL=jdbc:postgresql://postgres:5432/nexus_order
ORDER_DB_USERNAME=nexus
ORDER_DB_PASSWORD=nexus123
KAFKA_BOOTSTRAP_SERVERS=kafka:9092

# Inventory Service
INVENTORY_DB_URL=jdbc:postgresql://postgres:5432/nexus_inventory
INVENTORY_DB_USERNAME=nexus
INVENTORY_DB_PASSWORD=nexus123
KAFKA_BOOTSTRAP_SERVERS=kafka:9092

🔒 CI/CD 보안 설정 (GitHub Secrets)

CI/CD 파이프라인에서 민감한 정보(비밀번호, DB 연결 정보 등)를 안전하게 관리하기 위해 GitHub Secrets를 사용합니다.

GitHub Secrets 설정 방법

  1. GitHub 저장소로 이동

    • 저장소 페이지에서 Settings → Secrets and variables → Actions 클릭

  2. 필수 Secrets 추가

    다음 Secrets를 추가해야 합니다:

    Secret 이름 설명 예시 값
    POSTGRES_USER PostgreSQL 사용자명 nexus
    POSTGRES_PASSWORD PostgreSQL 비밀번호 (강력한 비밀번호)
    POSTGRES_ORDER_DB Order Service 데이터베이스명 nexus_order
    POSTGRES_INVENTORY_DB Inventory Service 데이터베이스명 nexus_inventory
    DOCKER_USERNAME Docker Hub 사용자명 (Docker Hub 계정)
    DOCKER_PASSWORD Docker Hub 비밀번호/토큰 (Docker Hub 토큰)

  3. Secrets 추가 절차

    • New repository secret 버튼 클릭
    • Name에 Secret 이름 입력 (예: POSTGRES_PASSWORD)
    • Secret에 실제 값 입력
    • Add secret 클릭

보안 모범 사례

✅ 해야 할 것:

  • 모든 민감한 정보는 GitHub Secrets 사용
  • 강력한 비밀번호 사용 (최소 16자, 특수문자 포함)
  • 정기적으로 비밀번호 변경
  • 프로덕션과 개발 환경의 Secrets 분리

❌ 하지 말아야 할 것:

  • 코드에 비밀번호 하드코딩 금지
  • Git 히스토리에 민감한 정보 커밋 금지
  • Secrets를 로그에 출력하지 않기

Secrets 사용 예시

CI/CD 워크플로우에서 Secrets는 다음과 같이 사용됩니다:

env:
  POSTGRES_USER: ${{ secrets.POSTGRES_USER }}
  POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}

⚠️ 주의: Secrets는 GitHub Actions 실행 시에만 사용 가능하며, 저장소 설정에서만 관리할 수 있습니다.

✅ 체크리스트

개발 시작 전 확인사항:

  • Java 21 설치 및 확인
  • Docker & Docker Compose 설치 및 확인
  • 프로젝트 클론 완료
  • docker compose up -d 실행 성공
  • PostgreSQL, Kafka, Redis 컨테이너 정상 실행 확인
  • 서비스 빌드 성공 (./gradlew build)
  • 서비스 실행 성공 (./gradlew bootRun)