운영 서버 배포 및 관리 가이드 (Production Deployment Guide)

본 문서는 SmartIMS 솔루션을 운영 서버에 최초 설치하는 절차와 Git Tag를 이용한 효율적인 버전 관리 및 업데이트 방역에 대해 설명합니다.

1. 개요 (Overview)

SmartIMS 배포는 Git Tag 기반 배포 방식을 권장합니다. 이는 검증된 특정 시점의 소스 코드(Release)만을 운영 서버에 반영하여 시스템 안정성을 확보하고, 향후 시스템 관리 메뉴를 통해 손쉽게 업데이트할 수 있는 기반을 제공합니다.

운영 서버(Linux/Synology 등)에 접속한 상태에서 다음 과정을 순차적으로 진행합니다.

소스 클론: /volume1/web 위치에서 아래 명령어를 실행하면 smartims 폴더가 생성되며 그 안에 소스가 들어갑니다.

cd /volume1/web
# 저장소 URL 뒤에 'smartims'를 붙여 폴더명을 지정합니다.
git clone https://gitea.qideun.com/SOKUREE/smart_ims.git smartims
cd smartims

안정 버전(Tag) 전환:

git fetch --all --tags
# v0.2.6 버전으로 전환
git checkout v0.2.6

환경 설정:
- server/.env 파일을 환경에 맞게 생성(DB 정보 등 입력).
- server/config/public_key.pem 파일이 존재하는지 확인 (라이선스 검증용).

패키지 설치 및 빌드:

# 전체 의존성 설치 및 프론트엔드 빌드
npm install
npm run build

# 백엔드 의존성 설치
cd server
npm install

데이터베이스 초기화:

# 처음 설치 시에만 수행
node migrate_db.js

PM2 프로세스 등록:

pm2 start index.js --name "smartims-api"
pm2 save
pm2 startup

수동으로 업데이트가 필요할 경우 다음 명령어를 조합하여 실행합니다.

git fetch --tags
git checkout [새로운_태그]
npm install
npm run build
pm2 reload smartims-api

시스템의 "시스템 관리 > 버전 정보" 화면에서 신규 버전을 감지하고 원 클릭으로 업데이트할 수 있습니다.

참고: 이 기능을 사용하려면 [기본 설정] 메뉴에서 Gitea 원격 저장소 URL과 (필요 시) 계정 정보를 먼저 설정해야 합니다.
동작 원리:
1. 서버가 설정된 원격 저장소의 최신 Tag 리스트를 확인합니다.
2. package.json의 현재 버전과 원격의 최신 Tag를 비교합니다.
3. 업데이트 실행 시 서버가 백그라운드에서 git checkout -> npm install -> npm run build -> pm2 reload 과정을 자동으로 수행합니다.
기대 효과:
- 터미널(SSH) 접속 없이 관리자 화면에서 즉시 최신 기능 반영 가능.
- 운영 서버 환경에서도 편리한 버전 관리.

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