phonebill/deployment/container/run-container-guide.md

백엔드 컨테이너 실행 가이드 (로컬 환경)

개요

본 문서는 phonebill 프로젝트의 백엔드 마이크로서비스들을 로컬 환경에서 Docker 컨테이너로 실행하는 방법을 안내합니다.

실행 정보

항목	값
Image Registry	docker.io
시스템명	phonebill
실행 환경	로컬 (localhost)

대상 서비스

서비스명	포트	설명
kos-mock	8084	KOS 목업 서비스
user-service	8081	사용자 인증/관리 서비스
bill-service	8082	요금 조회 서비스
product-service	8083	상품 변경 서비스
api-gateway	8080	API Gateway

사전 준비 사항

1. Docker 설치 확인

docker --version

2. 백킹 서비스 실행 확인

컨테이너 실행 전 아래 백킹 서비스가 실행 중이어야 합니다:

• PostgreSQL (auth-db: 15432, bill-inquiry-db: 25432, product-change-db: 35432)
• Redis (16379)

백킹 서비스 실행 상태 확인:

docker ps | grep -E "postgres|redis"

어플리케이션 빌드 및 컨테이너 이미지 생성

deployment/container/build-image.md 파일을 참조하여 이미지를 빌드합니다.

# Gradle 빌드
./gradlew clean build -x test

# 이미지 빌드 예시 (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 .

Docker Hub 로그인 (선택)

이미지를 Docker Hub에 푸시하려면 로그인이 필요합니다:

docker login docker.io -u {Docker Hub ID} -p {암호}

이미지 태그 및 푸시 (선택)

Docker Hub에 이미지를 푸시하는 경우:

# 태그
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 실행

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 실행

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 실행

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 실행

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 실행

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

---

실행 확인

컨테이너 실행 상태 확인

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

서비스 헬스체크

# API Gateway
curl http://localhost:8080/actuator/health

# User Service
curl http://localhost:8081/actuator/health

# Bill Service
curl http://localhost:8082/actuator/health

# Product Service
curl http://localhost:8083/actuator/health

# KOS Mock
curl http://localhost:8084/actuator/health

로그 확인

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

---

컨테이너 중지

개별 서비스 중지

docker stop api-gateway
docker stop product-service
docker stop bill-service
docker stop user-service
docker stop kos-mock

전체 서비스 중지

docker stop api-gateway product-service bill-service user-service kos-mock

---

재배포 방법

1. 소스 수정 후 로컬에서 푸시

git add .
git commit -m "수정 내용"
git push

2. 소스 내려받기

cd ~/home/workspace/phonebill
git pull

3. 컨테이너 이미지 재생성

deployment/container/build-image.md 파일을 참조하여 이미지를 다시 빌드합니다.

4. 이미지 푸시 (Docker Hub 사용 시)

docker tag api-gateway:latest docker.io/phonebill/api-gateway:latest
docker push docker.io/phonebill/api-gateway:latest

5. 컨테이너 중지

docker stop api-gateway

6. 기존 이미지 삭제 (선택)

docker rmi api-gateway:latest

7. 컨테이너 재실행

위의 "컨테이너 실행" 섹션의 명령어를 다시 실행합니다.

---

문제 해결

1. 컨테이너가 시작되지 않는 경우

# 로그 확인
docker logs api-gateway

# 컨테이너 상태 확인
docker ps -a | grep api-gateway

2. 서비스 간 통신 오류

• host.docker.internal이 올바르게 설정되었는지 확인
• 방화벽 설정 확인
• 백킹 서비스(DB, Redis) 실행 상태 확인

3. 포트 충돌

# 사용 중인 포트 확인
lsof -i :8080

---

작성일

2025-11-27