smart_ims/docs/DEPLOYMENT_GUIDE.md

시스템 배포 가이드 (Deployment Guide)

본 문서는 빌드된 스마트 IMS(Smart IMS) 솔루션을 실서버(Synology NAS 등)에 배포할 때 필요한 절차와 주의사항을 설명합니다.

1. 배포 대상 폴더 및 파일

서버에 업로드해야 하는 핵심 구성 요소는 다음과 같습니다.

1.1. dist/ 폴더 (프론트엔드)

• 생성 방법: npm run build 명령을 통해 생성됩니다.
• 역할: 사용자 브라우저에서 실행되는 정적 웹 파일(JS, CSS, HTML)입니다.
• 위치: 업로드 시 server/ 폴더와 동일한 레벨 혹은 서버 설정에 맞게 배치합니다.

1.2. server/ 폴더 (백엔드)

• 프로젝트의 API 및 세션, 라이선스 검증을 담당하는 핵심 로직입니다.
• 주의: node_modules는 서버에서 직접 npm install을 실행하여 생성하는 것을 권장합니다.

---

2. 보안 및 라이선스 필수 파일 (중요)

배포 시 다음 파일들의 유무와 내용을 반드시 점검해야 합니다.

2.1. server/.env (환경 변수)

• 설정: DB 접속 정보(Host, User, Password)와 포트 번호가 포함되어 있습니다.
• 주의: 배포 환경에 맞는 DB 정보를 정확히 입력해야 서버가 시작됩니다.

2.2. server/public_key.pem (RSA 공개키)

• 역할: 발급된 라이선스 키가 진짜인지 검증하는 데 사용됩니다.
• 필수: 이 파일이 없으면 웹에서 라이선스 활성화 및 로그인이 불가능할 수 있습니다.
• 보안: 공개되어도 무방한 파일입니다. (이 파일만으로는 라이선스 생성 불가)

---

3. 배포 시 제외해야 할 파일 (보안 주의)

다음 파일들은 절대로 고객사 서버에 업로드하지 마십시오.

1. tools/ 폴더 전체: 라이선스 발급 도구가 들어 있어 고객이 직접 키를 생성할 위험이 있습니다.
2. tools/keys/private_key.pem (개인키): 라이선스를 생성할 수 있는 마스터키입니다. 유출 시 모든 보안이 무너집니다.

4. 시놀로지 역방향 프록시 설정 (CCTV 필수)

도메인(https://demo.sokuree.com)을 통해 접속할 경우, WebSocket 통신이 허용되도록 설정해야 CCTV 영상이 출력됩니다.

1. 제어판 > 로그인 포털 > 고급 > 역방향 프록시 이동.
2. 해당 도메인 설정 선택 후 [편집] 클릭.
3. [사용자 정의 헤더] 탭으로 이동.
4. [생성] 버튼 옆의 드롭다운(화살표) 클릭 > WebSocket 선택.
5. Upgrade, Connection 헤더가 자동으로 추가된 것을 확인하고 **[저장]**을 클릭합니다.
   • 이 설정이 없으면 CCTV 화면이 검은색으로 나오거나 연결 오류가 발생합니다.

---

5. 서버 실행 절차 (PM2 기준)

업로드가 완료된 후 서버 터미널(SSH)에서 다음 명령을 실행합니다.

1. 의존성 설치: cd server 이동 후 npm install
2. 서비스 시작: pm2 start index.js --name "smartims"
3. 상태 확인: pm2 status를 통해 서버가 online 상태인지 확인합니다.

---

마지막 업데이트: 2026-01-22