From 2cbec4359022248831ec5d3c8eadae39b0b996c9 Mon Sep 17 00:00:00 2001
From: AutonetSellCar Deploy <autonet@grantech.kr>
Date: Mon, 5 Jan 2026 23:11:36 +0900
Subject: [PATCH] docs: Add staging deployment warning to prevent volume mount
 errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add rule #5: Never use manual docker run for staging deployment
- Document 2025-01-05 incident where wrong volume mount caused missing images
- Add correct docker-compose commands for staging deployment

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index b7f48bf..a49d880 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -89,6 +89,34 @@ ssh server3 "docker ps | grep nextcloud"
 2. **DB_NAME 직접 타이핑 금지** - 반드시 `autonet` 복사/붙여넣기
 3. **`.env` 파일 덮어쓰기 금지** - 서버의 기존 `.env` 보존
 4. **`/home/damon/mongolcar/data/uploads` 사용 금지** - 비어있는 잘못된 경로
+5. **스테이징 배포 시 수동 `docker run` 금지** - 반드시 `docker compose` 사용! (아래 참고)
+
+### ⚠️ 스테이징 배포 주의사항 (2025-01-05 사고 사례)
+
+**문제**: 수동 `docker run`으로 스테이징 배포 시 볼륨 마운트 경로를 잘못 지정하여 이미지가 사라짐
+
+**원인**: `docker-compose.staging.yml`은 production uploads를 마운트하지만, 수동 명령어에서 staging uploads를 마운트함
+```yaml
+# docker-compose.staging.yml (올바른 설정)
+volumes:
+  - /opt/autonet/production/backend/uploads:/app/uploads  # production 폴더 공유!
+```
+
+**올바른 스테이징 배포 방법**:
+```bash
+# 반드시 docker-compose 사용!
+ssh server2 "cd /opt/autonet/staging && docker compose -f docker-compose.staging.yml up -d --build"
+
+# 개별 서비스만 재시작
+ssh server2 "cd /opt/autonet/staging && docker compose -f docker-compose.staging.yml up -d --build backend-staging"
+ssh server2 "cd /opt/autonet/staging && docker compose -f docker-compose.staging.yml up -d --build frontend-staging"
+```
+
+**절대 하지 말 것**:
+```bash
+# ❌ 이렇게 하면 안됨! 볼륨 경로가 docker-compose와 달라짐
+docker run -v /opt/autonet/staging/backend/uploads:/app/uploads ...
+```
 
 ## ✅ 배포 전 필수 검증 명령어