From 28a1302caeed22ea29f4cb2a450f715830e2acd3 Mon Sep 17 00:00:00 2001
From: Hyungi Ahn <hyungiahn@Hyungiui-MacBookPro.local>
Date: Fri, 1 Aug 2025 13:46:37 +0900
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20RULES.md=20=EC=97=85=EB=8D=B0?=
 =?UTF-8?q?=EC=9D=B4=ED=8A=B8:=20Docker=20=ED=99=98=EA=B2=BD=20=EA=B5=AC?=
 =?UTF-8?q?=EC=84=B1=20=EB=B0=8F=20=ED=8A=B8=EB=9F=AC=EB=B8=94=EC=8A=88?=
 =?UTF-8?q?=ED=8C=85=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Docker 컨테이너 구성 및 실행 방법 명시
- 해결된 주요 문제들 문서화:
  * 프론트엔드 API 연결 오류 (10080 포트 문제)
  * 백엔드 데이터베이스 연결 실패 (localhost vs postgres)
  * 환경별 설정 관리 개선
- 실행 전 체크리스트 제공으로 향후 헷갈림 방지
---
 RULES.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 83 insertions(+), 3 deletions(-)

diff --git a/RULES.md b/RULES.md
index 554719a..317ff15 100644
--- a/RULES.md
+++ b/RULES.md
@@ -6,9 +6,12 @@
 
 ## 🛠️ **기술 스택**
 ```
-Frontend: React.js + Material-UI + Vite + React Router DOM
-Backend: FastAPI + SQLAlchemy + Python
+Frontend: React.js + Material-UI + Vite + React Router DOM + Nginx
+Backend: FastAPI + SQLAlchemy + Python + Uvicorn
 Database: PostgreSQL (운영 및 개발)
+캐시: Redis
+관리도구: pgAdmin4
+컨테이너: Docker + Docker Compose
 기타: Axios, XLSX (SheetJS), file-saver
 ```
 
@@ -28,6 +31,37 @@ TK-MP-Project/
 └── database/             # DB 스키마/시드
 ```
 
+## 🐳 **Docker 실행 환경** 
+### 컨테이너 구성
+- **tk-mp-frontend**: React + Nginx (포트: 3000)
+- **tk-mp-backend**: FastAPI + Uvicorn (포트: 8000) 
+- **tk-mp-postgres**: PostgreSQL (포트: 5432)
+- **tk-mp-redis**: Redis (포트: 6379)
+- **tk-mp-pgadmin**: pgAdmin4 (포트: 5050)
+
+### 실행 방법
+```bash
+# 개발 환경
+./scripts/dev.sh
+# 또는
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
+
+# 프로덕션 환경  
+./scripts/prod.sh
+# 또는
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+# 기본 환경
+docker-compose up -d
+```
+
+### 중요한 설정 사항
+- **API URL 설정**: 
+  - 개발환경: `http://localhost:8000` (직접 접근)
+  - 프로덕션: `/api` (nginx 프록시를 통한 상대경로)
+- **데이터베이스 연결**: `postgres:5432` (컨테이너명 사용, localhost 아님!)
+- **환경변수**: `VITE_API_URL`로 API URL 오버라이드 가능
+
 ## 🗄️ **핵심 데이터베이스 스키마**
 ```sql
 -- 핵심 테이블들
@@ -203,4 +237,50 @@ const purchaseQuantity = Math.ceil(bomQuantity / 5) * 5;
 - 작업 상태는 'in-progress'와 'complete'를 명확히 표시
 
 ---
-**마지막 업데이트**: 2024-12-20 
\ No newline at end of file
+## 🚨 **Docker 실행 관련 트러블슈팅**
+
+### 해결된 주요 문제들 (2025.08.01)
+
+1. **프론트엔드 API 연결 오류**
+   - **문제**: 빌드된 프론트엔드가 10080 포트로 API 요청
+   - **원인**: 환경변수 설정 누락으로 하드코딩된 포트 사용
+   - **해결**: 
+     ```bash
+     # Dockerfile에서 빌드 시 환경변수 주입
+     ARG VITE_API_URL=http://localhost:8000
+     ENV VITE_API_URL=$VITE_API_URL
+     
+     # docker-compose.yml에서 환경변수 설정
+     environment:
+       - VITE_API_URL=${VITE_API_URL:-/api}
+     ```
+
+2. **백엔드 데이터베이스 연결 실패**
+   - **문제**: `psycopg2.OperationalError` - localhost:5432 연결 거부
+   - **원인**: 백엔드가 localhost로 DB 접근 시도 (Docker 컨테이너 내에서는 불가)
+   - **해결**:
+     ```python
+     # backend/app/database.py 수정
+     DATABASE_URL = os.getenv(
+         "DATABASE_URL", 
+         "postgresql://tkmp_user:tkmp_password_2025@postgres:5432/tk_mp_bom"  # localhost → postgres
+     )
+     ```
+
+3. **환경별 설정 관리 개선**
+   - **문제**: 개발/프로덕션 환경 구분 없이 하드코딩
+   - **해결**: docker-compose 파일 분리
+     ```bash
+     docker-compose.yml          # 기본 설정
+     docker-compose.dev.yml      # 개발 환경 오버라이드  
+     docker-compose.prod.yml     # 프로덕션 환경 오버라이드
+     ```
+
+### 실행 전 체크리스트
+- [ ] Docker 및 Docker Compose 설치 확인
+- [ ] 모든 컨테이너 정상 실행 확인: `docker-compose ps`
+- [ ] 백엔드 API 문서 접근 가능: http://localhost:8000/docs
+- [ ] 프론트엔드 로딩 확인: http://localhost:3000
+- [ ] 데이터베이스 연결 확인: pgAdmin (http://localhost:5050)
+
+**마지막 업데이트**: 2025-08-01 (Docker 환경 구성 완료) 
\ No newline at end of file