PM_ver4 로컬 실행을 위한 To-Do List 및 개발 환경 세팅 가이드

이 문서는 PM_ver4 프로젝트를 로컬(Windows) 개발 환경에서 성공적으로 빌드하고 실행하기 위한 전체 To-Do List입니다. 이 프로젝트는 Node.js(Express) 백엔드, PostgreSQL DB, Redis(BullMQ), MinIO(스토리지) 및 외부 OAuth(Sentinel) 연동으로 구성되어 있습니다.

📋 로컬 실행 To-Do List 요약

[V] 1단계: 필수 개발 도구 설치 (Prerequisites)
[V] 2단계: 의존성 패키지 설치 (npm install)
[V] 3단계: Docker Compose를 이용한 로컬 인프라 구동 (DB, Redis, MinIO)
[V] 4단계: 환경 변수(.env) 파일 작성
5단계: 데이터베이스 스키마 생성 및 초기 데이터 적재
6단계: 로컬 테스트를 위한 인증(SSO) 우회 설정 (선택/권장)
7단계: 외부 문서 변환 프로그램 확인 (programs/)
8단계: 웹 서버 실행 및 접속 테스트

🛠️ 단계별 상세 가이드

1단계: 필수 개발 도구 설치

프로젝트 구동을 위해 로컬 PC에 아래 도구들이 설치되어 있어야 합니다.

Node.js: v18 또는 v20 LTS 권장
Docker Desktop: PostgreSQL, Redis, MinIO를 원클릭으로 띄우기 위해 필요

2단계: 의존성 패키지 설치

터미널(PowerShell 등)을 열고 프로젝트 폴더의 trunk/PM_ver4로 이동합니다.
아래 명령어를 실행하여 npm 패키지들을 설치합니다.
```
npm install
```

3단계: Docker Compose 실행 (로컬 인프라 구동)

프로젝트에 포함된 docker-compose.yml을 사용하여 PostgreSQL, Redis, MinIO 서비스를 가상 환경으로 실행합니다.

trunk/PM_ver4 디렉토리에서 아래 명령을 실행합니다.
```
docker compose up -d
```
컨테이너가 정상적으로 실행되었는지 확인합니다 (docker ps).
- PostgreSQL: 5432 포트
- Redis: 6379 포트
- MinIO: 9000 (S3 API), 9001 (관리자 웹 콘솔) 포트

4단계: 환경 변수(`.env`) 파일 작성

trunk/PM_ver4 루트 디렉토리에 .env 파일을 새로 생성하고 아래 내용을 환경에 맞춰 입력합니다.

# 1. 공통 애플리케이션 설정
NODE_ENV=development
SERVICE_NAME=PM_ver4_LOCAL
DEPLOYMENT_TYPE=ONPREMISE
COOKIE_SECRET=your_secret_cookie_key

# 2. 로컬 서버 IP 및 포트
LOCAL_IP=localhost
LOCAL_PORT=6565

# 3. PostgreSQL DB 설정 (ONPREMISE)
ONPREMISE_POSTGRES_HOST=localhost
ONPREMISE_POSTGRES_PORT=5432
ONPREMISE_POSTGRES_DATABASE=pm_db
ONPREMISE_POSTGRES_USER=postgres
ONPREMISE_POSTGRES_PASSWORD=your_password

# 4. Redis 설정
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# 5. MinIO 스토리지 설정
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESSKEYID=minio_access_key
MINIO_SECRETACCESSKEY=minio_secret_key

# 6. OAuth(Sentinel SSO) 인증 서버 설정
SENTINEL_BASE=http://sso.hanmaceng.co.kr  # 실제 사내 SSO 주소 입력
CLIENT_ID=PM_LOCAL

# 7. Gemini API 설정 (공문 AI 파싱 기능 사용 시 필요)
GEMINI_API_KEY=your_google_gemini_api_key

5단계: 데이터베이스 스키마 생성 및 초기 데이터 적재

Docker로 postgres 컨테이너만 띄운 상태이므로, 데이터베이스(pm_db) 내부에 스키마와 테이블들이 존재하지 않습니다. 로컬 실행을 위해 아래 작업이 필요합니다.

스키마 백업본 확보: 사내 개발 환경 혹은 운영 환경 DB에서 ver4 스키마 DDL/DML 백업 파일(.sql 등)을 받습니다.
로컬 DB에 적용:
- DBeaver, pgAdmin 등의 DB 클라이언트를 통해 localhost:5432로 PostgreSQL에 접속합니다.
- 데이터베이스 이름: pm_db, 사용자: postgres, 비밀번호: your_password
- ver4 스키마를 생성하고 백업받은 SQL 덤프 파일을 실행하여 테이블들을 구축합니다.
- 참고: tb_user, tb_permission, _test_tb_data, _test_tb_log, tb_official_doc_file 등의 테이블이 필요합니다.

6단계: 로컬 테스트를 위한 인증(SSO) 우회 설정 (권장)

이 프로젝트는 로그인 시 외부 Sentinel SSO 서버로 리다이렉트되어 인증을 처리합니다. 사내 망 외부이거나 로컬에서 간편하게 개발을 진행하려면 인증 미들웨어를 임시로 우회해야 합니다.

우회 방법: [oauthController.js](file:///d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/oauth/oauthController.js) 파일의 isLoggedIn 함수를 수정하여 항상 특정 개발자 계정 세션을 갖도록 처리할 수 있습니다.

// d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/oauth/oauthController.js
exports.isLoggedIn = async(req, res, next) => {
    // 로컬 테스트 시 강제로 세션 주입하고 통과시킴
    req.session.user = { 
        userId: 'test_user', 
        user_nm: '테스트사용자',
        group: 'dev' 
    };
    next();
}

사용자 디바인딩 우회: GSIM 서버 연동이 안 될 경우, [oauthController.js](file:///d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/oauth/oauthController.js)의 deserializeUser 함수에서 axios.post 부분을 주석 처리하고 Mock User 정보를 req.user에 직접 할당해야 합니다.

7단계: 외부 문서 변환 프로그램 확인

trunk/PM_ver4/programs/ 디렉토리에 파일 암호화 도구(encryp.exe), 썸네일 추출기(pdf_thumb.exe), 한글/캐드 변환 모듈 등이 존재합니다.

백그라운드 변환 기능(BullMQ 워커)이 올바르게 실행되려면 Windows 환경에서 해당 윈도우용 CLI 프로그램들의 실행 권한 및 관련 라이브러리 연동에 문제가 없어야 합니다.

8단계: 웹 서버 실행 및 접속 테스트

의존성 패키지와 로컬 인프라(Docker) 세팅이 끝나면 아래 명령으로 Node.js 서버를 실행합니다.
```
npm run start
```
(내부적으로 nodemon server.js가 구동됩니다.)
콘솔에 >> Web Server Start : http://localhost:6565/ 번 포트에서 대기 중 로그와 Redis connected, DB 연결 성공 메시지가 찍히는지 확인합니다.
웹 브라우저를 열고 http://localhost:6565에 접속하여 로컬 구동 여부를 확인합니다.

6.3 KiB Raw Blame History