kt-event-marketing/deployment/container/run-container-guide.md

# 백엔드 컨테이너 실행 가이드

작성일: 2025-10-27
작성자: DevOps Engineer

## 1. 개요

KT 이벤트 마케팅 플랫폼의 백엔드 마이크로서비스들을 Docker 컨테이너로 실행하는 방법을 안내합니다.

## 2. 실행 환경 정보

| 항목 | 값 |
|------|-----|
| **Azure Container Registry** | acrdigitalgarage01 |
| **VM IP** | 4.218.10.89 |
| **VM User ID** | azureuser |
| **SSH Private Key** | ~/home/bastion-dg0502 |
| **시스템명** | kt-event-marketing |

## 3. 빌드 가능한 서비스 목록

| 서비스명 | 포트 | 상태 | 비고 |
|---------|------|------|------|
| analytics-service | 8086 | ✅ 빌드 완료 | 컨테이너 이미지 생성됨 |
| participation-service | 8084 | ⏸️ JAR 빌드 완료 | 컨테이너 이미지 생성 필요 |
| event-service | 8080 | ⏸️ JAR 빌드 완료 | 컨테이너 이미지 생성 필요 |
| content-service | 8083 | ⏸️ JAR 빌드 완료 | 컨테이너 이미지 생성 필요 |

## 4. VM 접속 방법

### 4.1 터미널 실행

- **Linux/Mac**: 기본 터미널 실행
- **Windows**: Windows Terminal 실행

### 4.2 SSH Private Key 권한 설정 (최초 1회)

```bash
chmod 400 ~/home/bastion-dg0502
```

### 4.3 VM 접속

```bash
ssh -i ~/home/bastion-dg0502 azureuser@4.218.10.89
```

## 5. 작업 환경 준비

### 5.1 Workspace 디렉토리 생성

```bash
mkdir -p ~/home/workspace
cd ~/home/workspace
```

### 5.2 Git Repository 클론

```bash
git clone https://github.com/ktds-dg0501/kt-event-marketing.git
```

**참고**: 실제 Git Repository 주소로 변경해 주세요.

### 5.3 프로젝트 디렉토리 이동

```bash
cd kt-event-marketing
```

## 6. 애플리케이션 빌드 및 컨테이너 이미지 생성

### 6.1 gradlew 실행 권한 설정 (최초 1회)

VM 환경에서는 gradlew 파일에 실행 권한이 없을 수 있습니다:

```bash
chmod +x gradlew
```

### 6.2 JAR 파일 빌드

```bash
./gradlew :analytics-service:bootJar :content-service:bootJar :event-service:bootJar :participation-service:bootJar --no-daemon
```

**권한 오류 발생 시**:
```bash
bash gradlew :analytics-service:bootJar :content-service:bootJar :event-service:bootJar :participation-service:bootJar --no-daemon
```

### 6.3 Docker 이미지 생성

상세한 가이드는 `deployment/container/build-image.md` 파일을 참조하세요.

## 7. Azure Container Registry (ACR) 작업

### 7.1 ACR 인증 정보 확인

```bash
az acr credential show --name acrdigitalgarage01
```

**출력 예시**:
```json
{
  "passwords": [
    {
      "name": "password",
      "value": "<PASSWORD>"
    },
    {
      "name": "password2",
      "value": "<PASSWORD2>"
    }
  ],
  "username": "acrdigitalgarage01"
}
```

### 7.2 ACR 로그인

위에서 확인한 `username`과 `passwords[0].value`를 사용하여 로그인합니다:

```bash
docker login acrdigitalgarage01.azurecr.io -u acrdigitalgarage01 -p <PASSWORD>
```

## 8. 컨테이너 이미지 푸시

### 8.1 analytics-service

```bash
# 이미지 태그
docker tag analytics-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest

# ACR로 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
```

### 8.2 participation-service

```bash
# 이미지 태그
docker tag participation-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest

# ACR로 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest
```

### 8.3 event-service

```bash
# 이미지 태그
docker tag event-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest

# ACR로 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
```

### 8.4 content-service

```bash
# 이미지 태그
docker tag content-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/content-service:latest

# ACR로 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/content-service:latest
```

## 9. 컨테이너 실행

### 9.1 analytics-service

```bash
SERVER_PORT=8086

docker run -d --name analytics-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e DB_KIND=postgresql \
-e DB_HOST=4.230.49.9 \
-e DB_PORT=5432 \
-e DB_NAME=analyticdb \
-e DB_USERNAME=eventuser \
-e DB_PASSWORD=Hi5Jessica! \
-e DDL_AUTO=update \
-e SHOW_SQL=true \
-e REDIS_HOST=20.214.210.71 \
-e REDIS_PORT=6379 \
-e REDIS_PASSWORD=Hi5Jessica! \
-e REDIS_DATABASE=5 \
-e KAFKA_ENABLED=true \
-e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
-e KAFKA_CONSUMER_GROUP_ID=analytics-service-consumers \
-e SAMPLE_DATA_ENABLED=true \
-e SERVER_PORT=8086 \
-e JWT_SECRET=dev-jwt-secret-key-for-development-only-kt-event-marketing \
-e JWT_ACCESS_TOKEN_VALIDITY=1800 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400 \
-e CORS_ALLOWED_ORIGINS="http://localhost:*,http://4.218.10.89:3000" \
-e LOG_FILE=logs/analytics-service.log \
-e LOG_LEVEL_APP=DEBUG \
-e LOG_LEVEL_WEB=INFO \
-e LOG_LEVEL_SQL=DEBUG \
-e LOG_LEVEL_SQL_TYPE=TRACE \
acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
```

### 9.2 participation-service

```bash
SERVER_PORT=8084

docker run -d --name participation-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e DB_HOST=4.230.72.147 \
-e DB_NAME=participationdb \
-e DB_PASSWORD=Hi5Jessica! \
-e DB_PORT=5432 \
-e DB_USERNAME=eventuser \
-e DDL_AUTO=validate \
-e JWT_EXPIRATION=86400000 \
-e JWT_SECRET=kt-event-marketing-secret-key-for-development-only-change-in-production \
-e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
-e LOG_FILE=logs/participation-service.log \
-e LOG_LEVEL=INFO \
-e REDIS_HOST=20.214.210.71 \
-e REDIS_PASSWORD=Hi5Jessica! \
-e REDIS_PORT=6379 \
-e SERVER_PORT=8084 \
-e SHOW_SQL=true \
acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest
```

### 9.3 event-service

**참고**: event-service는 `.run.xml` 파일이 없어 환경변수 설정이 필요합니다.
아래는 `application.yml`을 기반으로 추정한 환경변수입니다.

```bash
SERVER_PORT=8080

docker run -d --name event-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e DB_HOST=<DB_HOST> \
-e DB_PORT=5432 \
-e DB_NAME=eventdb \
-e DB_USERNAME=eventuser \
-e DB_PASSWORD=<DB_PASSWORD> \
-e DDL_AUTO=update \
-e REDIS_HOST=20.214.210.71 \
-e REDIS_PORT=6379 \
-e REDIS_PASSWORD=Hi5Jessica! \
-e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
-e SERVER_PORT=8080 \
-e LOG_LEVEL=DEBUG \
-e SQL_LOG_LEVEL=DEBUG \
acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
```

⚠️ **필수**: `<DB_HOST>`와 `<DB_PASSWORD>`를 실제 값으로 변경해 주세요.

### 9.4 content-service

**참고**: content-service는 `.run.xml` 파일이 없어 환경변수 설정이 필요합니다.
아래는 `application.yml`을 기반으로 추정한 환경변수입니다.

```bash
SERVER_PORT=8083

docker run -d --name content-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e REDIS_HOST=20.214.210.71 \
-e REDIS_PORT=6379 \
-e REDIS_PASSWORD=Hi5Jessica! \
-e SERVER_PORT=8083 \
-e JWT_SECRET=dev-jwt-secret-key \
-e JWT_ACCESS_TOKEN_VALIDITY=3600000 \
-e JWT_REFRESH_TOKEN_VALIDITY=604800000 \
-e AZURE_STORAGE_CONNECTION_STRING=<AZURE_STORAGE_CONNECTION_STRING> \
-e AZURE_CONTAINER_NAME=event-images \
-e LOG_LEVEL_APP=DEBUG \
-e LOG_LEVEL_ROOT=INFO \
-e LOG_FILE=logs/content-service.log \
acrdigitalgarage01.azurecr.io/kt-event-marketing/content-service:latest
```

⚠️ **필수**: `<AZURE_STORAGE_CONNECTION_STRING>`을 실제 값으로 변경해 주세요.

## 10. 실행 확인

### 10.1 컨테이너 실행 상태 확인

```bash
# 전체 컨테이너 확인
docker ps

# 특정 서비스 확인
docker ps | grep analytics-service
docker ps | grep participation-service
docker ps | grep event-service
docker ps | grep content-service
```

### 10.2 컨테이너 로그 확인

```bash
# 실시간 로그 확인
docker logs -f analytics-service
docker logs -f participation-service
docker logs -f event-service
docker logs -f content-service

# 최근 100줄 로그 확인
docker logs --tail 100 analytics-service
```

### 10.3 헬스체크

```bash
# analytics-service
curl http://4.218.10.89:8086/actuator/health

# participation-service
curl http://4.218.10.89:8084/actuator/health

# event-service
curl http://4.218.10.89:8080/actuator/health

# content-service
curl http://4.218.10.89:8083/actuator/health
```

## 11. 재배포 방법

### 11.1 로컬에서 수정된 소스 푸시

로컬 개발 환경에서 코드 수정 후:

```bash
git add .
git commit -m "변경 사항"
git push
```

### 11.2 VM 접속

```bash
ssh -i ~/home/bastion-dg0502 azureuser@4.218.10.89
```

### 11.3 디렉토리 이동 및 소스 내려받기

```bash
cd ~/home/workspace/kt-event-marketing
git pull
```

### 11.4 컨테이너 이미지 재생성

**JAR 파일 빌드**:
```bash
./gradlew :analytics-service:bootJar :content-service:bootJar :event-service:bootJar :participation-service:bootJar --no-daemon
```

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

상세한 가이드는 `deployment/container/build-image.md` 파일을 참조하세요.

### 11.5 컨테이너 이미지 푸시

**analytics-service 예시**:
```bash
docker tag analytics-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
```

### 11.6 컨테이너 중지

```bash
docker stop analytics-service
docker stop participation-service
docker stop event-service
docker stop content-service
```

### 11.7 컨테이너 이미지 삭제 (선택사항)

```bash
docker rmi acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
docker rmi acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest
docker rmi acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
docker rmi acrdigitalgarage01.azurecr.io/kt-event-marketing/content-service:latest
```

### 11.8 컨테이너 재실행

위의 [9. 컨테이너 실행](#9-컨테이너-실행) 섹션의 명령어를 다시 실행합니다.

## 12. 일괄 실행 스크립트

### 12.1 전체 서비스 중지

```bash
docker stop analytics-service participation-service event-service content-service
```

### 12.2 전체 서비스 시작 (Bash 스크립트)

**실행 전 주의사항**:
- event-service와 content-service의 환경변수 값을 실제 값으로 변경해야 합니다.

```bash
#!/bin/bash

# analytics-service 실행
SERVER_PORT=8086
docker run -d --name analytics-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e DB_KIND=postgresql \
-e DB_HOST=4.230.49.9 \
-e DB_PORT=5432 \
-e DB_NAME=analyticdb \
-e DB_USERNAME=eventuser \
-e DB_PASSWORD=Hi5Jessica! \
-e DDL_AUTO=update \
-e SHOW_SQL=true \
-e REDIS_HOST=20.214.210.71 \
-e REDIS_PORT=6379 \
-e REDIS_PASSWORD=Hi5Jessica! \
-e REDIS_DATABASE=5 \
-e KAFKA_ENABLED=true \
-e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
-e KAFKA_CONSUMER_GROUP_ID=analytics-service-consumers \
-e SAMPLE_DATA_ENABLED=true \
-e SERVER_PORT=8086 \
-e JWT_SECRET=dev-jwt-secret-key-for-development-only-kt-event-marketing \
-e JWT_ACCESS_TOKEN_VALIDITY=1800 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400 \
-e CORS_ALLOWED_ORIGINS="http://localhost:*,http://4.218.10.89:3000" \
-e LOG_FILE=logs/analytics-service.log \
-e LOG_LEVEL_APP=DEBUG \
-e LOG_LEVEL_WEB=INFO \
-e LOG_LEVEL_SQL=DEBUG \
-e LOG_LEVEL_SQL_TYPE=TRACE \
acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest

echo "✅ analytics-service started on port 8086"

# participation-service 실행
SERVER_PORT=8084
docker run -d --name participation-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e DB_HOST=4.230.72.147 \
-e DB_NAME=participationdb \
-e DB_PASSWORD=Hi5Jessica! \
-e DB_PORT=5432 \
-e DB_USERNAME=eventuser \
-e DDL_AUTO=validate \
-e JWT_EXPIRATION=86400000 \
-e JWT_SECRET=kt-event-marketing-secret-key-for-development-only-change-in-production \
-e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
-e LOG_FILE=logs/participation-service.log \
-e LOG_LEVEL=INFO \
-e REDIS_HOST=20.214.210.71 \
-e REDIS_PASSWORD=Hi5Jessica! \
-e REDIS_PORT=6379 \
-e SERVER_PORT=8084 \
-e SHOW_SQL=true \
acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest

echo "✅ participation-service started on port 8084"

# 실행 확인
echo ""
echo "🔍 Running containers:"
docker ps | grep -E "analytics-service|participation-service"
```

## 13. 문제 해결

### 13.1 컨테이너가 즉시 종료되는 경우

**로그 확인**:
```bash
docker logs <container-name>
```

**일반적인 원인**:
- 환경변수 누락 또는 잘못된 값
- 데이터베이스/Redis/Kafka 연결 실패
- 포트 충돌

### 13.2 ACR 로그인 실패

**인증 정보 재확인**:
```bash
az acr credential show --name acrdigitalgarage01
```

**다시 로그인**:
```bash
docker logout acrdigitalgarage01.azurecr.io
docker login acrdigitalgarage01.azurecr.io -u <username> -p <password>
```

### 13.3 포트 충돌

**포트 사용 확인**:
```bash
netstat -tuln | grep <PORT>
```

**다른 포트로 변경**:
```bash
SERVER_PORT=<NEW_PORT>
docker run -d -p ${SERVER_PORT}:${SERVER_PORT} ...
```

## 14. 참고 자료

- 컨테이너 이미지 빌드 가이드: `deployment/container/build-image.md`
- Docker 공식 문서: https://docs.docker.com/
- Azure Container Registry 문서: https://docs.microsoft.com/azure/container-registry/