Jenkins 기반 CI/CD 파이프라인 구성

- Kustomize 기반 환경별(dev/staging/prod) 매니페스트 관리 - Jenkins 파이프라인 스크립트 작성 (Podman, Gradle, kubectl 컨테이너) - SonarQube 코드 품질 분석 및 Quality Gate 연동 - 수동 배포 및 리소스 검증 스크립트 추가 - k8s 매니페스트 구조 재정리 (configmaps, secrets, deployments, services 분리) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-12 19:49:10 +00:00 · 2025-12-01 10:23:32 +09:00
parent 21b9c77109
commit f12fed5de9
113 changed files with 2955 additions and 3567 deletions
@@ -5,13 +5,14 @@ ARG ARTIFACTORY_FILE
 COPY ${BUILD_LIB_DIR}/${ARTIFACTORY_FILE} app.jar

 # Run stage
-FROM eclipse-temurin:21-jre
+FROM eclipse-temurin:21-jre-alpine
 ENV USERNAME=k8s
 ENV ARTIFACTORY_HOME=/home/${USERNAME}
 ENV JAVA_OPTS=""

 # Add a non-root user
-RUN adduser --system --group ${USERNAME} && \
+RUN addgroup -S ${USERNAME} && \
+    adduser -S -G ${USERNAME} ${USERNAME} && \
    mkdir -p ${ARTIFACTORY_HOME} && \
    chown ${USERNAME}:${USERNAME} ${ARTIFACTORY_HOME}

@@ -22,4 +23,4 @@ RUN chown ${USERNAME}:${USERNAME} app.jar
 USER ${USERNAME}

 ENTRYPOINT [ "sh", "-c" ]
-CMD ["java ${JAVA_OPTS} -jar app.jar"]
+CMD ["java ${JAVA_OPTS} -jar app.jar"]
@@ -1,48 +1,37 @@
-# 백엔드 컨테이너 이미지 빌드 결과서
+# 백엔드 컨테이너 이미지 작성 결과서

-## 작업 개요
- **작업일시**: 2025-01-10
- **작업자**: 최운영/데옵스
- **작업 목표**: 백엔드 마이크로서비스들의 컨테이너 이미지 생성
+## 개요
+본 문서는 phonebill 프로젝트의 백엔드 마이크로서비스들의 컨테이너 이미지 빌드 과정과 결과를 기록합니다.

-## 빌드 대상 서비스
-총 5개의 백엔드 서비스에 대한 컨테이너 이미지를 생성했습니다.
+## 대상 서비스
+| 서비스명 | 설명 |
+|---------|------|
+| api-gateway | API Gateway 서비스 |
+| user-service | 사용자 인증/관리 서비스 |
+| bill-service | 요금 조회 서비스 |
+| product-service | 상품 변경 서비스 |
+| kos-mock | KOS 목업 서비스 |

-1. **api-gateway**: API Gateway 서비스
-2. **user-service**: 사용자 관리 서비스  
-3. **bill-service**: 요금 조회 서비스
-4. **product-service**: 상품 변경 서비스
-5. **kos-mock**: KOS 시스템 목업 서비스
+## Dockerfile 구성

-## 사전 작업
-
-### 1. 서비스별 bootJar 설정 추가
-각 서비스의 build.gradle 파일에 일관된 JAR 파일명 설정을 추가했습니다.
-
-```gradle
-bootJar {
-    archiveFileName = '{서비스명}.jar'
-}
-```
-
-### 2. Dockerfile 생성
-`deployment/container/Dockerfile-backend` 파일을 생성했습니다.
+**파일 위치**: `deployment/container/Dockerfile-backend`

 ```dockerfile
 # Build stage
-FROM openjdk:23-oraclelinux8 AS builder
+FROM eclipse-temurin:21-jdk AS builder
 ARG BUILD_LIB_DIR
 ARG ARTIFACTORY_FILE
 COPY ${BUILD_LIB_DIR}/${ARTIFACTORY_FILE} app.jar

 # Run stage
-FROM openjdk:23-slim
+FROM eclipse-temurin:21-jre-alpine
 ENV USERNAME=k8s
 ENV ARTIFACTORY_HOME=/home/${USERNAME}
 ENV JAVA_OPTS=""

 # Add a non-root user
-RUN adduser --system --group ${USERNAME} && \
+RUN addgroup -S ${USERNAME} && \
+    adduser -S -G ${USERNAME} ${USERNAME} && \
    mkdir -p ${ARTIFACTORY_HOME} && \
    chown ${USERNAME}:${USERNAME} ${ARTIFACTORY_HOME}

@@ -56,136 +45,99 @@ ENTRYPOINT [ "sh", "-c" ]
 CMD ["java ${JAVA_OPTS} -jar app.jar"]
 ```

-### 3. 서비스별 빌드
-모든 서비스에 대해 Gradle 빌드를 수행했습니다.
+### Dockerfile 특징
+- **멀티스테이지 빌드**: 빌드와 실행 환경 분리로 이미지 크기 최적화
+- **베이스 이미지**: Eclipse Temurin 21 JRE Alpine (경량화)
+- **보안**: 비루트 사용자(k8s)로 실행
+- **유연성**: `JAVA_OPTS` 환경변수로 JVM 옵션 설정 가능

+## 빌드 과정
+
+### 1. Gradle 빌드 (JAR 파일 생성)
 ```bash
-./gradlew api-gateway:clean api-gateway:bootJar
-./gradlew user-service:clean user-service:bootJar
-./gradlew bill-service:clean bill-service:bootJar
-./gradlew product-service:clean product-service:bootJar
-./gradlew kos-mock:clean kos-mock:bootJar
+./gradlew clean build -x test
 ```

-## 컨테이너 이미지 빌드
+### 2. 컨테이너 이미지 빌드
+각 서비스별로 아래 명령을 실행합니다:

-각 서비스별로 다음 명령어를 사용하여 컨테이너 이미지를 빌드했습니다.
-
-### API Gateway
 ```bash
 DOCKER_FILE=deployment/container/Dockerfile-backend
-service=api-gateway

+# api-gateway
 docker build \
  --platform linux/amd64 \
-  --build-arg BUILD_LIB_DIR="${service}/build/libs" \
-  --build-arg ARTIFACTORY_FILE="${service}.jar" \
+  --build-arg BUILD_LIB_DIR="api-gateway/build/libs" \
+  --build-arg ARTIFACTORY_FILE="api-gateway.jar" \
  -f ${DOCKER_FILE} \
-  -t ${service}:latest .
-```
-
-### User Service
-```bash
-DOCKER_FILE=deployment/container/Dockerfile-backend
-service=user-service
+  -t api-gateway:latest .

+# user-service
 docker build \
  --platform linux/amd64 \
-  --build-arg BUILD_LIB_DIR="${service}/build/libs" \
-  --build-arg ARTIFACTORY_FILE="${service}.jar" \
+  --build-arg BUILD_LIB_DIR="user-service/build/libs" \
+  --build-arg ARTIFACTORY_FILE="user-service.jar" \
  -f ${DOCKER_FILE} \
-  -t ${service}:latest .
-```
-
-### Bill Service
-```bash
-DOCKER_FILE=deployment/container/Dockerfile-backend
-service=bill-service
+  -t user-service:latest .

+# bill-service
 docker build \
  --platform linux/amd64 \
-  --build-arg BUILD_LIB_DIR="${service}/build/libs" \
-  --build-arg ARTIFACTORY_FILE="${service}.jar" \
+  --build-arg BUILD_LIB_DIR="bill-service/build/libs" \
+  --build-arg ARTIFACTORY_FILE="bill-service.jar" \
  -f ${DOCKER_FILE} \
-  -t ${service}:latest .
-```
-
-### Product Service
-```bash
-DOCKER_FILE=deployment/container/Dockerfile-backend
-service=product-service
+  -t bill-service:latest .

+# product-service
 docker build \
  --platform linux/amd64 \
-  --build-arg BUILD_LIB_DIR="${service}/build/libs" \
-  --build-arg ARTIFACTORY_FILE="${service}.jar" \
+  --build-arg BUILD_LIB_DIR="product-service/build/libs" \
+  --build-arg ARTIFACTORY_FILE="product-service.jar" \
  -f ${DOCKER_FILE} \
-  -t ${service}:latest .
-```
-
-### KOS Mock Service
-```bash
-DOCKER_FILE=deployment/container/Dockerfile-backend
-service=kos-mock
+  -t product-service:latest .

+# kos-mock
 docker build \
  --platform linux/amd64 \
-  --build-arg BUILD_LIB_DIR="${service}/build/libs" \
-  --build-arg ARTIFACTORY_FILE="${service}.jar" \
+  --build-arg BUILD_LIB_DIR="kos-mock/build/libs" \
+  --build-arg ARTIFACTORY_FILE="kos-mock.jar" \
  -f ${DOCKER_FILE} \
-  -t ${service}:latest .
+  -t kos-mock:latest .
 ```

 ## 빌드 결과

-### 성공적으로 생성된 이미지들
+### 생성된 이미지 목록
+| 이미지명 | 태그 | 크기 | 상태 |
+|---------|------|------|------|
+| api-gateway | latest | 158MB | ✅ 성공 |
+| user-service | latest | 205MB | ✅ 성공 |
+| bill-service | latest | 214MB | ✅ 성공 |
+| product-service | latest | 220MB | ✅ 성공 |
+| kos-mock | latest | 201MB | ✅ 성공 |

-| 서비스명 | 이미지 태그 | 이미지 ID | 크기 | 생성 시간 |
-|---------|------------|-----------|------|----------|
-| api-gateway | latest | 5f4a2a5527b8 | 329MB | 3분 전 |
-| user-service | latest | a8a85ba0b703 | 376MB | 2분 전 |
-| bill-service | latest | b77190090a40 | 385MB | 1분 전 |
-| product-service | latest | 5a6fba790ca3 | 392MB | 1분 전 |
-| kos-mock | latest | 3f5878cf2f1e | 372MB | 35초 전 |
-
-### 이미지 검증 명령어 실행 결과
+### 이미지 확인 명령
 ```bash
-$ docker images | grep -E "(api-gateway|user-service|bill-service|product-service|kos-mock)"
-kos-mock                                                 latest    3f5878cf2f1e   35 seconds ago       372MB
-product-service                                          latest    5a6fba790ca3   About a minute ago   392MB
-bill-service                                             latest    b77190090a40   About a minute ago   385MB
-user-service                                             latest    a8a85ba0b703   2 minutes ago        376MB
-api-gateway                                              latest    5f4a2a5527b8   3 minutes ago        329MB
+docker images | grep -E "api-gateway|user-service|bill-service|product-service|kos-mock"
 ```

-## 빌드 특징
+## 이미지 레지스트리 푸시 (선택)

-### 멀티 스테이지 빌드
- **Build Stage**: OpenJDK 23-oraclelinux8 사용하여 JAR 파일 복사
- **Runtime Stage**: OpenJDK 23-slim 사용하여 경량화된 실행 환경 구성
+Azure Container Registry에 푸시하는 경우:
+```bash
+REGISTRY=docker.io
+PROJECT=hiondal
+TAG=latest

-### 보안 강화
- 비루트 사용자 `k8s` 생성 및 사용
- 적절한 파일 소유권 및 권한 설정
- 최소 권한 원칙 적용
+# 로그인
+az acr login --name acrdigitalgarage01

-### 플랫폼 호환성
- `--platform linux/amd64` 옵션으로 AMD64 아키텍처 지원
- 쿠버네티스 클러스터 배포에 적합한 형태
+# 태그 및 푸시
+for service in api-gateway user-service bill-service product-service kos-mock; do
+  docker tag ${service}:latest ${REGISTRY}/${PROJECT}/${service}:${TAG}
+  docker push ${REGISTRY}/${PROJECT}/${service}:${TAG}
+done
+```

-## 다음 단계
-
-1. **컨테이너 레지스트리 푸시**: ACR 또는 Docker Hub에 이미지 푸시
-2. **쿠버네티스 매니페스트 작성**: Deployment, Service 등 K8s 리소스 정의
-3. **헬름 차트 작성**: 패키지 관리를 위한 Helm 차트 구성
-4. **CI/CD 파이프라인 통합**: 자동화된 빌드 및 배포 파이프라인 구축
-
-## 주요 성과
-
-✅ **모든 백엔드 서비스 컨테이너화 완료** (5개 서비스)  
-✅ **멀티 스테이지 빌드로 최적화된 이미지** (평균 360MB)  
-✅ **보안 강화된 컨테이너 구성** (비루트 사용자)  
-✅ **일관된 빌드 프로세스** (표준화된 Dockerfile)  
-✅ **쿠버네티스 배포 준비 완료**
-
-모든 백엔드 서비스들이 성공적으로 컨테이너화되었으며, 프로덕션 환경 배포를 위한 준비가 완료되었습니다.
+## 작성일
+2025-11-27
@@ -1,328 +1,326 @@
-# 백엔드 컨테이너 실행 가이드
+# 백엔드 컨테이너 실행 가이드 (로컬 환경)

-## 1. 시스템 정보
- **시스템명**: phonebill
- **서비스 목록**: 
-  - api-gateway (포트: 8080)
-  - user-service (포트: 8081) 
-  - bill-service (포트: 8082)
-  - product-service (포트: 8083)
-  - kos-mock (포트: 8084)
+## 개요
+본 문서는 phonebill 프로젝트의 백엔드 마이크로서비스들을 로컬 환경에서 Docker 컨테이너로 실행하는 방법을 안내합니다.

-## 2. VM 접속 방법
+## 실행 정보
+| 항목 | 값 |
+|------|-----|
+| Image Registry | docker.io |
+| 시스템명 | phonebill |
+| 실행 환경 | 로컬 (localhost) |

-### Windows 사용자
-1. **Windows Terminal** 실행
-2. 아래 명령어 순서대로 실행:
+## 대상 서비스
+| 서비스명 | 포트 | 설명 |
+|---------|------|------|
+| kos-mock | 8084 | KOS 목업 서비스 |
+| user-service | 8081 | 사용자 인증/관리 서비스 |
+| bill-service | 8082 | 요금 조회 서비스 |
+| product-service | 8083 | 상품 변경 서비스 |
+| api-gateway | 8080 | API Gateway |

+## 사전 준비 사항
+
+### 1. Docker 설치 확인
 ```bash
-# Private Key 파일 권한 설정 (최초 1회만)
-chmod 400 ~/home/bastion-dg0500
-
-# VM 접속
-ssh -i ~/home/bastion-dg0500 azureuser@4.230.5.6
+docker --version
 ```

-### Linux/Mac 사용자
-1. **터미널** 실행
-2. 아래 명령어 순서대로 실행:
+### 2. 백킹 서비스 실행 확인
+컨테이너 실행 전 아래 백킹 서비스가 실행 중이어야 합니다:
+- **PostgreSQL** (auth-db: 15432, bill-inquiry-db: 25432, product-change-db: 35432)
+- **Redis** (16379)

+백킹 서비스 실행 상태 확인:
 ```bash
-# Private Key 파일 권한 설정 (최초 1회만)
-chmod 400 ~/home/bastion-dg0500
-
-# VM 접속
-ssh -i ~/home/bastion-dg0500 azureuser@4.230.5.6
+docker ps | grep -E "postgres|redis"
 ```

-## 3. 컨테이너 이미지 준비
+## 어플리케이션 빌드 및 컨테이너 이미지 생성

-### 3.1 이미지 빌드 (로컬에서 수행)
-먼저 로컬에서 이미지를 빌드해야 합니다. 아래 가이드를 참고하여 수행하세요:
-```bash
-# 이미지 빌드 가이드 확인
-cat deployment/container/build-image.md
-```
-
-### 3.2 Azure Container Registry 로그인
-ACR 인증 정보를 확인하고 Docker 로그인을 수행합니다:
+`deployment/container/build-image.md` 파일을 참조하여 이미지를 빌드합니다.

 ```bash
-# ACR 인증 정보 확인
-az acr credential show --name acrdigitalgarage01
+# Gradle 빌드
+./gradlew clean build -x test

-# 출력 예시:
-# {
-#   "passwords": [
-#     {
-#       "name": "password", 
-#       "value": "실제암호"
-#     }
-#   ],
-#   "username": "acrdigitalgarage01"
-# }
-
-# Docker 로그인 (위에서 확인한 username과 password 사용)
-docker login acrdigitalgarage01.azurecr.io -u acrdigitalgarage01 -p 실제암호
+# 이미지 빌드 예시 (api-gateway)
+docker build \
+  --platform linux/amd64 \
+  --build-arg BUILD_LIB_DIR="api-gateway/build/libs" \
+  --build-arg ARTIFACTORY_FILE="api-gateway.jar" \
+  -f deployment/container/Dockerfile-backend \
+  -t api-gateway:latest .
 ```

-### 3.3 이미지 Push (로컬에서 수행)
-각 서비스별로 이미지를 태깅하고 푸시합니다:
+## Docker Hub 로그인 (선택)

+이미지를 Docker Hub에 푸시하려면 로그인이 필요합니다:
+```bash
+docker login docker.io -u {Docker Hub ID} -p {암호}
+```
+
+## 이미지 태그 및 푸시 (선택)
+
+Docker Hub에 이미지를 푸시하는 경우:
+```bash
+# 태그
+docker tag api-gateway:latest docker.io/hiondal/api-gateway:latest
+
+# 푸시
+docker push docker.io/hiondal/api-gateway:latest
+```
+
+---
+
+## 컨테이너 실행
+
+> **중요**: 서비스 간 의존성이 있으므로 아래 순서대로 실행하세요.
+> 1. kos-mock → 2. user-service → 3. bill-service → 4. product-service → 5. api-gateway
+
+### 1. kos-mock 실행
+```bash
+docker run -d --name kos-mock --rm \
+  -p 8084:8084 \
+  -e SERVER_PORT=8084 \
+  -e SPRING_PROFILES_ACTIVE=dev \
+  kos-mock:latest
+```
+
+### 2. user-service 실행
+```bash
+docker run -d --name user-service --rm \
+  -p 8081:8081 \
+  -e SERVER_PORT=8081 \
+  -e SPRING_PROFILES_ACTIVE=dev \
+  -e CORS_ALLOWED_ORIGINS=http://localhost:3000 \
+  -e DB_HOST=localhost \
+  -e DB_PORT=15432 \
+  -e DB_NAME=authdb \
+  -e DB_USERNAME=unicorn \
+  -e DB_PASSWORD='P@ssw0rd$' \
+  -e DB_KIND=postgresql \
+  -e DDL_AUTO=update \
+  -e SHOW_SQL=true \
+  -e REDIS_HOST=host.docker.internal \
+  -e REDIS_PORT=16379 \
+  -e REDIS_PASSWORD='P@ssw0rd$' \
+  -e REDIS_DATABASE=0 \
+  -e JWT_SECRET='nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==' \
+  -e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
+  -e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
+  user-service:latest
+```
+
+### 3. bill-service 실행
+```bash
+docker run -d --name bill-service --rm \
+  -p 8082:8082 \
+  -e SERVER_PORT=8082 \
+  -e SPRING_PROFILES_ACTIVE=dev \
+  -e CORS_ALLOWED_ORIGINS=http://localhost:3000 \
+  -e DB_HOST=host.docker.internal \
+  -e DB_PORT=25432 \
+  -e DB_NAME=inquirydb \
+  -e DB_USERNAME=unicorn \
+  -e DB_PASSWORD='P@ssw0rd$' \
+  -e DB_KIND=postgresql \
+  -e DB_MAX_POOL=20 \
+  -e DB_MIN_IDLE=5 \
+  -e DB_CONNECTION_TIMEOUT=30000 \
+  -e DB_IDLE_TIMEOUT=600000 \
+  -e DB_MAX_LIFETIME=1800000 \
+  -e DB_LEAK_DETECTION=60000 \
+  -e REDIS_HOST=host.docker.internal \
+  -e REDIS_PORT=16379 \
+  -e REDIS_PASSWORD='P@ssw0rd$' \
+  -e REDIS_DATABASE=1 \
+  -e REDIS_TIMEOUT=2000 \
+  -e REDIS_MAX_ACTIVE=8 \
+  -e REDIS_MAX_IDLE=8 \
+  -e REDIS_MIN_IDLE=0 \
+  -e REDIS_MAX_WAIT=-1 \
+  -e KOS_BASE_URL=http://host.docker.internal:8084 \
+  -e JWT_SECRET='nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==' \
+  -e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
+  -e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
+  -e LOG_FILE_NAME=logs/bill-service.log \
+  bill-service:latest
+```
+
+### 4. product-service 실행
+```bash
+docker run -d --name product-service --rm \
+  -p 8083:8083 \
+  -e SERVER_PORT=8083 \
+  -e SPRING_PROFILES_ACTIVE=dev \
+  -e CORS_ALLOWED_ORIGINS=http://localhost:3000 \
+  -e DB_HOST=host.docker.internal \
+  -e DB_PORT=35432 \
+  -e DB_NAME=changedb \
+  -e DB_USERNAME=unicorn \
+  -e DB_PASSWORD='P@ssw0rd$' \
+  -e DB_KIND=postgresql \
+  -e DDL_AUTO=update \
+  -e REDIS_HOST=host.docker.internal \
+  -e REDIS_PORT=16379 \
+  -e REDIS_PASSWORD='P@ssw0rd$' \
+  -e REDIS_DATABASE=2 \
+  -e KOS_BASE_URL=http://host.docker.internal:8084 \
+  -e KOS_MOCK_ENABLED=true \
+  -e KOS_CLIENT_ID=product-service-dev \
+  -e KOS_API_KEY=dev-api-key \
+  -e JWT_SECRET='nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==' \
+  -e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
+  -e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
+  product-service:latest
+```
+
+### 5. api-gateway 실행
+```bash
+docker run -d --name api-gateway --rm \
+  -p 8080:8080 \
+  -e SERVER_PORT=8080 \
+  -e SPRING_PROFILES_ACTIVE=dev \
+  -e CORS_ALLOWED_ORIGINS=http://localhost:3000 \
+  -e USER_SERVICE_URL=http://host.docker.internal:8081 \
+  -e BILL_SERVICE_URL=http://host.docker.internal:8082 \
+  -e PRODUCT_SERVICE_URL=http://host.docker.internal:8083 \
+  -e KOS_MOCK_URL=http://host.docker.internal:8084 \
+  -e JWT_SECRET='nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==' \
+  -e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
+  -e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
+  api-gateway:latest
+```
+
+---
+
+## 실행 확인
+
+### 컨테이너 실행 상태 확인
+```bash
+docker ps | grep -E "api-gateway|user-service|bill-service|product-service|kos-mock"
+```
+
+### 예상 결과
+```
+CONTAINER ID   IMAGE                  PORTS                    NAMES
+xxxxxxxxxxxx   api-gateway:latest     0.0.0.0:8080->8080/tcp   api-gateway
+xxxxxxxxxxxx   product-service:latest 0.0.0.0:8083->8083/tcp   product-service
+xxxxxxxxxxxx   bill-service:latest    0.0.0.0:8082->8082/tcp   bill-service
+xxxxxxxxxxxx   user-service:latest    0.0.0.0:8081->8081/tcp   user-service
+xxxxxxxxxxxx   kos-mock:latest        0.0.0.0:8084->8084/tcp   kos-mock
+```
+
+### 서비스 헬스체크
 ```bash
 # API Gateway
-docker tag api-gateway:latest acrdigitalgarage01.azurecr.io/phonebill/api-gateway:latest
-docker push acrdigitalgarage01.azurecr.io/phonebill/api-gateway:latest
+curl http://localhost:8080/actuator/health

 # User Service
-docker tag user-service:latest acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
-docker push acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
+curl http://localhost:8081/actuator/health

 # Bill Service
-docker tag bill-service:latest acrdigitalgarage01.azurecr.io/phonebill/bill-service:latest
-docker push acrdigitalgarage01.azurecr.io/phonebill/bill-service:latest
+curl http://localhost:8082/actuator/health

 # Product Service
-docker tag product-service:latest acrdigitalgarage01.azurecr.io/phonebill/product-service:latest
-docker push acrdigitalgarage01.azurecr.io/phonebill/product-service:latest
+curl http://localhost:8083/actuator/health

 # KOS Mock
-docker tag kos-mock:latest acrdigitalgarage01.azurecr.io/phonebill/kos-mock:latest
-docker push acrdigitalgarage01.azurecr.io/phonebill/kos-mock:latest
+curl http://localhost:8084/actuator/health
 ```

-## 4. 컨테이너 실행 (VM에서 수행)
-
-### 4.1 KOS Mock 서비스 실행
+### 로그 확인
 ```bash
-SERVER_PORT=8084
-
-docker run -d --name kos-mock --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e SERVER_PORT=8084 \
-e SPRING_PROFILES_ACTIVE=dev \
-acrdigitalgarage01.azurecr.io/phonebill/kos-mock:latest
+docker logs -f api-gateway
+docker logs -f user-service
+docker logs -f bill-service
+docker logs -f product-service
+docker logs -f kos-mock
 ```

-### 4.2 User Service 실행
+---
+
+## 컨테이너 중지
+
+### 개별 서비스 중지
 ```bash
-SERVER_PORT=8081
-
-docker run -d --name user-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e CORS_ALLOWED_ORIGINS="http://localhost:3000,http://4.230.5.6:3000" \
-e DB_HOST=20.249.70.6 \
-e DB_KIND=postgresql \
-e DB_NAME=phonebill_auth \
-e DB_PASSWORD=AuthUser2025! \
-e DB_PORT=5432 \
-e DB_USERNAME=auth_user \
-e DDL_AUTO=update \
-e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
-e JWT_SECRET="nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==" \
-e REDIS_DATABASE=0 \
-e REDIS_HOST=20.249.193.103 \
-e REDIS_PASSWORD=Redis2025Dev! \
-e REDIS_PORT=6379 \
-e SERVER_PORT=8081 \
-e SHOW_SQL=true \
-e SPRING_PROFILES_ACTIVE=dev \
-acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
-```
-
-### 4.3 Bill Service 실행
-```bash
-SERVER_PORT=8082
-
-docker run -d --name bill-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e CORS_ALLOWED_ORIGINS="http://localhost:3000,http://4.230.5.6:3000" \
-e DB_CONNECTION_TIMEOUT=30000 \
-e DB_HOST=20.249.175.46 \
-e DB_IDLE_TIMEOUT=600000 \
-e DB_KIND=postgresql \
-e DB_LEAK_DETECTION=60000 \
-e DB_MAX_LIFETIME=1800000 \
-e DB_MAX_POOL=20 \
-e DB_MIN_IDLE=5 \
-e DB_NAME=bill_inquiry_db \
-e DB_PASSWORD=BillUser2025! \
-e DB_PORT=5432 \
-e DB_USERNAME=bill_inquiry_user \
-e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
-e JWT_SECRET="nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==" \
-e KOS_BASE_URL=http://4.230.5.6:8084 \
-e LOG_FILE_NAME=logs/bill-service.log \
-e REDIS_DATABASE=1 \
-e REDIS_HOST=20.249.193.103 \
-e REDIS_MAX_ACTIVE=8 \
-e REDIS_MAX_IDLE=8 \
-e REDIS_MAX_WAIT=-1 \
-e REDIS_MIN_IDLE=0 \
-e REDIS_PASSWORD=Redis2025Dev! \
-e REDIS_PORT=6379 \
-e REDIS_TIMEOUT=2000 \
-e SERVER_PORT=8082 \
-e SPRING_PROFILES_ACTIVE=dev \
-acrdigitalgarage01.azurecr.io/phonebill/bill-service:latest
-```
-
-### 4.4 Product Service 실행
-```bash
-SERVER_PORT=8083
-
-docker run -d --name product-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e CORS_ALLOWED_ORIGINS="http://localhost:3000,http://4.230.5.6:3000" \
-e DB_HOST=20.249.107.185 \
-e DB_KIND=postgresql \
-e DB_NAME=product_change_db \
-e DB_PASSWORD=ProductUser2025! \
-e DB_PORT=5432 \
-e DB_USERNAME=product_change_user \
-e DDL_AUTO=update \
-e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
-e JWT_SECRET="nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==" \
-e KOS_API_KEY=dev-api-key \
-e KOS_BASE_URL=http://4.230.5.6:8084 \
-e KOS_CLIENT_ID=product-service-dev \
-e KOS_MOCK_ENABLED=true \
-e REDIS_DATABASE=2 \
-e REDIS_HOST=20.249.193.103 \
-e REDIS_PASSWORD=Redis2025Dev! \
-e REDIS_PORT=6379 \
-e SERVER_PORT=8083 \
-e SPRING_PROFILES_ACTIVE=dev \
-acrdigitalgarage01.azurecr.io/phonebill/product-service:latest
-```
-
-### 4.5 API Gateway 실행
-```bash
-SERVER_PORT=8080
-
-docker run -d --name api-gateway --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e BILL_SERVICE_URL=http://4.230.5.6:8082 \
-e CORS_ALLOWED_ORIGINS="http://localhost:3000,http://4.230.5.6:3000" \
-e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
-e JWT_SECRET="nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==" \
-e KOS_MOCK_URL=http://4.230.5.6:8084 \
-e PRODUCT_SERVICE_URL=http://4.230.5.6:8083 \
-e SERVER_PORT=8080 \
-e SPRING_PROFILES_ACTIVE=dev \
-e USER_SERVICE_URL=http://4.230.5.6:8081 \
-acrdigitalgarage01.azurecr.io/phonebill/api-gateway:latest
-```
-
-## 5. 컨테이너 실행 확인
-
-전체 서비스가 정상적으로 실행되었는지 확인:
-
-```bash
-# 모든 서비스 확인
-docker ps | grep -E "(api-gateway|user-service|bill-service|product-service|kos-mock)"
-
-# 개별 서비스 확인
-docker ps | grep api-gateway
-docker ps | grep user-service
-docker ps | grep bill-service
-docker ps | grep product-service
-docker ps | grep kos-mock
-```
-
-## 6. 서비스 접속 테스트
-
-각 서비스의 헬스체크 엔드포인트로 정상 동작을 확인:
-
-```bash
-# API Gateway
-curl http://4.230.5.6:8080/actuator/health
-
-# User Service  
-curl http://4.230.5.6:8081/actuator/health
-
-# Bill Service
-curl http://4.230.5.6:8082/actuator/health
-
-# Product Service
-curl http://4.230.5.6:8083/actuator/health
-
-# KOS Mock
-curl http://4.230.5.6:8084/actuator/health
-```
-
-## 7. 재배포 방법
-
-### 7.1 컨테이너 이미지 재생성 (로컬에서 수행)
-```bash
-# 이미지 재빌드
-/deploy-build-image-back
-```
-
-### 7.2 컨테이너 이미지 푸시 (로컬에서 수행)
-특정 서비스만 재배포하는 경우:
-```bash
-# 예: user-service 재배포
-docker tag user-service:latest acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
-docker push acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
-```
-
-### 7.3 컨테이너 재시작 (VM에서 수행)
-```bash
-# 1. 기존 컨테이너 중지
+docker stop api-gateway
+docker stop product-service
+docker stop bill-service
 docker stop user-service
-
-# 2. 컨테이너 이미지 삭제 (캐시 갱신을 위해)
-docker rmi acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
-
-# 3. 새 이미지로 컨테이너 재실행
-SERVER_PORT=8081
-
-docker run -d --name user-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
-e CORS_ALLOWED_ORIGINS="http://localhost:3000,http://4.230.5.6:3000" \
-e DB_HOST=20.249.70.6 \
-e DB_KIND=postgresql \
-e DB_NAME=phonebill_auth \
-e DB_PASSWORD=AuthUser2025! \
-e DB_PORT=5432 \
-e DB_USERNAME=auth_user \
-e DDL_AUTO=update \
-e JWT_ACCESS_TOKEN_VALIDITY=18000000 \
-e JWT_REFRESH_TOKEN_VALIDITY=86400000 \
-e JWT_SECRET="nwe5Yo9qaJ6FBD/Thl2/j6/SFAfNwUorAY1ZcWO2KI7uA4bmVLOCPxE9hYuUpRCOkgV2UF2DdHXtqHi3+BU/ecbz2zpHyf/720h48UbA3XOMYOX1sdM+dQ==" \
-e REDIS_DATABASE=0 \
-e REDIS_HOST=20.249.193.103 \
-e REDIS_PASSWORD=Redis2025Dev! \
-e REDIS_PORT=6379 \
-e SERVER_PORT=8081 \
-e SHOW_SQL=true \
-e SPRING_PROFILES_ACTIVE=dev \
-acrdigitalgarage01.azurecr.io/phonebill/user-service:latest
+docker stop kos-mock
 ```

-## 8. 전체 서비스 재시작 스크립트
-
-모든 서비스를 한번에 재시작하려면:
-
+### 전체 서비스 중지
 ```bash
-# 모든 컨테이너 중지
-docker stop api-gateway user-service bill-service product-service kos-mock
-
-# 모든 이미지 삭제
-docker rmi acrdigitalgarage01.azurecr.io/phonebill/api-gateway:latest
-docker rmi acrdigitalgarage01.azurecr.io/phonebill/user-service:latest  
-docker rmi acrdigitalgarage01.azurecr.io/phonebill/bill-service:latest
-docker rmi acrdigitalgarage01.azurecr.io/phonebill/product-service:latest
-docker rmi acrdigitalgarage01.azurecr.io/phonebill/kos-mock:latest
-
-# 컨테이너 재실행 (위의 4.1 ~ 4.5 단계 순서대로 실행)
+docker stop api-gateway product-service bill-service user-service kos-mock
 ```

-## 주의사항
+---

-1. **실행 순서**: KOS Mock → User Service → Bill Service → Product Service → API Gateway 순서로 실행하는 것을 권장합니다.
+## 재배포 방법

-2. **CORS 설정**: 프론트엔드에서 접근할 수 있도록 VM IP(4.230.5.6:3000)가 CORS_ALLOWED_ORIGINS에 포함되어 있습니다.
+### 1. 소스 수정 후 로컬에서 푸시
+```bash
+git add .
+git commit -m "수정 내용"
+git push
+```

-3. **로그 확인**: 컨테이너 로그는 `docker logs [컨테이너명]` 명령으로 확인할 수 있습니다.
+### 2. 소스 내려받기
+```bash
+cd ~/home/workspace/phonebill
+git pull
+```

-4. **네트워크**: 모든 서비스는 localhost로 서로 통신하도록 설정되어 있습니다.
+### 3. 컨테이너 이미지 재생성
+`deployment/container/build-image.md` 파일을 참조하여 이미지를 다시 빌드합니다.
+
+### 4. 이미지 푸시 (Docker Hub 사용 시)
+```bash
+docker tag api-gateway:latest docker.io/phonebill/api-gateway:latest
+docker push docker.io/phonebill/api-gateway:latest
+```
+
+### 5. 컨테이너 중지
+```bash
+docker stop api-gateway
+```
+
+### 6. 기존 이미지 삭제 (선택)
+```bash
+docker rmi api-gateway:latest
+```
+
+### 7. 컨테이너 재실행
+위의 "컨테이너 실행" 섹션의 명령어를 다시 실행합니다.
+
+---
+
+## 문제 해결
+
+### 1. 컨테이너가 시작되지 않는 경우
+```bash
+# 로그 확인
+docker logs api-gateway
+
+# 컨테이너 상태 확인
+docker ps -a | grep api-gateway
+```
+
+### 2. 서비스 간 통신 오류
+- `host.docker.internal`이 올바르게 설정되었는지 확인
+- 방화벽 설정 확인
+- 백킹 서비스(DB, Redis) 실행 상태 확인
+
+### 3. 포트 충돌
+```bash
+# 사용 중인 포트 확인
+lsof -i :8080
+```
+
+---
+
+## 작성일
+2025-11-27