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

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

백엔드 서비스를 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
```

---

이 가이드를 통해 백엔드 서비스를 안전하고 효율적으로 컨테이너로 실행할 수 있습니다. 추가 질문이나 문제가 있으면 언제든지 문의해 주세요! 🚀