From 81b75f0e2ccbcdbd7fa071c6a4d62f284c6e29ac Mon Sep 17 00:00:00 2001
From: AutonetSellCar Deploy <autonet@grantech.kr>
Date: Wed, 31 Dec 2025 10:55:36 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Git=20=EA=B8=B0=EB=B0=98=20=EB=B0=B0?=
 =?UTF-8?q?=ED=8F=AC=20=ED=95=84=EC=9A=94=EC=84=B1=20=EB=B0=8F=20carmodoo-?=
 =?UTF-8?q?agent=20=ED=99=98=EA=B2=BD=EB=B3=80=EC=88=98=20=EC=84=A4?=
 =?UTF-8?q?=EB=AA=85=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DEPLOYMENT_GUIDE.md | 139 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 132 insertions(+), 7 deletions(-)

diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md
index f3f2c51..8ebf872 100644
--- a/DEPLOYMENT_GUIDE.md
+++ b/DEPLOYMENT_GUIDE.md
@@ -278,8 +278,10 @@ services:
       - autonet-production-network
 
   carmodoo-agent:
-    build: ./carmodoo-agent
+    build: ./agent
     container_name: carmodoo-agent
+    volumes:
+      - ./agent/.env:/app/.env:ro
     networks:
       - autonet-production-network
 
@@ -408,7 +410,8 @@ docker compose -f docker-compose.production.yml up -d
 │   │   ├── requirements.txt      # psycopg2-binary 포함
 │   │   └── app/
 │   │       └── config.py         # URL 인코딩 적용
-│   ├── carmodoo-agent/
+│   ├── agent/
+│   │   └── .env                  # Carmodoo 로그인 정보
 │   └── docker-compose.production.yml
 │
 ├── releases/                     # 롤백용 백업
@@ -424,7 +427,7 @@ docker compose -f docker-compose.production.yml up -d
 
 ## 8. 환경변수 설정
 
-### 운영 서버 backend/.env 전체
+### 운영 서버 backend/.env
 
 ```env
 # Database (PostgreSQL)
@@ -463,9 +466,105 @@ VERIFICATION_CODE_EXPIRE_MINUTES=10
 EMAIL_VERIFICATION_REQUIRED=True
 ```
 
+### 운영 서버 agent/.env
+
+```env
+# Carmodoo 딜러 포탈 로그인 정보
+CARMODOO_USER_ID=01033315258
+CARMODOO_PASSWORD=alskfl@1122
+
+# Backend API 연결 (Docker 네트워크 내부)
+API_SERVER_URL=http://autonet-backend:8000/api
+```
+
+> ⚠️ **중요**: carmodoo-agent는 이 환경변수가 없으면 로그인 실패로 계속 재시작됩니다.
+
 ---
 
-## 9. 문제 해결
+## 9. Git 기반 배포가 필요한 이유
+
+### 9.1 문제 상황 (Git 미사용 시)
+
+```
+[서버4 - 로컬 개발]              [서버2 - 운영 서버]
+     소스코드 A                      소스코드 A
+         │                               │
+         │                          직접 수정 → 소스코드 B (예: 번역 수정)
+         │                               │
+         └────── docker build ───────────┘
+                      │
+                      ▼
+                소스코드 A로 덮어씀
+                (B 변경사항 사라짐!)
+```
+
+**원인**:
+- 서버2에서 직접 코드를 수정함
+- 서버4에서 `docker build`를 하면 서버4의 소스코드로 컨테이너가 다시 빌드됨
+- 서버2에서 수정한 내용이 서버4에는 없으므로 → **변경사항이 사라짐**
+
+### 9.2 해결 방법 (Git 기반 배포)
+
+```
+[서버4 - 로컬 개발]                        [서버2 - 운영 서버]
+     소스코드 수정
+         │
+    git commit
+         │
+    git push staging ────────────────→ Git Bare Repository
+                                                │
+                                          post-receive hook (자동)
+                                                │
+                                                ▼
+                                          소스코드 복사 + docker build
+                                                │
+                                                ▼
+                                          스테이징 컨테이너 실행
+                                                │
+                                          검증 후 deploy.sh promote
+                                                │
+                                                ▼
+                                          운영 컨테이너 실행
+```
+
+### 9.3 핵심 원칙
+
+| 이전 (문제) | 현재 (해결) |
+|------------|------------|
+| 서버2에서 직접 수정 | **서버4에서만 수정** |
+| 수정 후 바로 docker build | git commit → git push |
+| 변경 이력 없음 | Git으로 버전 관리 |
+| 롤백 불가 | `deploy.sh rollback`으로 롤백 가능 |
+
+### 9.4 올바른 배포 워크플로우
+
+```bash
+# 1. 서버4에서 코드 수정 (로컬 개발)
+code frontend/src/app/page.tsx
+
+# 2. 로컬 테스트
+npm run dev
+
+# 3. Git 커밋
+git add .
+git commit -m "fix: 번역 수정"
+
+# 4. 스테이징 배포 (자동 - post-receive hook)
+git push staging main
+
+# 5. 스테이징 검증
+# http://192.168.0.202:3001 (frontend)
+# http://192.168.0.202:8001/docs (backend)
+
+# 6. 운영 승격
+ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh promote"
+```
+
+> ⚠️ **중요**: 서버2에서 직접 코드를 수정하지 마세요! 모든 변경은 서버4에서 Git을 통해 배포해야 합니다.
+
+---
+
+## 10. 문제 해결
 
 ### PostgreSQL 연결 오류
 
@@ -514,9 +613,35 @@ docker compose -f docker-compose.production.yml build backend --no-cache
 NEXT_PUBLIC_API_URL=https://autonetsellcar.com
 ```
 
+### carmodoo-agent 계속 재시작
+
+```bash
+# 에러 확인
+docker logs carmodoo-agent --tail 20
+
+# 에러: User ID and password are required
+# 원인: agent/.env 파일 없음 또는 환경변수 미설정
+
+# 해결:
+# 1. .env 파일 생성
+cat > /opt/autonet/production/agent/.env << 'EOF'
+CARMODOO_USER_ID=01033315258
+CARMODOO_PASSWORD=alskfl@1122
+API_SERVER_URL=http://autonet-backend:8000/api
+EOF
+
+# 2. 컨테이너 재생성 (.env 마운트 적용)
+docker stop carmodoo-agent && docker rm carmodoo-agent
+docker run -d --name carmodoo-agent \
+  --restart unless-stopped \
+  --network autonet-production-network \
+  -v /opt/autonet/production/agent/.env:/app/.env:ro \
+  production-carmodoo-agent
+```
+
 ---
 
-## 10. 빠른 참조 명령어
+## 11. 빠른 참조 명령어
 
 ```
 ╔═══════════════════════════════════════════════════════════════════════════════╗
@@ -549,7 +674,7 @@ NEXT_PUBLIC_API_URL=https://autonetsellcar.com
 
 ---
 
-## 11. 체크리스트
+## 12. 체크리스트
 
 ### 최초 서버 설정
 
@@ -578,4 +703,4 @@ NEXT_PUBLIC_API_URL=https://autonetsellcar.com
 
 ---
 
-**최종 업데이트**: 2024-12-30
+**최종 업데이트**: 2024-12-31