From d223510198fc0a86bd668a30143fb94b8e8c820e Mon Sep 17 00:00:00 2001
From: Hyowon Yang <yhwooni@gmail.com>
Date: Mon, 27 Oct 2025 16:25:26 +0900
Subject: [PATCH] =?UTF-8?q?=EC=BB=A8=ED=85=8C=EC=9D=B4=EB=84=88=EB=B0=B0?=
 =?UTF-8?q?=ED=8F=AC=EC=84=A4=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../deploy-actions-cicd-guide-back.md         |  10 +
 .../deploy-actions-cicd-guide-front.md        |  11 +
 .claude/commands/deploy-build-image-back.md   |   2 +
 .claude/commands/deploy-build-image-front.md  |   2 +
 .claude/commands/deploy-help.md               |  55 ++
 .../deploy-jenkins-cicd-guide-back.md         |  10 +
 .../deploy-jenkins-cicd-guide-front.md        |  11 +
 .claude/commands/deploy-k8s-guide-back.md     |  12 +
 .claude/commands/deploy-k8s-guide-front.md    |  14 +
 .../deploy-run-container-guide-back.md        |  11 +
 .../deploy-run-container-guide-front.md       |  12 +
 deployment/container/Dockerfile-backend       |  25 +
 deployment/container/build-image.md           | 365 +++++++++++++
 deployment/container/run-container-guide.md   | 493 ++++++++++++++++++
 14 files changed, 1033 insertions(+)
 create mode 100644 .claude/commands/deploy-actions-cicd-guide-back.md
 create mode 100644 .claude/commands/deploy-actions-cicd-guide-front.md
 create mode 100644 .claude/commands/deploy-build-image-back.md
 create mode 100644 .claude/commands/deploy-build-image-front.md
 create mode 100644 .claude/commands/deploy-help.md
 create mode 100644 .claude/commands/deploy-jenkins-cicd-guide-back.md
 create mode 100644 .claude/commands/deploy-jenkins-cicd-guide-front.md
 create mode 100644 .claude/commands/deploy-k8s-guide-back.md
 create mode 100644 .claude/commands/deploy-k8s-guide-front.md
 create mode 100644 .claude/commands/deploy-run-container-guide-back.md
 create mode 100644 .claude/commands/deploy-run-container-guide-front.md
 create mode 100644 deployment/container/Dockerfile-backend
 create mode 100644 deployment/container/build-image.md
 create mode 100644 deployment/container/run-container-guide.md

diff --git a/.claude/commands/deploy-actions-cicd-guide-back.md b/.claude/commands/deploy-actions-cicd-guide-back.md
new file mode 100644
index 0000000..794d662
--- /dev/null
+++ b/.claude/commands/deploy-actions-cicd-guide-back.md
@@ -0,0 +1,10 @@
+@cicd
+'백엔드GitHubActions파이프라인작성가이드'에 따라 GitHub Actions를 이용한 CI/CD 가이드를 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- ACR_NAME: acrdigitalgarage01
+- RESOURCE_GROUP: rg-digitalgarage-01
+- AKS_CLUSTER: aks-digitalgarage-01
+- NAMESPACE: phonebill-dg0500
\ No newline at end of file
diff --git a/.claude/commands/deploy-actions-cicd-guide-front.md b/.claude/commands/deploy-actions-cicd-guide-front.md
new file mode 100644
index 0000000..184aaa0
--- /dev/null
+++ b/.claude/commands/deploy-actions-cicd-guide-front.md
@@ -0,0 +1,11 @@
+@cicd
+'프론트엔드GitHubActions파이프라인작성가이드'에 따라 GitHub Actions를 이용한 CI/CD 가이드를 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- SYSTEM_NAME: phonebill
+- ACR_NAME: acrdigitalgarage01
+- RESOURCE_GROUP: rg-digitalgarage-01
+- AKS_CLUSTER: aks-digitalgarage-01
+- NAMESPACE: phonebill-dg0500
\ No newline at end of file
diff --git a/.claude/commands/deploy-build-image-back.md b/.claude/commands/deploy-build-image-back.md
new file mode 100644
index 0000000..9893547
--- /dev/null
+++ b/.claude/commands/deploy-build-image-back.md
@@ -0,0 +1,2 @@
+@cicd
+'백엔드컨테이너이미지작성가이드'에 따라 컨테이너 이미지를 작성해 주세요.
\ No newline at end of file
diff --git a/.claude/commands/deploy-build-image-front.md b/.claude/commands/deploy-build-image-front.md
new file mode 100644
index 0000000..4c81118
--- /dev/null
+++ b/.claude/commands/deploy-build-image-front.md
@@ -0,0 +1,2 @@
+@cicd
+'프론트엔드컨테이너이미지작성가이드'에 따라 컨테이너 이미지를 작성해 주세요.
\ No newline at end of file
diff --git a/.claude/commands/deploy-help.md b/.claude/commands/deploy-help.md
new file mode 100644
index 0000000..cc52548
--- /dev/null
+++ b/.claude/commands/deploy-help.md
@@ -0,0 +1,55 @@
+배포 작업 순서
+
+## 1단계: 컨테이너 이미지 작성
+### 백엔드
+/deploy-build-image-back
+- 백엔드컨테이너이미지작성가이드에 따라 컨테이너 이미지를 작성합니다
+
+### 프론트엔드
+/deploy-build-image-front
+- 프론트엔드컨테이너이미지작성가이드에 따라 컨테이너 이미지를 작성합니다
+
+## 2단계: 컨테이너 실행 가이드 작성
+### 백엔드
+/deploy-run-container-guide-back
+- 백엔드컨테이너실행방법가이드에 따라 실행 가이드를 작성합니다
+- [실행정보] 섹션에 ACR명, VM 정보를 제공해야 합니다
+
+### 프론트엔드
+/deploy-run-container-guide-front
+- 프론트엔드컨테이너실행방법가이드에 따라 실행 가이드를 작성합니다
+- [실행정보] 섹션에 시스템명, ACR명, VM 정보를 제공해야 합니다
+
+## 3단계: 쿠버네티스 배포 가이드 작성
+### 백엔드
+/deploy-k8s-guide-back
+- 백엔드배포가이드에 따라 K8s 배포 가이드를 작성합니다
+- [실행정보] 섹션에 ACR명, k8s명, 네임스페이스, 리소스 정보를 제공해야 합니다
+
+### 프론트엔드
+/deploy-k8s-guide-front
+- 프론트엔드배포가이드에 따라 K8s 배포 가이드를 작성합니다
+- [실행정보] 섹션에 시스템명, ACR명, k8s명, 네임스페이스, 리소스, Gateway Host 정보를 제공해야 합니다
+
+## 4단계: CI/CD 파이프라인 작성
+### Jenkins CI/CD
+#### 백엔드
+/deploy-jenkins-cicd-guide-back
+- 백엔드Jenkins파이프라인작성가이드에 따라 작성합니다
+- [실행정보] 섹션에 ACR_NAME, RESOURCE_GROUP, AKS_CLUSTER, NAMESPACE 정보를 제공해야 합니다
+
+#### 프론트엔드
+/deploy-jenkins-cicd-guide-front
+- 프론트엔드Jenkins파이프라인작성가이드에 따라 작성합니다
+- [실행정보] 섹션에 SYSTEM_NAME, ACR_NAME, RESOURCE_GROUP, AKS_CLUSTER, NAMESPACE 정보를 제공해야 합니다
+
+### GitHub Actions CI/CD
+#### 백엔드
+/deploy-actions-cicd-guide-back
+- 백엔드GitHubActions파이프라인작성가이드에 따라 작성합니다
+- [실행정보] 섹션에 ACR_NAME, RESOURCE_GROUP, AKS_CLUSTER, NAMESPACE 정보를 제공해야 합니다
+
+#### 프론트엔드
+/deploy-actions-cicd-guide-front
+- 프론트엔드GitHubActions파이프라인작성가이드에 따라 작성합니다
+- [실행정보] 섹션에 SYSTEM_NAME, ACR_NAME, RESOURCE_GROUP, AKS_CLUSTER, NAMESPACE 정보를 제공해야 합니다
\ No newline at end of file
diff --git a/.claude/commands/deploy-jenkins-cicd-guide-back.md b/.claude/commands/deploy-jenkins-cicd-guide-back.md
new file mode 100644
index 0000000..d14ddc4
--- /dev/null
+++ b/.claude/commands/deploy-jenkins-cicd-guide-back.md
@@ -0,0 +1,10 @@
+@cicd
+'백엔드Jenkins파이프라인작성가이드'에 따라 Jenkins를 이용한 CI/CD 가이드를 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- ACR_NAME: acrdigitalgarage01
+- RESOURCE_GROUP: rg-digitalgarage-01
+- AKS_CLUSTER: aks-digitalgarage-01
+- NAMESPACE: phonebill-dg0500
\ No newline at end of file
diff --git a/.claude/commands/deploy-jenkins-cicd-guide-front.md b/.claude/commands/deploy-jenkins-cicd-guide-front.md
new file mode 100644
index 0000000..4c7dc11
--- /dev/null
+++ b/.claude/commands/deploy-jenkins-cicd-guide-front.md
@@ -0,0 +1,11 @@
+@cicd
+'프론트엔드Jenkins파이프라인작성가이드'에 따라 Jenkins를 이용한 CI/CD 가이드를 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- SYSTEM_NAME: phonebill
+- ACR_NAME: acrdigitalgarage01
+- RESOURCE_GROUP: rg-digitalgarage-01
+- AKS_CLUSTER: aks-digitalgarage-01
+- NAMESPACE: phonebill-dg0500
\ No newline at end of file
diff --git a/.claude/commands/deploy-k8s-guide-back.md b/.claude/commands/deploy-k8s-guide-back.md
new file mode 100644
index 0000000..e6f23bb
--- /dev/null
+++ b/.claude/commands/deploy-k8s-guide-back.md
@@ -0,0 +1,12 @@
+@cicd
+'백엔드배포가이드'에 따라 백엔드 서비스 배포 방법을 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- ACR명: acrdigitalgarage01
+- k8s명: aks-digitalgarage-01
+- 네임스페이스: tripgen
+- 파드수: 2
+- 리소스(CPU): 256m/1024m
+- 리소스(메모리): 256Mi/1024Mi
\ No newline at end of file
diff --git a/.claude/commands/deploy-k8s-guide-front.md b/.claude/commands/deploy-k8s-guide-front.md
new file mode 100644
index 0000000..8773bd4
--- /dev/null
+++ b/.claude/commands/deploy-k8s-guide-front.md
@@ -0,0 +1,14 @@
+@cicd
+'프론트엔드배포가이드'에 따라 프론트엔드 서비스 배포 방법을 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- 시스템명: tripgen
+- ACR명: acrdigitalgarage01
+- k8s명: aks-digitalgarage-01
+- 네임스페이스: tripgen
+- 파드수: 2
+- 리소스(CPU): 256m/1024m
+- 리소스(메모리): 256Mi/1024Mi
+- Gateway Host: http://tripgen-api.20.214.196.128.nip.io
\ No newline at end of file
diff --git a/.claude/commands/deploy-run-container-guide-back.md b/.claude/commands/deploy-run-container-guide-back.md
new file mode 100644
index 0000000..e18d86c
--- /dev/null
+++ b/.claude/commands/deploy-run-container-guide-back.md
@@ -0,0 +1,11 @@
+@cicd
+'백엔드컨테이너실행방법가이드'에 따라 컨테이너 실행 가이드를 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- ACR명: acrdigitalgarage01
+- VM
+  - KEY파일: ~/home/bastion-dg0502
+  - USERID: azureuser
+  - IP: 4.218.10.89
\ No newline at end of file
diff --git a/.claude/commands/deploy-run-container-guide-front.md b/.claude/commands/deploy-run-container-guide-front.md
new file mode 100644
index 0000000..faca872
--- /dev/null
+++ b/.claude/commands/deploy-run-container-guide-front.md
@@ -0,0 +1,12 @@
+@cicd
+'프론트엔드컨테이너실행방법가이드'에 따라 컨테이너 실행 가이드를 작성해 주세요.
+프롬프트에 '[실행정보]'항목이 없으면 수행을 중단하고 안내 메시지를 표시해 주세요.
+{안내메시지}
+'[실행정보]'섹션 하위에 아래 예와 같이 필요한 정보를 제시해 주세요.
+[실행정보]
+- 시스템명: tripgen
+- ACR명: acrdigitalgarage01
+- VM
+  - KEY파일: ~/home/bastion-dg0500
+  - USERID: azureuser
+  - IP: 4.230.5.6
\ No newline at end of file
diff --git a/deployment/container/Dockerfile-backend b/deployment/container/Dockerfile-backend
new file mode 100644
index 0000000..37da239
--- /dev/null
+++ b/deployment/container/Dockerfile-backend
@@ -0,0 +1,25 @@
+# Build stage
+FROM openjdk:23-oraclelinux8 AS builder
+ARG BUILD_LIB_DIR
+ARG ARTIFACTORY_FILE
+COPY ${BUILD_LIB_DIR}/${ARTIFACTORY_FILE} app.jar
+
+# Run stage
+FROM openjdk:23-slim
+ENV USERNAME=k8s
+ENV ARTIFACTORY_HOME=/home/${USERNAME}
+ENV JAVA_OPTS=""
+
+# Add a non-root user
+RUN adduser --system --group ${USERNAME} && \
+    mkdir -p ${ARTIFACTORY_HOME} && \
+    chown ${USERNAME}:${USERNAME} ${ARTIFACTORY_HOME}
+
+WORKDIR ${ARTIFACTORY_HOME}
+COPY --from=builder app.jar app.jar
+RUN chown ${USERNAME}:${USERNAME} app.jar
+
+USER ${USERNAME}
+
+ENTRYPOINT [ "sh", "-c" ]
+CMD ["java ${JAVA_OPTS} -jar app.jar"]
diff --git a/deployment/container/build-image.md b/deployment/container/build-image.md
new file mode 100644
index 0000000..d861c9e
--- /dev/null
+++ b/deployment/container/build-image.md
@@ -0,0 +1,365 @@
+# 백엔드 컨테이너 이미지 작성 결과
+
+작성일: 2025-10-27
+작성자: DevOps Engineer
+
+## 1. 개요
+
+KT 이벤트 마케팅 플랫폼의 백엔드 마이크로서비스들을 컨테이너 이미지로 빌드하는 과정을 문서화합니다.
+
+## 2. 서비스 현황
+
+### 2.1 전체 서비스 목록 (settings.gradle 기준)
+
+```
+rootProject.name = 'kt-event-marketing'
+
+// Common module
+include 'common'
+
+// Microservices
+include 'user-service'
+include 'event-service'
+include 'ai-service'
+include 'content-service'
+include 'distribution-service'
+include 'participation-service'
+include 'analytics-service'
+```
+
+### 2.2 구현 상태
+
+| 서비스명 | 구현 상태 | JAR 빌드 | 컨테이너 이미지 | 비고 |
+|---------|----------|---------|---------------|------|
+| common | ✅ | N/A | N/A | 공통 라이브러리 |
+| user-service | ⚠️ | ❌ | ⏸️ | 컴파일 에러 (타입 불일치) |
+| event-service | ✅ | ✅ | ⏸️ | Docker Desktop 필요 |
+| ai-service | ❌ | ❌ | ❌ | 미구현 |
+| content-service | ✅ | ✅ | ⏸️ | Docker Desktop 필요 |
+| distribution-service | ❌ | ❌ | ❌ | 미구현 |
+| participation-service | ✅ | ✅ | ⏸️ | Docker Desktop 필요 |
+| analytics-service | ✅ | ✅ | ⏸️ | Docker Desktop 필요 |
+
+**빌드 가능 서비스**: 4개 (event-service, content-service, participation-service, analytics-service)
+
+## 3. JAR 파일 빌드
+
+### 3.1 bootJar 설정 확인
+
+root `build.gradle`에 이미 설정되어 있음:
+
+```gradle
+// Configure bootJar task for each service
+bootJar {
+    archiveFileName = "${project.name}.jar"
+}
+```
+
+### 3.2 JAR 빌드 실행
+
+**명령어**:
+```bash
+./gradlew :analytics-service:bootJar :content-service:bootJar :event-service:bootJar :participation-service:bootJar :user-service:bootJar --no-daemon
+```
+
+**빌드 결과**:
+
+✅ **성공한 서비스 (4개)**:
+- `analytics-service/build/libs/analytics-service.jar`
+- `content-service/build/libs/content-service.jar`
+- `event-service/build/libs/event-service.jar`
+- `participation-service/build/libs/participation-service.jar`
+
+❌ **실패한 서비스 (1개)**:
+- `user-service`: 컴파일 에러 발생
+
+**user-service 컴파일 에러 상세**:
+```
+UserController.java:93: error: incompatible types: UUID cannot be converted to Long
+        Long userId = principal.getUserId();
+                                         ^
+UserController.java:109: error: incompatible types: UUID cannot be converted to Long
+        Long userId = principal.getUserId();
+                                         ^
+UserController.java:126: error: incompatible types: UUID cannot be converted to Long
+        Long userId = principal.getUserId();
+                                         ^
+AuthenticationServiceImpl.java:72: error: method createAccessToken in class JwtTokenProvider cannot be applied to given types;
+  required: UUID,UUID,String,String,List<String>
+  found:    Long,String,String,List<String>
+  reason: actual and formal argument lists differ in length
+```
+
+**조치 필요**: user-service의 User ID 타입을 Long에서 UUID로 변경 필요
+
+## 4. Dockerfile 작성
+
+**파일 위치**: `deployment/container/Dockerfile-backend`
+
+**내용**:
+```dockerfile
+# Build stage
+FROM openjdk:23-oraclelinux8 AS builder
+ARG BUILD_LIB_DIR
+ARG ARTIFACTORY_FILE
+COPY ${BUILD_LIB_DIR}/${ARTIFACTORY_FILE} app.jar
+
+# Run stage
+FROM openjdk:23-slim
+ENV USERNAME=k8s
+ENV ARTIFACTORY_HOME=/home/${USERNAME}
+ENV JAVA_OPTS=""
+
+# Add a non-root user
+RUN adduser --system --group ${USERNAME} && \
+    mkdir -p ${ARTIFACTORY_HOME} && \
+    chown ${USERNAME}:${USERNAME} ${ARTIFACTORY_HOME}
+
+WORKDIR ${ARTIFACTORY_HOME}
+COPY --from=builder app.jar app.jar
+RUN chown ${USERNAME}:${USERNAME} app.jar
+
+USER ${USERNAME}
+
+ENTRYPOINT [ "sh", "-c" ]
+CMD ["java ${JAVA_OPTS} -jar app.jar"]
+```
+
+**특징**:
+- Multi-stage build (빌드 단계와 실행 단계 분리)
+- OpenJDK 23 사용
+- 비root 사용자(k8s)로 실행하여 보안 강화
+- JAVA_OPTS 환경변수로 JVM 옵션 커스터마이징 가능
+- linux/amd64 플랫폼 지원
+
+## 5. 컨테이너 이미지 빌드
+
+### 5.1 사전 조건
+
+⚠️ **Docker Desktop 실행 필요**
+
+이미지 빌드 전에 Docker Desktop이 실행되어 있어야 합니다:
+
+1. Windows에서 Docker Desktop 실행
+2. 시스템 트레이에서 "Docker Desktop is running" 확인
+3. 확인 명령어: `docker ps`
+
+### 5.2 빌드 명령어
+
+#### 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 .
+```
+
+#### content-service
+```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 .
+```
+
+#### event-service
+```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 .
+```
+
+#### participation-service
+```bash
+docker build \
+  --platform linux/amd64 \
+  --build-arg BUILD_LIB_DIR="participation-service/build/libs" \
+  --build-arg ARTIFACTORY_FILE="participation-service.jar" \
+  -f deployment/container/Dockerfile-backend \
+  -t participation-service:latest .
+```
+
+### 5.3 일괄 빌드 스크립트
+
+모든 서비스를 한 번에 빌드하려면 다음 스크립트를 사용하세요:
+
+**Windows (PowerShell)**:
+```powershell
+# 빌드 가능한 서비스 목록
+$services = @(
+    "analytics-service",
+    "content-service",
+    "event-service",
+    "participation-service"
+)
+
+# 각 서비스 빌드
+foreach ($service in $services) {
+    Write-Host "Building $service..." -ForegroundColor Green
+    docker build `
+        --platform linux/amd64 `
+        --build-arg BUILD_LIB_DIR="$service/build/libs" `
+        --build-arg ARTIFACTORY_FILE="$service.jar" `
+        -f deployment/container/Dockerfile-backend `
+        -t ${service}:latest .
+
+    if ($LASTEXITCODE -eq 0) {
+        Write-Host "✅ $service build completed" -ForegroundColor Green
+    } else {
+        Write-Host "❌ $service build failed" -ForegroundColor Red
+    }
+}
+```
+
+**Linux/Mac (Bash)**:
+```bash
+#!/bin/bash
+
+# 빌드 가능한 서비스 목록
+services=(
+    "analytics-service"
+    "content-service"
+    "event-service"
+    "participation-service"
+)
+
+# 각 서비스 빌드
+for service in "${services[@]}"; do
+    echo "Building $service..."
+    docker build \
+        --platform linux/amd64 \
+        --build-arg BUILD_LIB_DIR="${service}/build/libs" \
+        --build-arg ARTIFACTORY_FILE="${service}.jar" \
+        -f deployment/container/Dockerfile-backend \
+        -t ${service}:latest .
+
+    if [ $? -eq 0 ]; then
+        echo "✅ $service build completed"
+    else
+        echo "❌ $service build failed"
+    fi
+done
+```
+
+## 6. 이미지 확인
+
+### 6.1 빌드된 이미지 목록 확인
+
+```bash
+docker images | grep -E "analytics-service|content-service|event-service|participation-service"
+```
+
+**예상 출력**:
+```
+analytics-service        latest    <IMAGE_ID>   <TIME>   <SIZE>
+content-service          latest    <IMAGE_ID>   <TIME>   <SIZE>
+event-service            latest    <IMAGE_ID>   <TIME>   <SIZE>
+participation-service    latest    <IMAGE_ID>   <TIME>   <SIZE>
+```
+
+### 6.2 개별 서비스 이미지 확인
+
+```bash
+# analytics-service
+docker images analytics-service:latest
+
+# content-service
+docker images content-service:latest
+
+# event-service
+docker images event-service:latest
+
+# participation-service
+docker images participation-service:latest
+```
+
+### 6.3 이미지 상세 정보 확인
+
+```bash
+# 이미지 레이어 확인
+docker history <service-name>:latest
+
+# 이미지 메타데이터 확인
+docker inspect <service-name>:latest
+```
+
+## 7. 테스트 실행
+
+### 7.1 로컬에서 컨테이너 실행 테스트
+
+```bash
+# analytics-service 실행 예시
+docker run -d \
+  --name analytics-service-test \
+  -p 8080:8080 \
+  -e JAVA_OPTS="-Xms256m -Xmx512m" \
+  -e SPRING_PROFILES_ACTIVE=dev \
+  analytics-service:latest
+
+# 로그 확인
+docker logs -f analytics-service-test
+
+# 헬스체크
+curl http://localhost:8080/actuator/health
+
+# 컨테이너 정리
+docker stop analytics-service-test
+docker rm analytics-service-test
+```
+
+## 8. 문제 해결
+
+### 8.1 user-service 컴파일 에러
+
+**문제**: UUID와 Long 타입 불일치
+
+**해결 방법**:
+1. `UserController.java`에서 `Long userId` → `UUID userId` 변경
+2. `AuthenticationServiceImpl.java`와 `UserServiceImpl.java`에서 `createAccessToken` 메서드 호출 시 첫 번째 파라미터로 `sessionId` 추가
+3. 변경 후 재빌드:
+   ```bash
+   ./gradlew :user-service:bootJar --no-daemon
+   ```
+
+### 8.2 ai-service 및 distribution-service
+
+**문제**: 소스 코드 미구현
+
+**조치**: 해당 서비스의 구현이 완료된 후 컨테이너 이미지 빌드 진행
+
+### 8.3 Docker Desktop 연결 실패
+
+**에러 메시지**:
+```
+error during connect: open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.
+```
+
+**해결 방법**:
+1. Docker Desktop 실행
+2. 완전히 시작될 때까지 대기 (트레이 아이콘 확인)
+3. `docker ps` 명령으로 정상 동작 확인
+4. 빌드 명령 재실행
+
+## 9. 다음 단계
+
+1. ✅ **완료**: Dockerfile 작성 및 JAR 빌드
+2. ⏸️ **대기 중**: Docker Desktop 실행 후 이미지 빌드
+3. 📋 **예정**:
+   - user-service 컴파일 에러 수정
+   - ai-service 및 distribution-service 구현 완료 후 빌드
+   - 이미지 레지스트리에 푸시 (ACR 등)
+   - Kubernetes 배포 매니페스트 작성
+
+## 10. 참고 자료
+
+- Dockerfile: `deployment/container/Dockerfile-backend`
+- JAR 위치: `<service-name>/build/libs/<service-name>.jar`
+- 빌드 스크립트: 본 문서의 5.3 섹션 참조
+- OpenJDK 23 Documentation: https://openjdk.org/projects/jdk/23/
diff --git a/deployment/container/run-container-guide.md b/deployment/container/run-container-guide.md
new file mode 100644
index 0000000..fdfb71b
--- /dev/null
+++ b/deployment/container/run-container-guide.md
@@ -0,0 +1,493 @@
+# 백엔드 컨테이너 실행 가이드
+
+작성일: 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. 애플리케이션 빌드 및 컨테이너 이미지 생성
+
+`deployment/container/build-image.md` 파일의 가이드를 참조하여 다음 작업을 수행하세요:
+
+1. **JAR 파일 빌드**
+2. **Docker 이미지 생성**
+
+## 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 컨테이너 이미지 재생성
+
+`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/