P82282866/kt-event-marketing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

백엔드 컨테이너 실행 가이드 문서 추가

Browse Source 
- 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>
This commit is contained in:
doyeon 2025-10-27 16:17:23 +09:00
parent b198c46d06
commit 060921e756
1 changed files with 502 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

502
deployment/container/run-container-guide-back.md Normal file
View File

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