kt-event-marketing/deployment/container/build-image.md

Event Service 컨테이너 이미지 빌드 가이드

1. 빌드 일시

• 빌드 날짜: 2025-10-28
• 빌드 시간: 14:35 KST

2. 수정 사항

2.1 타입 불일치 수정

Event Service 컴파일 오류 해결을 위해 다음 파일들을 수정했습니다:

UserPrincipal.java (common 모듈)

• 파일 경로: common/src/main/java/com/kt/event/common/security/UserPrincipal.java
• 수정 내용: userId와 storeId 타입을 Long에서 UUID로 변경
• 변경 이유: EventService의 메서드 시그니처가 UUID를 기대하므로 일관성 유지

// Before
private final Long userId;
private final Long storeId;

// After
private final UUID userId;
private final UUID storeId;

JwtTokenProvider.java (common 모듈)

• 파일 경로: common/src/main/java/com/kt/event/common/security/JwtTokenProvider.java
• 수정 내용: JWT 토큰 파싱 시 Long.parseLong()을 UUID.fromString()으로 변경
• 변경 이유: UserPrincipal의 타입 변경에 따른 파싱 로직 수정

// Before
Long userId = Long.parseLong(claims.getSubject());
Long storeId = storeIdStr != null ? Long.parseLong(storeIdStr) : null;

// After
UUID userId = UUID.fromString(claims.getSubject());
UUID storeId = storeIdStr != null ? UUID.fromString(storeIdStr) : null;

event-service/build.gradle

• 수정 내용: bootJar 설정 추가
• 변경 이유: 컨테이너 이미지 빌드를 위한 JAR 파일명 명시

bootJar {
    archiveFileName = 'event-service.jar'
}

3. 빌드 명령어

3.1 Common 모듈 컴파일

./gradlew common:compileJava

결과: BUILD SUCCESSFUL in 6s

3.2 Event Service 컴파일

./gradlew event-service:compileJava

결과: BUILD SUCCESSFUL in 6s

3.3 Event Service JAR 빌드

./gradlew event-service:bootJar

결과:

• BUILD SUCCESSFUL in 5s
• JAR 파일 생성: event-service/build/libs/event-service.jar (94MB)

3.4 Docker 이미지 빌드

docker build \
  --platform linux/amd64 \
  --build-arg BUILD_LIB_DIR="event-service/build/libs" \
  --build-arg ARTIFACTORY_FILE="event-service.jar" \
  -f deployment/container/Dockerfile-backend \
  -t event-service:latest .

결과: 이미지 빌드 성공

• Image ID: bbeecf2ccaf2
• Size: 1.08GB
• Created: 19 seconds ago

4. 빌드 검증

4.1 JAR 파일 확인

ls -lh event-service/build/libs/

출력:

-rw-r--r-- 1 KTDS 197121 94M 10월 28 14:35 event-service.jar

4.2 Docker 이미지 확인

docker images | grep event-service

출력:

event-service    latest    bbeecf2ccaf2    19 seconds ago    1.08GB

5. Dockerfile 구조

파일 위치: deployment/container/Dockerfile-backend

빌드 스테이지 (Build Stage)

• Base Image: openjdk:23-oraclelinux8
• 작업: JAR 파일 복사

실행 스테이지 (Run Stage)

• Base Image: openjdk:23-slim
• 사용자: k8s (non-root user)
• 작업 디렉토리: /home/k8s
• 진입점: java ${JAVA_OPTS} -jar app.jar

6. 컨테이너 실행 가이드

6.1 기본 실행

docker run -d \
  --name event-service \
  -p 8082:8082 \
  -e SPRING_PROFILES_ACTIVE=dev \
  -e SERVER_PORT=8082 \
  event-service:latest

6.2 환경변수 설정

Event Service 실행을 위한 주요 환경변수:

필수 환경변수

• SERVER_PORT: 서버 포트 (기본값: 8082)
• DB_HOST: PostgreSQL 호스트
• DB_PORT: PostgreSQL 포트 (기본값: 5432)
• DB_NAME: 데이터베이스 이름
• DB_USERNAME: 데이터베이스 사용자명
• DB_PASSWORD: 데이터베이스 비밀번호
• REDIS_HOST: Redis 호스트
• REDIS_PORT: Redis 포트 (기본값: 6379)
• REDIS_PASSWORD: Redis 비밀번호
• KAFKA_BOOTSTRAP_SERVERS: Kafka 브로커 주소
• JWT_SECRET: JWT 서명 키 (최소 32자)

선택 환경변수

• DISTRIBUTION_SERVICE_URL: Distribution Service URL
• JAVA_OPTS: JVM 옵션

6.3 Docker Compose 실행 예시

services:
  event-service:
    image: event-service:latest
    container_name: event-service
    ports:
      - "8082:8082"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - SERVER_PORT=8082
      - DB_HOST=your-db-host
      - DB_PORT=5432
      - DB_NAME=event_db
      - DB_USERNAME=event_user
      - DB_PASSWORD=your-password
      - REDIS_HOST=your-redis-host
      - REDIS_PORT=6379
      - REDIS_PASSWORD=your-redis-password
      - KAFKA_BOOTSTRAP_SERVERS=your-kafka:9092
      - JWT_SECRET=your-jwt-secret-key-minimum-32-characters
      - DISTRIBUTION_SERVICE_URL=http://distribution-service:8086
    restart: unless-stopped

7. 헬스체크

7.1 Spring Boot Actuator

curl http://localhost:8082/actuator/health

예상 응답:

{
  "status": "UP",
  "components": {
    "ping": {
      "status": "UP"
    },
    "db": {
      "status": "UP"
    },
    "redis": {
      "status": "UP"
    }
  }
}

7.2 Swagger UI

http://localhost:8082/swagger-ui/index.html

8. 빌드 결과 요약

서비스 정보

• 서비스명: event-service
• 포트: 8082
• JAR 크기: 94MB
• 이미지 크기: 1.08GB
• Base Image: openjdk:23-slim
• Platform: linux/amd64

빌드 통계

• Common 컴파일: 6초
• Event Service 컴파일: 6초
• JAR 빌드: 5초
• Docker 이미지 빌드: 약 120초

주요 의존성

• Spring Boot Actuator
• Spring Kafka
• Spring Data Redis
• Spring Cloud OpenFeign
• PostgreSQL Driver
• Jackson

9. 트러블슈팅

9.1 컴파일 오류 해결

증상: userId/storeId 타입 불일치 오류

해결:

• UserPrincipal의 userId, storeId를 UUID로 변경
• JwtTokenProvider의 파싱 로직을 UUID.fromString()으로 수정

9.2 Gradle Clean 오류

증상: Unable to delete directory 'common\build'

해결: clean 없이 빌드 수행

./gradlew event-service:bootJar

9.3 Docker 빌드 컨텍스트 오류

증상: JAR 파일을 찾을 수 없음

해결:

• JAR 파일이 실제로 빌드되었는지 확인
• 빌드 아규먼트 경로가 올바른지 확인

10. 다음 단계

1. 컨테이너 테스트: 로컬 환경에서 컨테이너 실행 및 API 테스트
2. 환경변수 설정: 운영 환경에 맞는 환경변수 구성
3. 통합 테스트: 다른 마이크로서비스들과의 통합 테스트
4. 이미지 레지스트리 푸시: Docker Hub 또는 사설 레지스트리에 이미지 업로드
5. Kubernetes 배포: K8s 클러스터에 배포

11. 참고사항

• 개발 환경 인증: DevAuthenticationFilter가 자동으로 테스트용 UserPrincipal 생성
• 프로덕션 배포: DevAuthenticationFilter 비활성화 및 실제 JWT 인증 필터 활성화 필요
• 보안: JWT_SECRET은 안전하게 관리하고 최소 32자 이상 사용
• 성능: JAVA_OPTS를 통해 JVM 메모리 설정 최적화 권장