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. 다음 단계

### 빌드 수행 이력

#### 최신 빌드 (2025-10-28)

**1단계: JAR 빌드**
```bash
./gradlew content-service:clean content-service:bootJar
```

빌드 결과:
```
BUILD SUCCESSFUL in 8s
9 actionable tasks: 6 executed, 3 up-to-date
```

**2단계: Docker 이미지 빌드**
```bash
docker build \
  --platform linux/amd64 \
  --build-arg BUILD_LIB_DIR="content-service/build/libs" \
  --build-arg ARTIFACTORY_FILE="content-service.jar" \
  -f deployment/container/Dockerfile-backend \
  -t content-service:latest .
```

빌드 결과:
- ✅ Build stage 완료 (openjdk:23-oraclelinux8)
- ✅ Run stage 완료 (openjdk:23-slim)
- ✅ 이미지 생성 완료

**3단계: 이미지 확인**
```bash
docker images | grep content-service
```

확인 결과:
```
content-service    latest    ff73258c94cc    15 seconds ago    393MB
```

### 빌드 정보
- **서비스명**: content-service
- **JAR 파일**: content-service.jar
- **Docker 이미지**: content-service:latest
- **이미지 ID**: ff73258c94cc
- **이미지 크기**: 393MB
- **노출 포트**: 8084

### 빌드 일시
- **최신 빌드**: 2025-10-28
- **이전 빌드**: 2025-10-27

### 환경
- **Base Image**: openjdk:23-slim
- **Platform**: linux/amd64
- **User**: k8s (non-root)
- **Java Version**: 23