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를 기대하므로 일관성 유지

```java
// 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의 타입 변경에 따른 파싱 로직 수정

```java
// 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 파일명 명시

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

## 3. 빌드 명령어

### 3.1 Common 모듈 컴파일
```bash
./gradlew common:compileJava
```

**결과**: BUILD SUCCESSFUL in 6s

### 3.2 Event Service 컴파일
```bash
./gradlew event-service:compileJava
```

**결과**: BUILD SUCCESSFUL in 6s

### 3.3 Event Service JAR 빌드
```bash
./gradlew event-service:bootJar
```

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

### 3.4 Docker 이미지 빌드
```bash
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 파일 확인
```bash
ls -lh event-service/build/libs/
```

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

### 4.2 Docker 이미지 확인
```bash
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 기본 실행
```bash
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 실행 예시
```yaml
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
```bash
curl http://localhost:8082/actuator/health
```

**예상 응답**:
```json
{
  "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 없이 빌드 수행
```bash
./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 메모리 설정 최적화 권장