124 lines
6.3 KiB
Markdown
124 lines
6.3 KiB
Markdown
# 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단계: 의존성 패키지 설치
|
|
1. 터미널(PowerShell 등)을 열고 프로젝트 폴더의 `trunk/PM_ver4`로 이동합니다.
|
|
2. 아래 명령어를 실행하여 npm 패키지들을 설치합니다.
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 3단계: Docker Compose 실행 (로컬 인프라 구동)
|
|
프로젝트에 포함된 `docker-compose.yml`을 사용하여 PostgreSQL, Redis, MinIO 서비스를 가상 환경으로 실행합니다.
|
|
1. `trunk/PM_ver4` 디렉토리에서 아래 명령을 실행합니다.
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
2. 컨테이너가 정상적으로 실행되었는지 확인합니다 (`docker ps`).
|
|
* **PostgreSQL**: `5432` 포트
|
|
* **Redis**: `6379` 포트
|
|
* **MinIO**: `9000` (S3 API), `9001` (관리자 웹 콘솔) 포트
|
|
|
|
### 4단계: 환경 변수(`.env`) 파일 작성
|
|
`trunk/PM_ver4` 루트 디렉토리에 `.env` 파일을 새로 생성하고 아래 내용을 환경에 맞춰 입력합니다.
|
|
|
|
```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`) 내부에 스키마와 테이블들이 존재하지 않습니다. 로컬 실행을 위해 아래 작업이 필요합니다.
|
|
|
|
1. **스키마 백업본 확보**: 사내 개발 환경 혹은 운영 환경 DB에서 `ver4` 스키마 DDL/DML 백업 파일(`.sql` 등)을 받습니다.
|
|
2. **로컬 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` 함수를 수정하여 항상 특정 개발자 계정 세션을 갖도록 처리할 수 있습니다.
|
|
```javascript
|
|
// 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단계: 웹 서버 실행 및 접속 테스트
|
|
1. 의존성 패키지와 로컬 인프라(Docker) 세팅이 끝나면 아래 명령으로 Node.js 서버를 실행합니다.
|
|
```bash
|
|
npm run start
|
|
```
|
|
*(내부적으로 `nodemon server.js`가 구동됩니다.)*
|
|
2. 콘솔에 `>> Web Server Start : http://localhost:6565/ 번 포트에서 대기 중` 로그와 `Redis connected`, `DB 연결 성공` 메시지가 찍히는지 확인합니다.
|
|
3. 웹 브라우저를 열고 `http://localhost:6565`에 접속하여 로컬 구동 여부를 확인합니다.
|