📝 RULES.md 업데이트: Docker 환경 구성 및 트러블슈팅 가이드 추가

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

RULES.md

@@ -6,9 +6,12 @@
 
 ## 🛠️ **기술 스택**
 ```
-Frontend: React.js + Material-UI + Vite + React Router DOM
+Frontend: React.js + Material-UI + Vite + React Router DOM + Nginx
-Backend: FastAPI + SQLAlchemy + Python
+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 
+## 🚨 **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 환경 구성 완료) 

backend/Dockerfile

@@ -0,0 +1,28 @@
+# Python 3.9 베이스 이미지 사용
+FROM python:3.9-slim
+
+# 작업 디렉토리 설정
+WORKDIR /app
+
+# 시스템 패키지 업데이트 및 필요한 패키지 설치
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# requirements.txt 복사 및 의존성 설치
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 애플리케이션 코드 복사
+COPY . .
+
+# 포트 8000 노출
+EXPOSE 8000
+
+# 환경변수 설정
+ENV PYTHONPATH=/app
+
+# 서버 실행
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/app/database.py

@@ -3,8 +3,11 @@ from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import sessionmaker
 import os
 
-# 데이터베이스 URL
+# 데이터베이스 URL (환경변수에서 읽거나 기본값 사용)
-DATABASE_URL = "postgresql://tkmp_user:tkmp_password_2025@localhost:5432/tk_mp_bom"
+DATABASE_URL = os.getenv(
+    "DATABASE_URL", 
+    "postgresql://tkmp_user:tkmp_password_2025@postgres:5432/tk_mp_bom"
+)
 
 # SQLAlchemy 엔진 생성
 engine = create_engine(DATABASE_URL)

docker-compose.dev.yml

@@ -0,0 +1,26 @@
+version: '3.8'
+
+# 개발 환경용 오버라이드
+services:
+  frontend:
+    environment:
+      - VITE_API_URL=http://localhost:8000
+    build:
+      args:
+        - VITE_API_URL=http://localhost:8000
+
+  backend:
+    volumes:
+      - ./backend:/app  # 개발 시 코드 변경 실시간 반영
+    environment:
+      - DEBUG=True
+      - RELOAD=True
+
+  # 개발용 포트 매핑
+  postgres:
+    ports:
+      - "5432:5432"
+
+  redis:
+    ports:
+      - "6379:6379"

docker-compose.prod.yml

@@ -0,0 +1,46 @@
+version: '3.8'
+
+# 프로덕션 환경용 오버라이드
+services:
+  frontend:
+    environment:
+      - VITE_API_URL=/api
+    build:
+      args:
+        - VITE_API_URL=/api
+    # 포트를 외부에 노출하지 않음 (리버스 프록시 사용)
+    ports: []
+
+  backend:
+    environment:
+      - DEBUG=False
+      - RELOAD=False
+    # 포트를 외부에 노출하지 않음
+    ports: []
+
+  # 프로덕션용 리버스 프록시 (예: Nginx)
+  nginx:
+    image: nginx:alpine
+    container_name: tk-mp-nginx
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
+      - ./nginx/ssl:/etc/nginx/ssl  # SSL 인증서
+    depends_on:
+      - frontend
+      - backend
+    networks:
+      - tk-mp-network
+
+  # 데이터베이스 접근 제한
+  postgres:
+    ports: []  # 외부 접근 차단
+
+  redis:
+    ports: []  # 외부 접근 차단
+
+  pgadmin:
+    ports: []  # 외부 접근 차단 (필요시 SSH 터널링)

docker-compose.yml

@@ -49,6 +49,44 @@ services:
     networks:
       - tk-mp-network
 
+  # 백엔드 FastAPI 서비스
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: tk-mp-backend
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql://tkmp_user:tkmp_password_2025@postgres:5432/tk_mp_bom
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      - postgres
+      - redis
+    networks:
+      - tk-mp-network
+    volumes:
+      - ./backend/uploads:/app/uploads
+
+  # 프론트엔드 Nginx 서비스
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+      args:
+        - VITE_API_URL=${VITE_API_URL:-/api}
+    container_name: tk-mp-frontend
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - VITE_API_URL=${VITE_API_URL:-/api}
+    depends_on:
+      - backend
+    networks:
+      - tk-mp-network
+
 volumes:
   postgres_data:
     driver: local

frontend/Dockerfile

@@ -0,0 +1,36 @@
+# Node.js 18 베이스 이미지 사용
+FROM node:18-alpine
+
+# 작업 디렉토리 설정
+WORKDIR /app
+
+# 빌드 인자 받기
+ARG VITE_API_URL=http://localhost:8000
+ENV VITE_API_URL=$VITE_API_URL
+
+# package.json과 package-lock.json 복사
+COPY package*.json ./
+
+# 의존성 설치 (플랫폼별 바이너리 다운로드)
+RUN npm ci --force
+
+# 소스 코드 복사 (node_modules 제외)
+COPY . .
+
+# Vite 빌드
+RUN npm run build
+
+# Nginx 이미지로 멀티스테이지 빌드
+FROM nginx:alpine
+
+# 빌드된 파일을 nginx로 복사
+COPY --from=0 /app/dist /usr/share/nginx/html
+
+# nginx 설정 파일 복사 (필요시)
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+# 포트 3000 노출
+EXPOSE 3000
+
+# nginx 실행
+CMD ["nginx", "-g", "daemon off;"]

frontend/nginx.conf

@@ -0,0 +1,26 @@
+server {
+    listen 3000;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html index.htm;
+
+    # SPA를 위한 설정 (React Router 등)
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API 프록시 설정
+    location /api/ {
+        proxy_pass http://tk-mp-backend:8000/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # 정적 파일 캐싱
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}

frontend/src/api.js

@@ -1,8 +1,9 @@
 import axios from 'axios';
 
 // 환경변수에서 API URL을 읽음 (Vite 기준)
+// 프로덕션에서는 nginx 프록시를 통해 /api 경로 사용
 const API_BASE_URL = import.meta.env.VITE_API_URL || 
-  (import.meta.env.DEV ? 'http://localhost:8000' : 'http://localhost:8000');
+  (import.meta.env.DEV ? 'http://localhost:8000' : '/api');
 
 console.log('API Base URL:', API_BASE_URL);
 console.log('Environment:', import.meta.env.MODE);

scripts/dev.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# 개발 환경 실행 스크립트
+
+echo "🚀 TK-MP 프로젝트 개발 환경 시작..."
+
+# 기존 컨테이너 정리
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml down
+
+# 개발 환경으로 빌드 및 실행
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d
+
+echo "✅ 개발 환경이 실행되었습니다!"
+echo "📱 프론트엔드: http://localhost:3000"
+echo "🔧 백엔드 API: http://localhost:8000"
+echo "📚 API 문서: http://localhost:8000/docs"
+echo "🗄️ pgAdmin: http://localhost:5050"
+
+# 로그 출력
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml logs -f

scripts/prod.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# 프로덕션 환경 실행 스크립트
+
+echo "🚀 TK-MP 프로젝트 프로덕션 환경 시작..."
+
+# 기존 컨테이너 정리
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml down
+
+# 프로덕션 환경으로 빌드 및 실행
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up --build -d
+
+echo "✅ 프로덕션 환경이 실행되었습니다!"
+echo "🌐 애플리케이션: http://localhost (또는 도메인)"
+echo "🔒 HTTPS: https://localhost (SSL 설정 시)"
+
+# 상태 확인
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml ps