백엔드 컨테이너 실행 가이드 작성

- deployment/container/run-container-guide.md 생성 - 4개 서비스(user, event, analytics, participation) 컨테이너 실행 방법 안내 - VM 접속, ACR 설정, 이미지 푸시, 컨테이너 실행, 재배포 절차 포함 - CORS 설정에 프론트엔드 주소(http://20.196.65.160:3000) 추가 - 실행정보: ACR(acrdigitalgarage01), VM(20.196.65.160)
2025-12-06 07:26:24 +00:00 · 2025-10-28 15:26:35 +09:00 · 2025-10-28 15:26:35 +09:00 · 0c718c67f6
commit 0c718c67f6
parent cf2689390d
2 changed files with 589 additions and 0 deletions
--- a/claude/run-container-guide-back.md
+++ b/claude/run-container-guide-back.md
@ -0,0 +1,187 @@
+# 백엔드 컨테이너 실행방법 가이드
+
+[요청사항]  
+- 백엔드 각 서비스들의 컨테이너 이미지를 컨테이너로 실행하는 가이드 작성  
+- 실제 컨테이너 실행은 하지 않음   
+- '[결과파일]'에 수행할 명령어를 포함하여 컨테이너 실행 가이드 생성    
+
+[작업순서]
+- 실행정보 확인   
+  프롬프트의 '[실행정보]'섹션에서 아래정보를 확인  
+  - {ACR명}: 컨테이너 레지스트리 이름 
+  - {VM.KEY파일}: VM 접속하는 Private Key파일 경로 
+  - {VM.USERID}: VM 접속하는 OS 유저명
+  - {VM.IP}: VM IP
+  예시)
+  ```
+  [실행정보]
+  - ACR명: acrdigitalgarage01
+  - VM
+    - KEY파일: ~/home/bastion-dg0500
+    - USERID: azureuser
+    - IP: 4.230.5.6
+  ``` 
+  
+- 시스템명과 서비스명 확인   
+  settings.gradle에서 확인.    
+  - 시스템명: rootProject.name 
+  - 서비스명: include 'common'하위의 include문 뒤의 값임 
+
+  예시) include 'common'하위의 4개가 서비스명임.  
+  ```
+  rootProject.name = 'tripgen'
+
+  include 'common'
+  include 'user-service'
+  include 'location-service'
+  include 'ai-service'
+  include 'trip-service'
+  ```  
+
+- VM 접속 방법 안내
+  - Linux/Mac은 기본 터미널을 실행하고 Window는 Window Terminal을 실행하도록 안내   
+  - 터미널에서 아래 명령으로 VM에 접속하도록 안내  
+    최초 한번 Private key파일의 모드를 변경.  
+    ```
+    chmod 400 {VM.KEY파일}
+    ``` 
+    
+    private key를 이용하여 접속.  
+    ``` 
+    ssh -i {VM.KEY파일} {VM.USERID}@{VM.IP}
+    ``` 
+  - 접속 후 docker login 방법 안내   
+    ```
+    docker login {ACR명}.azurecr.io -u {ID} -p {암호}
+    ```
+
+- Git Repository 클론 안내       
+  - workspace 디렉토리 생성 및 이동   
+    ```
+    mkdir -p ~/home/workspace 
+    cd ~/home/workspace
+    ```
+  - 소스 Clone 
+    ```
+    git clone {원격 Git Repository 주소}
+    ```   
+    예)
+    ```
+    git clone https://github.com/cna-bootcamp/phonebill.git 
+    ```
+  - 프로젝트 디렉토리로 이동  
+    ```
+    cd {시스템명}
+    ``` 
+
+- 어플리케이션 빌드 및 컨테이너 이미지 생성 방법 안내      
+  'deployment/container/build-image.md' 파일을 열어 가이드대로 수행하도록 안내    
+
+- 컨테이너 레지스트리 로그인 방법 안내     
+  아래 명령으로 {ACR명}의 인증정보를 구합니다.  
+  'username'이 ID이고 'passwords[0].value'가 암호임. 
+  ```
+  az acr credential show --name {ACR명}
+  ```
+
+  예시) ID=dg0200cr, 암호={암호}    
+  ```
+  $ az acr credential show --name dg0200cr 
+  {
+    "passwords": [
+      {
+        "name": "password",
+        "value": "{암호}"
+      },
+      {
+        "name": "password2",
+        "value": "{암호2}"
+      }
+    ],
+    "username": "dg0200cr"
+  }
+  ```
+  
+  아래와 같이 로그인 명령을 작성합니다.   
+  ```
+  docker login {ACR명}.azurecr.io -u {ID} -p {암호}
+  ```
+
+- 컨테이너 푸시 방법 안내   
+  Docker Tag 명령으로 이미지를 tag하는 명령을 작성합니다.   
+  ```
+  docker tag {서비스명}:latest {ACR명}.azurecr.io/{시스템명}/{서비스명}:latest 
+  ```
+  이미지 푸시 명령을 작성합니다.   
+  ```
+  docker push {ACR명}.azurecr.io/{시스템명}/{서비스명}:latest
+  ```
+
+- 컨테이너 실행 명령 생성    
+  - 환경변수 확인    
+    '{서비스명}/.run/{서비스명}.run.xml' 을 읽어 각 서비스의 환경변수 찾음.      
+    "env.map"의 각 entry의 key와 value가 환경변수임.   
+      
+    예제) SERVER_PORT=8081, DB_HOST=20.249.137.175가 환경변수임 
+    ```
+    <component name="ProjectRunConfigurationManager">
+      <configuration default="false" name="ai-service" type="GradleRunConfiguration" factoryName="Gradle">
+        <ExternalSystemSettings>
+          <option name="env">
+            <map>
+              <entry key="SERVER_PORT" value="8084" />
+              <entry key="DB_HOST" value="20.249.137.175" />
+    ```
+
+  - 아래 명령으로 컨테이너를 실행하는 명령을 생성합니다.    
+    - shell 파일을 만들지 말고 command로 수행하는 방법 안내.        
+    - 모든 환경변수에 대해 '-e' 파라미터로 환경변수값을 넘깁니다.  
+    - 중요) CORS 설정 환경변수에 프론트엔드 주소 추가   
+      - 'ALLOWED_ORIGINS' 포함된 환경변수가 CORS 설정 환경변수임.  
+      - 이 환경변수의 값에 'http://{VM.IP}:3000'번 추가  
+    
+    ```
+    SERVER_PORT={환경변수의 SERVER_PORT값}
+
+    docker run -d --name {서비스명} --rm -p ${SERVER_PORT}:${SERVER_PORT} \
+    -e {환경변수 KEY}={환경변수 VALUE} 
+    {ACR명}.azurecr.io/{시스템명}/{서비스명}:latest
+    ```
+
+- 실행된 컨테이너 확인 방법 작성    
+  아래 명령으로 모든 서비스의 컨테이너가 실행 되었는지 확인하는 방법을 안내.     
+  ```
+  docker ps | grep {서비스명}
+  ```
+- 재배포 방법 작성 
+  - 로컬에서 수정된 소스 푸시 
+  - VM 접속 
+  - 디렉토리 이동 및 소스 내려받기
+    ```
+    cd ~/home/workspace/{시스템명}
+    ```
+
+    ```
+    git pull
+    ```
+  - 컨테이너 이미지 재생성 
+    'deployment/container/build-image.md' 파일을 열어 가이드대로 수행
+
+  - 컨테이너 이미지 푸시  
+    ```
+    docker tag {서비스명}:latest {ACR명}.azurecr.io/{시스템명}/{서비스명}:latest
+    docker push {ACR명}.azurecr.io/{시스템명}/{서비스명}:latest
+    ```     
+  - 컨테이너 중지 
+    ```
+    docker stop {서비스명}
+    ```
+  - 컨테이너 이미지 삭제  
+    ```
+    docker rmi {ACR명}.azurecr.io/{시스템명}/{서비스명}:latest
+    ``` 
+  - 컨테이너 재실행 
+  
+[결과파일]
+deployment/container/run-container-guide.md
+  
--- a/deployment/container/run-container-guide.md
+++ b/deployment/container/run-container-guide.md
@ -0,0 +1,402 @@
+# 백엔드 컨테이너 실행 가이드
+
+## 목차
+1. [개요](#개요)
+2. [VM 접속](#vm-접속)
+3. [Git Repository 클론](#git-repository-클론)
+4. [컨테이너 이미지 빌드](#컨테이너-이미지-빌드)
+5. [컨테이너 레지스트리 설정](#컨테이너-레지스트리-설정)
+6. [컨테이너 이미지 푸시](#컨테이너-이미지-푸시)
+7. [컨테이너 실행](#컨테이너-실행)
+8. [컨테이너 확인](#컨테이너-확인)
+9. [재배포](#재배포)
+
+---
+
+## 개요
+
+본 가이드는 **kt-event-marketing** 시스템의 백엔드 마이크로서비스들을 Docker 컨테이너로 실행하는 방법을 안내합니다.
+
+### 시스템 정보
+- **시스템명**: kt-event-marketing
+- **ACR명**: acrdigitalgarage01
+- **서비스 목록**:
+  - user-service (포트: 8081)
+  - event-service (포트: 8080)
+  - analytics-service (포트: 8086)
+  - participation-service (포트: 8084)
+
+### VM 정보
+- **IP**: 20.196.65.160
+- **사용자 ID**: P82265804@ktds.co.kr
+- **SSH Key 파일**: ~/home/bastion-dg0505
+
+---
+
+## VM 접속
+
+### 1단계: 터미널 실행
+- **Linux/Mac**: 기본 터미널 실행
+- **Windows**: Windows Terminal 실행
+
+### 2단계: SSH Key 파일 권한 설정 (최초 1회)
+```bash
+chmod 400 ~/home/bastion-dg0505
+```
+
+### 3단계: VM 접속
+```bash
+ssh -i ~/home/bastion-dg0505 P82265804@ktds.co.kr@20.196.65.160
+```
+
+---
+
+## Git Repository 클론
+
+### 1단계: workspace 디렉토리 생성 및 이동
+```bash
+mkdir -p ~/home/workspace
+cd ~/home/workspace
+```
+
+### 2단계: 소스 클론
+```bash
+git clone https://github.com/ktds-dg0501/kt-event-marketing.git
+```
+
+### 3단계: 프로젝트 디렉토리로 이동
+```bash
+cd kt-event-marketing
+```
+
+---
+
+## 컨테이너 이미지 빌드
+
+### 이미지 빌드 가이드 참조
+프로젝트 내 빌드 가이드를 참조하여 컨테이너 이미지를 생성합니다:
+
+```bash
+# 빌드 가이드 파일 열기
+cat deployment/container/build-image.md
+```
+
+빌드 가이드에 따라 각 서비스의 컨테이너 이미지를 생성하세요.
+
+---
+
+## 컨테이너 레지스트리 설정
+
+### 1단계: ACR 인증 정보 확인
+Azure CLI를 사용하여 ACR 인증 정보를 확인합니다:
+
+```bash
+az acr credential show --name acrdigitalgarage01
+```
+
+**출력 예시**:
+```json
+{
+  "passwords": [
+    {
+      "name": "password",
+      "value": "{암호}"
+    },
+    {
+      "name": "password2",
+      "value": "{암호2}"
+    }
+  ],
+  "username": "acrdigitalgarage01"
+}
+```
+
+- **ID**: `username` 값 (예: acrdigitalgarage01)
+- **암호**: `passwords[0].value` 값
+
+### 2단계: Docker 로그인
+```bash
+docker login acrdigitalgarage01.azurecr.io -u {ID} -p {암호}
+```
+
+**예시**:
+```bash
+docker login acrdigitalgarage01.azurecr.io -u acrdigitalgarage01 -p mySecretPassword123
+```
+
+---
+
+## 컨테이너 이미지 푸시
+
+각 서비스의 이미지를 ACR에 푸시합니다.
+
+### user-service
+```bash
+docker tag user-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:latest
+docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:latest
+```
+
+### event-service
+```bash
+docker tag event-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
+docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
+```
+
+### analytics-service
+```bash
+docker tag analytics-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
+docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
+```
+
+### participation-service
+```bash
+docker tag participation-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest
+docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest
+```
+
+---
+
+## 컨테이너 실행
+
+각 서비스를 Docker 컨테이너로 실행합니다.
+
+### user-service 실행
+```bash
+SERVER_PORT=8081
+
+docker run -d --name user-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
+  -e SERVER_PORT=8081 \
+  -e DB_URL=jdbc:postgresql://20.249.125.115:5432/userdb \
+  -e DB_DRIVER=org.postgresql.Driver \
+  -e DB_HOST=20.249.125.115 \
+  -e DB_PORT=5432 \
+  -e DB_NAME=userdb \
+  -e DB_USERNAME=eventuser \
+  -e DB_PASSWORD=Hi5Jessica! \
+  -e DB_KIND=postgresql \
+  -e DDL_AUTO=update \
+  -e SHOW_SQL=true \
+  -e JPA_DIALECT=org.hibernate.dialect.PostgreSQLDialect \
+  -e H2_CONSOLE_ENABLED=false \
+  -e REDIS_ENABLED=true \
+  -e REDIS_HOST=20.214.210.71 \
+  -e REDIS_PORT=6379 \
+  -e REDIS_PASSWORD=Hi5Jessica! \
+  -e REDIS_DATABASE=0 \
+  -e EXCLUDE_REDIS="" \
+  -e KAFKA_BOOTSTRAP_SERVERS=4.230.50.63:9092 \
+  -e KAFKA_CONSUMER_GROUP=user-service-consumers \
+  -e EXCLUDE_KAFKA="" \
+  -e JWT_SECRET=kt-event-marketing-secret-key-for-development-only-please-change-in-production \
+  -e JWT_ACCESS_TOKEN_VALIDITY=604800000 \
+  -e CORS_ALLOWED_ORIGINS="http://localhost:*,http://20.196.65.160:3000" \
+  -e LOG_LEVEL_APP=DEBUG \
+  -e LOG_LEVEL_WEB=INFO \
+  -e LOG_LEVEL_SQL=DEBUG \
+  -e LOG_LEVEL_SQL_TYPE=TRACE \
+  -e LOG_FILE_PATH=logs/user-service.log \
+  acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:latest
+```
+
+### event-service 실행
+```bash
+SERVER_PORT=8080
+
+docker run -d --name event-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
+  -e SERVER_PORT=8080 \
+  -e DB_HOST=20.249.177.232 \
+  -e DB_PORT=5432 \
+  -e DB_NAME=eventdb \
+  -e DB_USERNAME=eventuser \
+  -e DB_PASSWORD=Hi5Jessica! \
+  -e DDL_AUTO=update \
+  -e REDIS_HOST=20.214.210.71 \
+  -e REDIS_PORT=6379 \
+  -e REDIS_PASSWORD=Hi5Jessica! \
+  -e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
+  -e CONTENT_SERVICE_URL=http://localhost:8082 \
+  -e DISTRIBUTION_SERVICE_URL=http://localhost:8084 \
+  -e JWT_SECRET=kt-event-marketing-secret-key-for-development-only-please-change-in-production \
+  -e LOG_LEVEL=DEBUG \
+  -e SQL_LOG_LEVEL=DEBUG \
+  acrdigitalgarage01.azurecr.io/kt-event-marketing/event-service:latest
+```
+
+### analytics-service 실행
+```bash
+SERVER_PORT=8086
+
+docker run -d --name analytics-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
+  -e DB_KIND=postgresql \
+  -e DB_HOST=4.230.49.9 \
+  -e DB_PORT=5432 \
+  -e DB_NAME=analyticdb \
+  -e DB_USERNAME=eventuser \
+  -e DB_PASSWORD=Hi5Jessica! \
+  -e DDL_AUTO=update \
+  -e SHOW_SQL=true \
+  -e REDIS_HOST=20.214.210.71 \
+  -e REDIS_PORT=6379 \
+  -e REDIS_PASSWORD=Hi5Jessica! \
+  -e REDIS_DATABASE=5 \
+  -e KAFKA_ENABLED=true \
+  -e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
+  -e KAFKA_CONSUMER_GROUP_ID=analytics-service-consumers \
+  -e SAMPLE_DATA_ENABLED=true \
+  -e SERVER_PORT=8086 \
+  -e JWT_SECRET=dev-jwt-secret-key-for-development-only-kt-event-marketing \
+  -e JWT_ACCESS_TOKEN_VALIDITY=1800 \
+  -e JWT_REFRESH_TOKEN_VALIDITY=86400 \
+  -e CORS_ALLOWED_ORIGINS="http://localhost:*,http://20.196.65.160:3000" \
+  -e LOG_FILE=logs/analytics-service.log \
+  -e LOG_LEVEL_APP=DEBUG \
+  -e LOG_LEVEL_WEB=INFO \
+  -e LOG_LEVEL_SQL=DEBUG \
+  -e LOG_LEVEL_SQL_TYPE=TRACE \
+  acrdigitalgarage01.azurecr.io/kt-event-marketing/analytics-service:latest
+```
+
+### participation-service 실행
+```bash
+SERVER_PORT=8084
+
+docker run -d --name participation-service --rm -p ${SERVER_PORT}:${SERVER_PORT} \
+  -e DB_HOST=4.230.72.147 \
+  -e DB_NAME=participationdb \
+  -e DB_PASSWORD=Hi5Jessica! \
+  -e DB_PORT=5432 \
+  -e DB_USERNAME=eventuser \
+  -e DDL_AUTO=update \
+  -e JWT_EXPIRATION=86400000 \
+  -e JWT_SECRET=kt-event-marketing-secret-key-for-development-only-change-in-production \
+  -e KAFKA_BOOTSTRAP_SERVERS=20.249.182.13:9095,4.217.131.59:9095 \
+  -e LOG_FILE=logs/participation-service.log \
+  -e LOG_LEVEL=INFO \
+  -e REDIS_HOST=20.214.210.71 \
+  -e REDIS_PASSWORD=Hi5Jessica! \
+  -e REDIS_PORT=6379 \
+  -e SERVER_PORT=8084 \
+  -e SHOW_SQL=true \
+  acrdigitalgarage01.azurecr.io/kt-event-marketing/participation-service:latest
+```
+
+---
+
+## 컨테이너 확인
+
+모든 서비스가 정상적으로 실행되었는지 확인합니다.
+
+### 전체 서비스 확인
+```bash
+docker ps
+```
+
+### 개별 서비스 확인
+```bash
+docker ps | grep user-service
+docker ps | grep event-service
+docker ps | grep analytics-service
+docker ps | grep participation-service
+```
+
+### 서비스 로그 확인
+```bash
+docker logs user-service
+docker logs event-service
+docker logs analytics-service
+docker logs participation-service
+```
+
+---
+
+## 재배포
+
+소스 코드 수정 후 재배포 방법입니다.
+
+### 1단계: 로컬에서 수정된 소스 푸시
+로컬 개발 환경에서 소스 수정 후 Git에 푸시합니다.
+
+### 2단계: VM 접속
+```bash
+ssh -i ~/home/bastion-dg0505 P82265804@ktds.co.kr@20.196.65.160
+```
+
+### 3단계: 디렉토리 이동 및 소스 내려받기
+```bash
+cd ~/home/workspace/kt-event-marketing
+git pull
+```
+
+### 4단계: 컨테이너 이미지 재생성
+빌드 가이드에 따라 이미지를 재생성합니다:
+```bash
+cat deployment/container/build-image.md
+```
+
+### 5단계: 컨테이너 이미지 푸시 (예: user-service)
+```bash
+docker tag user-service:latest acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:latest
+docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:latest
+```
+
+### 6단계: 기존 컨테이너 중지
+```bash
+docker stop user-service
+```
+
+### 7단계: 컨테이너 이미지 삭제
+```bash
+docker rmi acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:latest
+```
+
+### 8단계: 컨테이너 재실행
+위 [컨테이너 실행](#컨테이너-실행) 섹션의 명령을 다시 실행합니다.
+
+---
+
+## 참고 사항
+
+### CORS 설정
+- 프론트엔드 접근을 위해 `CORS_ALLOWED_ORIGINS` 환경변수에 `http://20.196.65.160:3000`이 추가되었습니다.
+- 필요에 따라 추가 도메인을 콤마(,)로 구분하여 추가할 수 있습니다.
+
+### 포트 매핑
+- user-service: 8081
+- event-service: 8080
+- analytics-service: 8086
+- participation-service: 8084
+
+### 환경변수 보안
+- 본 가이드는 개발 환경용입니다.
+- 운영 환경에서는 비밀번호, JWT 시크릿 등을 환경변수 파일이나 Secret 관리 시스템을 통해 관리해야 합니다.
+
+### Docker 네트워크
+- 현재는 호스트 네트워크 모드로 실행됩니다.
+- 서비스 간 통신이 필요한 경우 Docker 네트워크를 생성하여 사용하는 것을 권장합니다.
+
+---
+
+## 문제 해결
+
+### 컨테이너가 시작되지 않는 경우
+```bash
+docker logs {서비스명}
+```
+
+### 포트가 이미 사용 중인 경우
+```bash
+# 포트 사용 프로세스 확인
+sudo netstat -tulpn | grep {포트번호}
+
+# 기존 컨테이너 중지
+docker stop {서비스명}
+```
+
+### 이미지 다운로드 실패
+```bash
+# Docker 로그인 재시도
+docker login acrdigitalgarage01.azurecr.io -u {ID} -p {암호}
+
+# 이미지 pull 재시도
+docker pull acrdigitalgarage01.azurecr.io/kt-event-marketing/{서비스명}:latest
+```