From 060921e756ac9979ed0b0d5bebedb3528a859a4f Mon Sep 17 00:00:00 2001
From: doyeon <dokaykim@gmail.com>
Date: Mon, 27 Oct 2025 16:17:23 +0900
Subject: [PATCH] =?UTF-8?q?=EB=B0=B1=EC=97=94=EB=93=9C=20=EC=BB=A8?=
 =?UTF-8?q?=ED=85=8C=EC=9D=B4=EB=84=88=20=EC=8B=A4=ED=96=89=20=EA=B0=80?=
 =?UTF-8?q?=EC=9D=B4=EB=93=9C=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- deployment/container/run-container-guide-back.md 파일 생성
- VM 접속 및 ACR 로그인 방법
- 컨테이너 실행 및 관리 방법
- 문제 해결 가이드
- 헬스체크 및 모니터링 방법
- 자동화 스크립트 예시
- 서비스별 실행 예시 포함

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../container/run-container-guide-back.md     | 502 ++++++++++++++++++
 1 file changed, 502 insertions(+)
 create mode 100644 deployment/container/run-container-guide-back.md

diff --git a/deployment/container/run-container-guide-back.md b/deployment/container/run-container-guide-back.md
new file mode 100644
index 0000000..6aaa614
--- /dev/null
+++ b/deployment/container/run-container-guide-back.md
@@ -0,0 +1,502 @@
+# 백엔드 컨테이너 실행 가이드
+
+백엔드 서비스를 Azure VM에서 Docker 컨테이너로 실행하는 가이드를 제공합니다.
+
+## 📋 목차
+
+1. [사전 준비](#사전-준비)
+2. [컨테이너 이미지 확인](#컨테이너-이미지-확인)
+3. [컨테이너 실행](#컨테이너-실행)
+4. [컨테이너 관리](#컨테이너-관리)
+5. [문제 해결](#문제-해결)
+
+---
+
+## 사전 준비
+
+### 1. VM 접속 정보
+```yaml
+ACR: acrdigitalgarage01
+VM:
+  KEY파일: ~/home/bastion-dg0505
+  사용자: azureuser
+  IP: 20.196.65.160
+```
+
+### 2. VM 접속
+```bash
+# SSH 접속
+ssh -i ~/home/bastion-dg0505 azureuser@20.196.65.160
+```
+
+### 3. Docker 및 ACR 로그인 확인
+```bash
+# Docker 실행 확인
+docker --version
+
+# ACR 로그인 (필요시)
+az acr login --name acrdigitalgarage01
+```
+
+---
+
+## 컨테이너 이미지 확인
+
+### 1. ACR에서 이미지 목록 조회
+```bash
+# 이미지 목록 확인
+az acr repository list --name acrdigitalgarage01 --output table
+
+# 특정 이미지의 태그 확인
+az acr repository show-tags --name acrdigitalgarage01 \
+  --repository {service-name} --output table
+```
+
+### 2. 실행할 이미지 Pull
+```bash
+# 이미지 다운로드
+docker pull acrdigitalgarage01.azurecr.io/{service-name}:{tag}
+
+# 예: participation-service
+docker pull acrdigitalgarage01.azurecr.io/participation-service:latest
+```
+
+---
+
+## 컨테이너 실행
+
+### 1. 환경 변수 준비
+
+각 서비스별 환경 변수를 확인하고 준비합니다.
+
+```bash
+# .env 파일 생성 (예시)
+cat > ~/event-marketing.env << EOF
+# Database
+DB_HOST=your-db-host
+DB_PORT=5432
+DB_NAME=event_marketing
+DB_USERNAME=your-username
+DB_PASSWORD=your-password
+
+# Redis
+REDIS_HOST=your-redis-host
+REDIS_PORT=6379
+
+# Kafka
+KAFKA_BOOTSTRAP_SERVERS=your-kafka:9092
+
+# Application
+SERVER_PORT=8080
+SPRING_PROFILES_ACTIVE=prod
+EOF
+```
+
+### 2. 네트워크 생성 (선택사항)
+
+여러 컨테이너를 함께 실행할 경우 네트워크를 생성합니다.
+
+```bash
+# Docker 네트워크 생성
+docker network create event-marketing-network
+```
+
+### 3. 컨테이너 실행
+
+#### 기본 실행
+```bash
+docker run -d \
+  --name {service-name} \
+  --env-file ~/event-marketing.env \
+  -p 8080:8080 \
+  acrdigitalgarage01.azurecr.io/{service-name}:latest
+```
+
+#### 네트워크 포함 실행
+```bash
+docker run -d \
+  --name {service-name} \
+  --network event-marketing-network \
+  --env-file ~/event-marketing.env \
+  -p 8080:8080 \
+  acrdigitalgarage01.azurecr.io/{service-name}:latest
+```
+
+#### 볼륨 마운트 포함 실행
+```bash
+docker run -d \
+  --name {service-name} \
+  --network event-marketing-network \
+  --env-file ~/event-marketing.env \
+  -p 8080:8080 \
+  -v ~/logs/{service-name}:/app/logs \
+  acrdigitalgarage01.azurecr.io/{service-name}:latest
+```
+
+### 4. 여러 서비스 실행 (docker-compose 사용)
+
+`docker-compose.yml` 파일 생성:
+
+```yaml
+version: '3.8'
+
+services:
+  participation-service:
+    image: acrdigitalgarage01.azurecr.io/participation-service:latest
+    container_name: participation-service
+    env_file:
+      - ./event-marketing.env
+    ports:
+      - "8080:8080"
+    networks:
+      - event-marketing-network
+    volumes:
+      - ./logs/participation:/app/logs
+    restart: unless-stopped
+
+  # 다른 서비스 추가...
+
+networks:
+  event-marketing-network:
+    driver: bridge
+
+volumes:
+  logs:
+```
+
+실행:
+```bash
+# docker-compose로 모든 서비스 시작
+docker-compose up -d
+
+# 특정 서비스만 시작
+docker-compose up -d participation-service
+```
+
+---
+
+## 컨테이너 관리
+
+### 1. 컨테이너 상태 확인
+```bash
+# 실행 중인 컨테이너 확인
+docker ps
+
+# 모든 컨테이너 확인 (중지된 것 포함)
+docker ps -a
+
+# 특정 컨테이너 상세 정보
+docker inspect {container-name}
+```
+
+### 2. 로그 확인
+```bash
+# 실시간 로그 확인
+docker logs -f {container-name}
+
+# 최근 100줄 로그 확인
+docker logs --tail 100 {container-name}
+
+# 타임스탬프 포함 로그 확인
+docker logs -t {container-name}
+```
+
+### 3. 컨테이너 중지/시작/재시작
+```bash
+# 중지
+docker stop {container-name}
+
+# 시작
+docker start {container-name}
+
+# 재시작
+docker restart {container-name}
+
+# 강제 중지
+docker kill {container-name}
+```
+
+### 4. 컨테이너 삭제
+```bash
+# 중지된 컨테이너 삭제
+docker rm {container-name}
+
+# 실행 중인 컨테이너 강제 삭제
+docker rm -f {container-name}
+
+# 중지된 모든 컨테이너 삭제
+docker container prune
+```
+
+### 5. 컨테이너 내부 접속
+```bash
+# bash 쉘로 접속
+docker exec -it {container-name} bash
+
+# 특정 명령 실행
+docker exec {container-name} ls -la /app
+```
+
+### 6. 리소스 사용량 확인
+```bash
+# 실시간 리소스 사용량
+docker stats
+
+# 특정 컨테이너의 리소스 사용량
+docker stats {container-name}
+```
+
+---
+
+## 문제 해결
+
+### 1. 컨테이너가 시작되지 않는 경우
+
+```bash
+# 로그 확인
+docker logs {container-name}
+
+# 컨테이너 상태 확인
+docker inspect {container-name}
+
+# 환경 변수 확인
+docker exec {container-name} env
+```
+
+### 2. 포트 충돌
+
+```bash
+# 포트 사용 확인
+netstat -tuln | grep {port}
+
+# 다른 포트로 매핑
+docker run -d -p 8081:8080 ...
+```
+
+### 3. 네트워크 연결 문제
+
+```bash
+# 네트워크 목록 확인
+docker network ls
+
+# 네트워크 상세 정보
+docker network inspect {network-name}
+
+# 컨테이너를 네트워크에 연결
+docker network connect {network-name} {container-name}
+```
+
+### 4. 이미지 Pull 실패
+
+```bash
+# ACR 로그인 재시도
+az acr login --name acrdigitalgarage01
+
+# 수동으로 Pull
+docker pull acrdigitalgarage01.azurecr.io/{service-name}:{tag}
+```
+
+### 5. 디스크 공간 부족
+
+```bash
+# 사용하지 않는 이미지 삭제
+docker image prune -a
+
+# 사용하지 않는 볼륨 삭제
+docker volume prune
+
+# 전체 정리 (주의!)
+docker system prune -a
+```
+
+---
+
+## 헬스체크 및 모니터링
+
+### 1. 헬스체크 엔드포인트 확인
+```bash
+# Spring Boot Actuator health endpoint
+curl http://localhost:8080/actuator/health
+
+# 상세 헬스 정보
+curl http://localhost:8080/actuator/health/readiness
+curl http://localhost:8080/actuator/health/liveness
+```
+
+### 2. 메트릭 확인
+```bash
+# 메트릭 엔드포인트
+curl http://localhost:8080/actuator/metrics
+
+# 특정 메트릭 확인
+curl http://localhost:8080/actuator/metrics/jvm.memory.used
+```
+
+### 3. 로그 모니터링 스크립트
+```bash
+#!/bin/bash
+# monitor-logs.sh
+
+SERVICE_NAME=$1
+if [ -z "$SERVICE_NAME" ]; then
+  echo "Usage: ./monitor-logs.sh {service-name}"
+  exit 1
+fi
+
+# 에러 로그 모니터링
+docker logs -f $SERVICE_NAME 2>&1 | grep -i error
+```
+
+---
+
+## 자동화 스크립트
+
+### 1. 서비스 재배포 스크립트
+```bash
+#!/bin/bash
+# redeploy.sh
+
+SERVICE_NAME=$1
+IMAGE_TAG=${2:-latest}
+
+if [ -z "$SERVICE_NAME" ]; then
+  echo "Usage: ./redeploy.sh {service-name} [tag]"
+  exit 1
+fi
+
+echo "📦 Pulling latest image..."
+docker pull acrdigitalgarage01.azurecr.io/$SERVICE_NAME:$IMAGE_TAG
+
+echo "🛑 Stopping old container..."
+docker stop $SERVICE_NAME
+docker rm $SERVICE_NAME
+
+echo "🚀 Starting new container..."
+docker run -d \
+  --name $SERVICE_NAME \
+  --env-file ~/event-marketing.env \
+  -p 8080:8080 \
+  acrdigitalgarage01.azurecr.io/$SERVICE_NAME:$IMAGE_TAG
+
+echo "✅ Deployment complete!"
+docker logs -f $SERVICE_NAME
+```
+
+### 2. 헬스체크 스크립트
+```bash
+#!/bin/bash
+# healthcheck.sh
+
+SERVICE_NAME=$1
+MAX_RETRIES=30
+RETRY_INTERVAL=2
+
+if [ -z "$SERVICE_NAME" ]; then
+  echo "Usage: ./healthcheck.sh {service-name}"
+  exit 1
+fi
+
+echo "⏳ Waiting for $SERVICE_NAME to be healthy..."
+
+for i in $(seq 1 $MAX_RETRIES); do
+  if curl -f http://localhost:8080/actuator/health > /dev/null 2>&1; then
+    echo "✅ $SERVICE_NAME is healthy!"
+    exit 0
+  fi
+  echo "Attempt $i/$MAX_RETRIES failed. Retrying in ${RETRY_INTERVAL}s..."
+  sleep $RETRY_INTERVAL
+done
+
+echo "❌ $SERVICE_NAME failed to become healthy"
+exit 1
+```
+
+---
+
+## 보안 고려사항
+
+### 1. 환경 변수 보호
+```bash
+# .env 파일 권한 설정
+chmod 600 ~/event-marketing.env
+
+# 민감 정보는 Azure Key Vault 사용 권장
+```
+
+### 2. 컨테이너 보안
+```bash
+# 읽기 전용 파일시스템으로 실행
+docker run -d --read-only ...
+
+# 리소스 제한
+docker run -d \
+  --memory="512m" \
+  --cpus="0.5" \
+  ...
+```
+
+### 3. 네트워크 보안
+```bash
+# 필요한 포트만 노출
+# 내부 통신은 Docker 네트워크 사용
+```
+
+---
+
+## 서비스별 실행 예시
+
+### Participation Service
+```bash
+docker run -d \
+  --name participation-service \
+  --network event-marketing-network \
+  --env-file ~/event-marketing.env \
+  -e SERVER_PORT=8080 \
+  -e SPRING_PROFILES_ACTIVE=prod \
+  -p 8080:8080 \
+  -v ~/logs/participation:/app/logs \
+  acrdigitalgarage01.azurecr.io/participation-service:latest
+```
+
+### Event Service
+```bash
+docker run -d \
+  --name event-service \
+  --network event-marketing-network \
+  --env-file ~/event-marketing.env \
+  -e SERVER_PORT=8081 \
+  -e SPRING_PROFILES_ACTIVE=prod \
+  -p 8081:8081 \
+  -v ~/logs/event:/app/logs \
+  acrdigitalgarage01.azurecr.io/event-service:latest
+```
+
+### User Service
+```bash
+docker run -d \
+  --name user-service \
+  --network event-marketing-network \
+  --env-file ~/event-marketing.env \
+  -e SERVER_PORT=8082 \
+  -e SPRING_PROFILES_ACTIVE=prod \
+  -p 8082:8082 \
+  -v ~/logs/user:/app/logs \
+  acrdigitalgarage01.azurecr.io/user-service:latest
+```
+
+### Analytics Service
+```bash
+docker run -d \
+  --name analytics-service \
+  --network event-marketing-network \
+  --env-file ~/event-marketing.env \
+  -e SERVER_PORT=8083 \
+  -e SPRING_PROFILES_ACTIVE=prod \
+  -p 8083:8083 \
+  -v ~/logs/analytics:/app/logs \
+  acrdigitalgarage01.azurecr.io/analytics-service:latest
+```
+
+---
+
+이 가이드를 통해 백엔드 서비스를 안전하고 효율적으로 컨테이너로 실행할 수 있습니다. 추가 질문이나 문제가 있으면 언제든지 문의해 주세요! 🚀