kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ERP-node/DOCKER.md

9.6 KiB
Raw Blame History

🐳 Docker 가이드 - WACE 솔루션 (ERP-node)

이 문서는 WACE 솔루션의 Docker 환경 설정 및 사용법을 설명합니다.

📋 개요

기술 스택:

  • 백엔드: Node.js + TypeScript + Prisma + PostgreSQL
  • 프론트엔드: Next.js + TypeScript + Tailwind CSS
  • 컨테이너: Docker + Docker Compose

환경:

  • 개발: Mac (볼륨 마운트 + Hot Reload)
  • 운영: Linux 서버 (최적화된 프로덕션 빌드)

🔧 개발 환경 (Mac)

빠른 시작

# 전체 서비스 시작 (병렬 빌드 - 가장 빠름!)
./scripts/dev/start-all-parallel.sh

개별 서비스 시작

# 백엔드만 시작
./scripts/dev/start-backend.sh

# 프론트엔드만 시작
./scripts/dev/start-frontend.sh

개발용 Docker Compose 파일들

  • docker/dev/docker-compose.backend.mac.yml - Mac 개발용 백엔드

    • 볼륨 마운트: ./backend-node:/app (Hot Reload)
    • Dockerfile: docker/dev/backend.Dockerfile
    • 포트: 8080

  • docker/dev/docker-compose.frontend.mac.yml - Mac 개발용 프론트엔드

    • 볼륨 마운트: ./frontend:/app (Hot Reload)
    • Dockerfile: docker/dev/frontend.Dockerfile
    • 포트: 3000

개발 환경 특징

  • ✅ Hot Reload: 코드 변경 시 자동 반영
  • ✅ 볼륨 마운트: 실시간 개발
  • ✅ 디버그 모드: 상세 로그 출력
  • ✅ 빠른 재시작: Docker 재빌드 불필요

🔥 Hot Reload 상세 가이드

✅ 바로 반영되는 것들 (즉시 Hot Reload)

백엔드 (Node.js + TypeScript):

backend-node/src/controllers/*.ts    # API 컨트롤러 수정
backend-node/src/services/*.ts       # 비즈니스 로직 수정
backend-node/src/routes/*.ts         # 라우터 설정 수정
backend-node/src/middleware/*.ts     # 미들웨어 수정
backend-node/src/utils/*.ts          # 유틸리티 함수 수정
backend-node/src/types/*.ts          # 타입 정의 수정
backend-node/src/config/*.ts         # 애플리케이션 설정

→ 반영 시간: 1-2초 (nodemon 자동 재시작)

프론트엔드 (Next.js + TypeScript):

frontend/components/**/*.tsx         # React 컴포넌트 수정
frontend/app/**/*.tsx               # 페이지 컴포넌트 수정
frontend/lib/**/*.ts                # 유틸리티 함수 수정
frontend/hooks/*.ts                 # 커스텀 훅 수정
frontend/types/*.ts                 # 타입 정의 수정
frontend/constants/*.ts             # 상수 정의 수정
CSS/SCSS 파일 수정                   # 스타일 변경

→ 반영 시간: 즉시 (Fast Refresh)

❌ Docker 재시작이 필요한 것들

의존성 변경:

package.json 수정                   # 새 패키지 추가/제거
npm install / npm uninstall         # 패키지 설치/제거
package-lock.json 변경              # 의존성 잠금 파일

Prisma 관련:

backend-node/prisma/schema.prisma   # DB 스키마 변경
npx prisma migrate                  # 마이그레이션 실행
npx prisma generate                 # 클라이언트 재생성

설정 파일:

next.config.mjs                     # Next.js 설정
tsconfig.json                       # TypeScript 설정
tailwind.config.js                  # Tailwind CSS 설정
.env / .env.local                   # 환경 변수
eslint.config.mjs                   # ESLint 설정

Docker 관련:

Dockerfile / Dockerfile.dev         # 도커 파일 수정
docker-compose.*.yml                # Docker Compose 설정
.dockerignore                       # Docker 무시 파일

🔄 재시작 방법

특정 서비스만 재시작:

# 백엔드만 재시작
docker-compose -f docker-compose.backend.mac.yml restart backend

# 프론트엔드만 재시작
docker-compose -f docker-compose.frontend.mac.yml restart frontend

전체 재빌드:

# 의존성 변경 시 (rebuild 필요)
docker-compose -f docker-compose.backend.mac.yml up --build -d
docker-compose -f docker-compose.frontend.mac.yml up --build -d

🚀 운영 환경 (Linux)

운영 서버 배포

# Linux 서버에서 실행
./scripts/prod/start-all-linux.sh

개별 서비스 시작 (운영용)

# 직접 Docker Compose 사용
docker-compose -f docker/prod/docker-compose.backend.prod.yml up -d
docker-compose -f docker/prod/docker-compose.frontend.prod.yml up -d

운영용 Docker Compose 파일들

  • docker/prod/docker-compose.backend.prod.yml - 운영용 백엔드

    • Dockerfile: docker/prod/backend.Dockerfile (프로덕션 최적화)
    • 포트: 8080
    • 환경: NODE_ENV=production

  • docker/prod/docker-compose.frontend.prod.yml - 운영용 프론트엔드

    • Dockerfile: docker/prod/frontend.Dockerfile (프로덕션 최적화)
    • 포트: 3000
    • 환경: 최적화된 빌드

운영 환경 특징

  • ✅ 최적화된 빌드: 프로덕션용 이미지
  • ✅ 보안 강화: 운영 환경 설정
  • ✅ 성능 최적화: 이미지 크기 최소화
  • ✅ 안정성: 프로덕션 모드

📁 프로젝트 구조

ERP-node/
├── 🔧 개발용 (Mac)
│   ├── start-all-parallel.sh          # 병렬 시작 (추천)
│   ├── start-backend.sh               # 백엔드만
│   ├── start-frontend.sh              # 프론트엔드만
│   ├── docker-compose.backend.mac.yml # Mac 개발용 백엔드
│   └── docker-compose.frontend.mac.yml# Mac 개발용 프론트엔드
│
├── 🚀 운영용 (Linux)
│   ├── start-all-separated-linux.sh   # Linux 운영용
│   ├── start-backend-linux.sh         # 백엔드만 (Linux)
│   ├── start-frontend-linux.sh        # 프론트엔드만 (Linux)
│   ├── docker-compose.backend.prod.yml# 운영용 백엔드
│   └── docker-compose.frontend.prod.yml# 운영용 프론트엔드
│
├── 📁 백엔드
│   ├── backend-node/
│   │   ├── Dockerfile                 # 프로덕션용
│   │   └── Dockerfile.dev             # 개발용
│   └── src/, prisma/, package.json...
│
├── 📁 프론트엔드
│   ├── frontend/
│   │   ├── Dockerfile                 # 프로덕션용
│   │   └── Dockerfile.dev             # 개발용
│   └── app/, components/, hooks/...
│
└── 🗂️ 기타
    ├── db/00-create-roles.sh          # DB 초기화
    └── README.md, DOCKER.md...

🌐 접속 정보

개발 환경

운영 환경

  • 서버 IP에 따라 다름 (Linux 서버 설정 확인)

🛠️ 주요 명령어

Docker 컨테이너 관리

# 실행 중인 컨테이너 확인
docker ps

# 모든 컨테이너 중지
docker stop $(docker ps -q)

# 사용하지 않는 컨테이너/이미지 정리
docker system prune -f

로그 확인

# 백엔드 로그
docker logs pms-backend-mac -f     # 개발용
docker logs pms-backend-prod -f    # 운영용

# 프론트엔드 로그
docker logs pms-frontend-mac -f    # 개발용
docker logs pms-frontend-prod -f   # 운영용

컨테이너 내부 접속

# 백엔드 컨테이너 접속
docker exec -it pms-backend-mac bash   # 개발용
docker exec -it pms-backend-prod bash  # 운영용

# 프론트엔드 컨테이너 접속
docker exec -it pms-frontend-mac sh    # 개발용
docker exec -it pms-frontend-prod sh   # 운영용

🚨 트러블슈팅

자주 발생하는 문제들

1. 포트 충돌

# 포트 사용 중인 프로세스 확인
lsof -i :8080
lsof -i :3000

# 프로세스 종료
kill -9 <PID>

2. Docker 빌드 오류

# Docker 캐시 클리어 후 재빌드
docker builder prune -f
./start-all-parallel.sh

3. 볼륨 마운트 문제 (개발환경)

# Docker Desktop 설정에서 파일 공유 확인
# Docker Desktop > Settings > Resources > File Sharing

4. 데이터베이스 연결 오류

# 데이터베이스 초기화
./db/00-create-roles.sh

# PostgreSQL 연결 확인
docker exec -it <db-container> psql -U postgres

Warning 메시지들 (무시해도 됨)

WARN: the attribute `version` is obsolete
Network Error (일시적)

이런 메시지들은 Docker Compose 버전 차이로 발생하며, 기능에는 영향 없습니다.

📈 성능 최적화

개발 환경 최적화

  • ✅ 병렬 빌드: start-all-parallel.sh 사용
  • ✅ Docker 캐시: --no-cache 제거됨
  • ✅ npm 최적화: --prefer-offline --no-audit 적용

운영 환경 최적화

  • ✅ 멀티 스테이지 빌드: Dockerfile 최적화
  • ✅ 이미지 크기 최소화: Alpine Linux 기반
  • ✅ 의존성 캐시: 레이어 캐싱 활용

🔄 업데이트 가이드

개발 환경 업데이트

# 코드 변경 시 (Hot Reload 자동 반영)
# 별도 작업 불필요

# 의존성 변경 시
docker-compose -f docker-compose.backend.mac.yml up --build -d

운영 환경 업데이트

# 새로운 버전 배포
./start-all-separated-linux.sh

📞 지원

문제 발생 시:

  1. 이 문서의 트러블슈팅 섹션 확인
  2. Docker 로그 확인 (docker logs <container-name>)
  3. 개발팀에 문의

프로젝트 관련:

  • Node.js 백엔드: backend-node/ 디렉토리
  • Next.js 프론트엔드: frontend/ 디렉토리
  • 데이터베이스: PostgreSQL (JNDI 설정)

버전: 1.0.0
마지막 업데이트: 2024년 12월 28일
작성자: PLM 개발팀