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회)

chmod 400 ~/home/bastion-dg0502

4.3 VM 접속

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

5. 작업 환경 준비

5.1 Workspace 디렉토리 생성

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

5.2 Git Repository 클론

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

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

5.3 프로젝트 디렉토리 이동

cd kt-event-marketing

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

deployment/container/build-image.md 파일의 가이드를 참조하여 다음 작업을 수행하세요:

1. JAR 파일 빌드
2. Docker 이미지 생성

7. Azure Container Registry (ACR) 작업

7.1 ACR 인증 정보 확인

az acr credential show --name acrdigitalgarage01

출력 예시:

{
  "passwords": [
    {
      "name": "password",
      "value": "<PASSWORD>"
    },
    {
      "name": "password2",
      "value": "<PASSWORD2>"
    }
  ],
  "username": "acrdigitalgarage01"
}

7.2 ACR 로그인

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

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

8. 컨테이너 이미지 푸시

8.1 analytics-service

# 이미지 태그
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

# 이미지 태그
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

# 이미지 태그
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

# 이미지 태그
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

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

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을 기반으로 추정한 환경변수입니다.

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을 기반으로 추정한 환경변수입니다.

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 컨테이너 실행 상태 확인

# 전체 컨테이너 확인
docker ps

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

10.2 컨테이너 로그 확인

# 실시간 로그 확인
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 헬스체크

# 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 로컬에서 수정된 소스 푸시

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

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

11.2 VM 접속

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

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

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

11.4 컨테이너 이미지 재생성

deployment/container/build-image.md 파일의 가이드대로 다시 빌드

11.5 컨테이너 이미지 푸시

analytics-service 예시:

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 컨테이너 중지

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

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

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. 컨테이너 실행 섹션의 명령어를 다시 실행합니다.

12. 일괄 실행 스크립트

12.1 전체 서비스 중지

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

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

실행 전 주의사항:

• event-service와 content-service의 환경변수 값을 실제 값으로 변경해야 합니다.

#!/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 컨테이너가 즉시 종료되는 경우

로그 확인:

docker logs <container-name>

일반적인 원인:

• 환경변수 누락 또는 잘못된 값
• 데이터베이스/Redis/Kafka 연결 실패
• 포트 충돌

13.2 ACR 로그인 실패

인증 정보 재확인:

az acr credential show --name acrdigitalgarage01

다시 로그인:

docker logout acrdigitalgarage01.azurecr.io
docker login acrdigitalgarage01.azurecr.io -u <username> -p <password>

13.3 포트 충돌

포트 사용 확인:

netstat -tuln | grep <PORT>

다른 포트로 변경:

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/