itsm_ysm/docs/ITMS_INSTALL_RUNBOOK.md

ITMS 설치 실전 런북 (전체 스택)

최종 갱신: 2026-07-19 | 정본 = 이 문서 + install/(스크립트) + docs/ITMS_서버설치가이드.docx(기본 4-WAR 절차) 이 런북은 설치가이드(4-WAR)에 실전 운영 절차(OpenSearch 검색·Docker·배치/Quartz·프로시저/트리거·업로드 경로·방화벽·통합 테스트)를 합친 것이다. 소유자 제공 설치 노트(2026-07-19) 반영. 보안: 접속정보·비밀번호·keystore 비번·연동 키를 로그/문서/커밋에 노출 금지. env·keystore 권한 600, 소유자 서비스계정.

0. 시스템 구성 (실전 파악)

ITMS 는 4-WAR(auth:11000·api:11010·front:11020·batch:11030) + datatrans 데몬 + 검색엔진(OpenSearch) 으로 구성된다.

• 검색 경유: 목록/조회 검색은 OpenSearch 색인을 탄다. 배치(Quartz)가 DB ↔ OpenSearch 색인을 중개한다("검색이 되면 배치도 도는 것" = 배치가 색인을 갱신하므로 검색 성공 = 배치 정상). api ↔ 배치 ↔ 검색 간 데이터가 오간다.
• DB 프로시저/함수/트리거: 결재·업무 로직 일부가 DB 프로시저/함수/트리거로 구현(PROC_APPROVAL·PROC_REJECT·PROC_REQ_APPROVAL·FUNC_HOLIDAYS 등 5개 + 트리거). 스키마 적재만으로 부족 — 반드시 등록.
• Docker: OpenSearch(및 부속)를 Docker 로 기동. 디스크 부족 시 Docker 루트 디렉터리 이전 필요.

1. 사전 요구 (Feasibility Gate — 설치 전 실측)

항목	요구	미충족 시
OS/systemd	Linux	—
JDK17	빌드·런타임 공통 (Boot 2.6.2 Java21 미지원)	apt openjdk-17-jdk / dnf java-17-openjdk-devel
메모리	4GB+ 권장 (4 WAR + 데몬 + OpenSearch 1~2GB)	★게이트: 부족 시 모듈 축소 기동 or 서버 분리
디스크	빌드·아티팩트·로그·OpenSearch 인덱스·Docker 이미지 여유	★Docker 루트 이전(§4)
MariaDB	ur_itms_db (api/batch 필수)	설치·적재(§3)
Oracle XE	batch 인사 연동	미도달 시 batch 부분 보류
OpenSearch	검색 백엔드(Docker)	미기동 시 검색·배치 검증 불가
JDBC 드라이버	Oracle ojdbc 등은 Maven 미제공 → 설치 파일로 동봉·수동 배치	빌드/기동 실패
네트워크	11000/11010/11020/11030 + OpenSearch 포트 개방	§9 방화벽
시크릿	기관 application-<기관>.yml · keystore(UrpSystem/UrpSysKeyMng)	사전 확보

2. 패키지·계정·디렉터리·systemd

tar xzf itms-install-*.tar.gz && cd itms-install
sudo bash preflight.sh            # JDK17·DB 도달·디스크 점검
sudo dnf install -y java-17-openjdk-devel   # (미설치 시)
sudo bash install.sh              # itms 계정·/opt/itms·/etc/itms·systemd 유닛(멱등). start 안 함

3. DB 준비 (MariaDB ur_itms_db)

1. 스키마 적재: 실제 고객 스키마 mmsdb CM_* DDL(note1.txt) → ur_itms_db. charset utf8(mb3/mb4) 한글 정합.
2. 데이터 적재: mms_data/*.csv (테이블명_날짜.csv) → 대응 테이블(LOAD DATA/mysqlimport, 인코딩·NULL 확인).
3. 프로시저/함수 5개 (DBeaver 또는 mysql): note3.txt 의 PROC_APPROVAL·PROC_REJECT·PROC_REQ_APPROVAL·FUNC_HOLIDAYS(+잔여 1) — 함수명/DELIMITER 정확히.
4. 트리거 생성: 테이블명·함수명 정확히 매칭하여 트리거 등록(DBeaver: 테이블 좌클릭 → 트리거 생성). note/DDL의 트리거 정의 기준.
5. 업로드 파일 경로: 첨부/업로드 저장 경로를 DB 설정에 반영(파일 저장 루트를 서버 실제 경로로).
6. 인덱스(note2.txt/index.sql) 적용.
7. 로그인 계층(포털: COMVNUSERMASTER·TB_*·oauth)은 실 dump에 없으면 역설계본 유지(로그인 동작 보존). CM_*가 실 dump 권위.

4. Docker + OpenSearch (검색)

1. Docker 설치·기동. 디스크 부족 시 Docker 루트 디렉터리 이전:
   • /etc/docker/daemon.json 에 {"data-root": "/data/docker"} → systemctl restart docker (기존 이미지 이전 or 재pull).
2. OpenSearch 컨테이너 기동(메모리 -Xms/-Xmx 서버 여유 내로 제한, 예 512m~1g). 보안플러그인/포트 설정.
3. Dev Tools 테스트: OpenSearch Dashboards Dev Tools 진입 → 쿼리 입력 후 Ctrl+Enter 로 실행, 인덱스/검색 응답 확인.

5. 아티팩트 빌드 (온라인 필요)

• 컴파일 시 온라인(gradle 배포판·의존성 다운로드 — 콜드 빌드 1회 워밍). CI(방법 B) 또는 deploy/build.sh(JDK17).
• JDBC 드라이버: Oracle ojdbc 등 Maven 미제공 드라이버는 설치 파일로 동봉해 빌드 classpath/lib 에 배치.
• 산출물 */build/libs/itms-<모듈>.war → /opt/itms/artifacts/current/.

6. 설정 파일 수정 (폴더·IP·Yaml·Quartz)

1. 폴더·IP 정합: 각 application-<기관>.yml 및 설정의 경로/호스트를 대상 서버 폴더·IP 로 정확히 수정.
2. Quartz property: 배치 스케줄러 property(잡·데이터소스·색인 대상) 값 변경.
3. 설치 정보 파일 수정(설치 메타/버전/경로).
4. 프로파일 파일명 쉘 반영: §6-1에서 수정한 프로파일 파일명을 기동 쉘/env SPRING_PROFILES_ACTIVE 에 동일하게 반영(파일명↔쉘 불일치 시 미기동).

7. 기동 (순서 준수)

# /etc/itms/itms-<모듈>.env: SPRING_PROFILES_ACTIVE=<기관>, JAVA_OPTS=-Xms256m -Xmx512m
sudo systemctl daemon-reload
# 순서대로 올리고 각 단계 프로세스 확인
for m in auth api front batch datatrans; do sudo systemctl enable --now itms-$m; sleep 3; systemctl is-active itms-$m; done

8. 방화벽 (Linux)

• 내부 포트 11000/11010/11020/11030 + OpenSearch 포트 개방(firewalld/ufw). 외부는 리버스 프록시(HTTPS)만 노출.

9. 최종 점검 (통합 테스트)

#	항목	기대
1	down/start 쉘 동작	중지·기동 쉘 정상, 프로세스 up/down 반영
2	헬스	11000/11010/11020 200, batch/datatrans 로그 라이브
3	SR 신청 1건	등록 성공(DB insert 확인)
4	검색	SR/자산 검색 결과 노출 = 배치 색인 정상(검색되면 배치도 도는 것)
5	통합 테스트	로그인→메인→SR 등록→결재(프로시저)→검색→보고서 흐름
6	자산 대용량 처리	대량 자산 조회/색인 성능·오류 확인
7	배치 중개	배치가 DB↔검색(AP) 데이터 왕복 정상

10. 테스트 자격

• MariaDB root, 테스트 계정 admin — 값은 서버 로컬/시크릿 저장소에서만 조달, 이 문서·로그·커밋에 미기재.

11. 트러블슈팅

• 기동 즉시 종료 → journalctl -u itms-<모듈> (DB 미도달/프로파일 오류).
• gradlew 127 → CRLF: sed -i 's/\r$//' gradlew.
• front 빌드 실패 → egov spring-modules-validation(artifact-only 저장소) 배선 확인.
• webhook 미동작 → url localhost·secret 일치·ALLOWED_HOST_LIST loopback + deploy_server 서버 사본 반영·재시작.
• Docker 디스크 부족 → data-root 이전(§4-1).
• 검색 무결과 → 배치 색인 잡 확인(Quartz property·OpenSearch 도달).