goldenChart/frontend_golden/ENVIRONMENT_SETUP.md

프론트엔드 환경 설정 가이드

📋 환경별 설정

1. 로컬 개발 환경 (Development)

실행 방법:

npm start
# 또는 Windows에서
npm run start:win

접속 URL:

• 프론트엔드: http://localhost:3100

자동 연결되는 서비스:

• 백엔드 API: http://localhost:8083/api (로컬 Docker)
• Market Data WebSocket: wss://exdev.co.kr/market-data/ws/chart (서버)
• Backend WebSocket: ws://localhost:8083/ws (로컬 Docker)

환경 변수 파일: .env.development, .env.local

특징:

• Hot Reload 지원 (코드 수정 시 자동 새로고침)
• 소스맵 포함 (디버깅 용이)
• 개발자 도구 활성화
• WebSocket Data Service는 서버(exdev.co.kr)에서 실행 중

---

2. 로컬 프로덕션 빌드 (Local Production Build)

빌드 방법:

npm run build

실행 방법:

# serve 패키지 설치 (한 번만)
npm install -g serve

# 빌드된 파일 서빙 (포트 3100)
serve -s build -l 3100

접속 URL:

• 프론트엔드: http://localhost:3100

자동 연결되는 서비스:

• 백엔드 API: http://localhost:8083/api (로컬 Docker)
• Market Data WebSocket: wss://exdev.co.kr/market-data/ws/chart (서버)
• Backend WebSocket: ws://localhost:8083/ws (로컬 Docker)

환경 변수 파일: .env.production.local (없으면 코드에서 자동 감지)

특징:

• 최적화된 프로덕션 빌드
• 코드 압축 및 난독화
• WebSocket Data Service는 서버(exdev.co.kr)에서 실행 중

---

3. 서버 배포 환경 (Production on Server)

빌드 방법:

npm run build

배포 방법:

# Docker 이미지 빌드 및 배포
docker-compose build frontend
docker-compose up -d frontend

접속 URL:

• 프론트엔드: https://exdev.co.kr (HTTPS, 포트 443)
• 또는: http://exdev.co.kr (HTTP, 포트 80)

nginx 프록시를 통해 연결되는 서비스:

• 백엔드 API: https://exdev.co.kr/api → backend:8083/api
• Market Data WebSocket: wss://exdev.co.kr/market-data/ws/chart → market-data-system:8086/ws/chart
• Backend WebSocket: wss://exdev.co.kr/ws → backend:8083/ws

환경 변수 파일: .env.production

특징:

• nginx 리버스 프록시 사용
• SSL/TLS 암호화 (HTTPS)
• 모든 서비스가 443 포트를 통해 접근
• 외부 네트워크에서 접근 가능

---

🔧 환경 감지 로직

API Base URL (apiConfig.ts)

export const getApiBaseUrl = (): string => {
  const isLocalhost = window.location.hostname === 'localhost' || 
                      window.location.hostname === '127.0.0.1' ||
                      window.location.hostname === '';
  
  if (isLocalhost) {
    // 로컬: 직접 연결
    return 'http://localhost:8083/api';
  }
  
  // 서버: nginx 프록시 (상대 경로)
  return '/api';
};

Market Data WebSocket URL (useMarketDataWebSocket.ts)

const getMarketDataUrl = (): string => {
  const isLocalhost = window.location.hostname === 'localhost' || 
                      window.location.hostname === '127.0.0.1' ||
                      window.location.hostname === '';
  
  if (isLocalhost) {
    // 로컬: 직접 연결
    return 'http://localhost:8086';
  }
  
  // 서버: nginx 프록시
  const protocol = window.location.protocol === 'https:' ? 'https:' : 'http:';
  return `${protocol}//${window.location.host}/market-data`;
};

핵심: window.location.hostname을 기준으로 자동 감지하므로, 환경 변수 없이도 동작합니다!

---

📁 환경 변수 파일 우선순위

React는 다음 순서로 환경 변수 파일을 로드합니다:

1. .env.development.local (개발 환경, git 무시)
2. .env.production.local (프로덕션 환경, git 무시)
3. .env.local (모든 환경, git 무시)
4. .env.development (개발 환경)
5. .env.production (프로덕션 환경)
6. .env (모든 환경)

현재 프로젝트:

• .env - 기본 포트 설정
• .env.local - 로컬 개발 설정
• .env.development - 개발 환경 설정
• .env.production - 프로덕션 환경 설정 (주석만, 실제로는 코드에서 자동 감지)

---

🚀 시나리오별 사용법

시나리오 1: 로컬에서 개발

# 1. 백엔드 서비스 실행 (Docker)
docker-compose up -d backend market-data-system

# 2. 프론트엔드 개발 서버 실행
cd frontend
npm start

# 3. 브라우저에서 접속
# http://localhost:3100

시나리오 2: 로컬에서 프로덕션 빌드 테스트

# 1. 백엔드 서비스 실행 (Docker)
docker-compose up -d backend market-data-system

# 2. 프론트엔드 빌드
cd frontend
npm run build

# 3. 빌드된 파일 서빙
serve -s build -l 3100

# 4. 브라우저에서 접속
# http://localhost:3100

시나리오 3: 서버에 배포

# 1. 전체 서비스 빌드 및 배포
docker-compose build
docker-compose up -d

# 2. 외부에서 접속
# https://exdev.co.kr

---

🔍 트러블슈팅

문제: 로컬에서 API 연결 안 됨

확인 사항:

1. 백엔드 서비스가 실행 중인지 확인

   docker-compose ps
   

2. 포트가 열려있는지 확인

   # Windows
   netstat -ano | findstr :8083
   netstat -ano | findstr :8086
   

3. 브라우저 콘솔에서 URL 확인

   [API Config] 로컬 환경 감지: http://localhost:8083/api
   [Market Data] WebSocket URL: ws://localhost:8086/ws/chart
   

문제: 서버에서 WebSocket 연결 안 됨

확인 사항:

1. nginx 설정 확인

   docker-compose exec frontend nginx -t
   

2. nginx 로그 확인

   docker-compose logs frontend
   

3. 브라우저 콘솔에서 URL 확인

   [Market Data] WebSocket URL: wss://exdev.co.kr/market-data/ws/chart
   

문제: Mixed Content 오류 (HTTP/HTTPS)

원인: HTTPS 페이지에서 HTTP 리소스 로드 시도

해결:

• 로컬: http://localhost 사용 (HTTPS 불필요)
• 서버: 모든 연결이 HTTPS/WSS로 자동 변환됨

---

📝 체크리스트

로컬 개발 시작 전

• Docker Desktop 실행 중
• docker-compose up -d backend market-data-system 실행
• npm install 완료
• 포트 3100, 8083, 8086 사용 가능

서버 배포 전

• 프로덕션 빌드 테스트 완료
• nginx 설정 확인
• SSL 인증서 유효
• 방화벽 443 포트 오픈

---

🎯 요약

환경	접속 URL	백엔드 API	Market Data WS	특징
로컬 개발	http://localhost:3100	http://localhost:8083	wss://exdev.co.kr/market-data	Hot Reload, 서버 WS
로컬 빌드	http://localhost:3100	http://localhost:8083	wss://exdev.co.kr/market-data	최적화 빌드, 서버 WS
서버 배포	https://exdev.co.kr	https://exdev.co.kr/api	wss://exdev.co.kr/market-data	nginx 프록시

핵심:

• 백엔드 API는 로컬/서버 환경에 따라 자동 감지
• WebSocket Data Service는 항상 서버(exdev.co.kr) 사용 🚀
• 별도 설정 없이 어디서든 동작합니다!