시작 가이드

개요

원라인 설치 또는 Docker 설치로 플랜트펄스 플랫폼을 설치하셨다면, 모든 운영 스크립트는 /opt/kopens/plantpulse-platform-docker/bin/ 디렉토리에 있습니다. 이 페이지에서는 Docker Compose 스택으로 동작하는 플랫폼을 시작하고 운영하는 방법을 안내합니다.

플랫폼은 컨테이너 아홉 개로 구성됩니다 — 인증서 원샷 하나, 데이터레이크 하나, 앱 여섯, 프록시 하나. 구성 전체는 Docker 설치 — 설치되는 모양에 있습니다.

옛 스크립트 이름을 쓰고 계신다면

아래 왼쪽 이름들은 더 이상 존재하지 않습니다. 오른쪽의 공통 동사를 사용해 주세요.

옛 이름	지금 쓸 것
start.sh	up.sh
platform-stop.sh	down.sh
platform-update.sh	update.sh
platform-remove.sh	remove.sh
platform-bash.sh	shell.sh
platform-verify-boot.sh	stack-verify-boot.sh
worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh	워커 관리 참조

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh 는 그대로 동작합니다(새 이름을 한 줄 안내한 뒤 같은 일을 합니다).

환경 변수 설정

플랫폼 시작 전에 환경 변수를 확인해 주세요. 자원값은 설치 시 호스트를 보고 자동으로 계산되므로, 대부분의 서버에서는 손댈 것이 거의 없습니다.

vi /opt/kopens/plantpulse-platform-docker/bin/env.sh

자주 조정하는 항목

변수	설명	기본값
PP_LANG	플랫폼 로케일 (ko / en)	en
PP_TZ	플랫폼 타임존	Asia/Seoul
DOCKER_PP_CPUS	컨테이너에 줄 vCPU 수	nproc 결과
DOCKER_PP_MEMORY	메모리 상한	호스트 RAM 의 90%
DOCKER_DATALAKE_MEMORY	데이터레이크 메모리 상한	80G (호스트가 작으면 RAM 의 90%)
DOCKER_PP_DATA_DISK_NAME	데이터 디스크 이름	자동 역추적 (실패 시 sda)
DOCKER_PP_EXTERNAL_IP	NAT 환경의 외부 advertise IP	빈 값

환경 변수 전체 목록은 환경 변수 레퍼런스 페이지를 참고해 주세요.

변경 적용: env.sh 를 수정한 뒤에는 반드시 ./restart.sh 로 재시작해야 새 설정이 반영됩니다.

비밀번호는 env.sh 로 바꿀 수 없습니다

설치가 끝난 노드에서는 시크릿 사이드카(/etc/kopens/plantpulse-platform.env)가 env.sh 와 셸 export 를 모두 이깁니다. 비밀번호 변경은 비밀번호 회전의 passwd.sh 를 사용해 주세요.

플랫폼 시작

최초 설치 후 시작

설치(install.sh)가 완료되면 스택이 이미 실행 중입니다. 상태만 확인해 주세요.

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

정지된 스택 시작

./down.sh 또는 호스트 재부팅 등으로 스택이 정지된 경우 다시 시작합니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./up.sh

up.sh 는 멱등이며 준비될 때까지 기다립니다. 종료 코드 0 은 «명령이 성공했다»가 아니라 «이제 쓸 수 있다» 라는 뜻입니다.

환경 변수	기본값	뜻
PP_READY_TIMEOUT	900	준비 대기 상한(초)
PP_READY_INTERVAL	15	확인 간격(초)
PP_WAIT=0	—	대기하지 않음 (이때의 0 은 준비 완료가 아닙니다)

볼륨(pp-data, pp-temp, pp-backup, pp-security, pp-proxy-certs)의 데이터는 그대로 유지됩니다. 템플릿/설정은 호스트 바인드 마운트(/etc/kopens/conf)로 관리됩니다.

시작 순서

컨테이너는 compose 의 depends_on 이 정한 순서로 뜹니다. service_healthy 조건이므로 «프로세스가 떴다»가 아니라 «쓸 수 있다»를 기다립니다.

plantpulse-certs        (완료까지 — 원샷)
      │
plantpulse-datalake     (healthy 까지)
      │
plantpulse-server-web   (healthy 까지) ──── plantpulse-proxy
      │
plantpulse-batch-web    (healthy 까지)
      │
      ├── plantpulse-warehouse
      ├── plantpulse-plugin-opcua-server
      ├── plantpulse-plugin-aasx-server
      └── plantpulse-ha        (이 넷은 서로 순서가 없습니다)

데이터레이크 컨테이너 안에서는 인프라 컴포넌트가 다시 순서대로 기동합니다.

순서	카테고리	컴포넌트
1	스토리지	Valkey(Redis), PostgreSQL, Cassandra, MinIO
2	분석	Spark, Hadoop, Hive, Kyuubi, Gravitino
3	시계열	시계열 엔진, 시계열 UI
4	메시징	Kafka, MQTT
5	워크플로우	Temporal, Kestra
6	처리	CEP, Data Gateway, SQL, Monitor

소요 시간

프로세스 기동 자체는 35분(JVM 워밍업)이지만, 클린 설치는 **전 컴포넌트가 안정되기까지 1518분**이 걸립니다. Cassandra 스키마 마이그레이션과 안정화가 가장 느립니다.

실측(2026-08-31, 32 vCPU / 128GiB): 데이터레이크 217초, 웹 서버 316초. 데이터가 이미 있는 재시작은 이보다 훨씬 빠릅니다.

부팅 검증

cd /opt/kopens/plantpulse-platform-docker/bin
./stack-verify-boot.sh

stack-verify-boot.sh 는 컨테이너 하나가 아니라 스택 전체를 판정합니다 — 원샷이 정상 종료됐는지, 데이터레이크와 앱들이 running·healthy 인지, 프록시가 443 을 서비스하는지까지 봅니다. 노드 티어(PP_TIER — FULL / DATALAKE / APP)를 인식하여 해당 티어에 존재하는 컴포넌트만 검증합니다.

up.sh 와 restart.sh 는 이 스크립트가 통과할 때까지 폴링하며, 그것이 두 명령의 종료 코드 0 이 «쓸 수 있다»를 뜻하는 근거입니다.

정상 시작 확인

# 서비스 / health / 볼륨 요약 (0 = 정상 / 2 = 비정상)
./status.sh

# 운영 health + 최근 critical log 점검
./ops-check.sh

# 헬스체크 엔드포인트 직접 호출
curl -kfsS https://<서버IP>:4950/api/health | jq

# Docker 상태
docker ps

docker ps 에서 여덟 개가 (healthy), plantpulse-certs 가 Exited (0) 이면 정상입니다. 원샷의 Exited (0) 은 성공 상태이지 장애가 아닙니다.

플랫폼 중지

cd /opt/kopens/plantpulse-platform-docker/bin
./down.sh

스택을 안전하게 정지합니다. 데이터는 Docker 볼륨에 그대로 보존되므로 ./up.sh 로 다시 시작하면 이전 상태가 유지됩니다.

주의: docker kill 이나 호스트 강제 종료는 데이터 일관성을 깨뜨릴 수 있습니다. 반드시 ./down.sh 를 사용해 주세요.

플랫폼 재시작

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh

내부 컴포넌트를 graceful 하게 종료(drain)한 뒤 스택을 의존 순서의 역순으로 정지하고, 다시 depends_on 순서로 기동한 다음 준비될 때까지 기다립니다.

env.sh 변경, 운영 중 발생한 일시적 문제 해소, 정기 재시작 시에 사용합니다.

서비스 상태 확인

전체 요약

./status.sh

서비스 목록, 컨테이너 상태, health 결과, 볼륨 정보를 한 번에 보여줍니다. 종료 코드가 계약입니다 — 0 이 정상, 2 가 비정상이므로 모니터링 자동화에 그대로 쓸 수 있습니다.

운영 점검

./ops-check.sh

컨테이너 health, 헬스 API 응답, 최근 critical 로그를 함께 검사합니다. 여덟 컨테이너를 모두 훑습니다.

호스트 측 리소스 확인

docker stats --no-stream        # 컨테이너별 CPU / 메모리
docker ps                       # 컨테이너 상태

컨테이너마다 mem_limit 이 따로 걸려 있으므로, 어느 컨테이너가 한계에 닿았는지 개별로 확인할 수 있습니다. 앱별 한계값은 환경 변수 레퍼런스에 있습니다.

컨테이너 내부 접속

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh                          # 인자가 없으면 데이터레이크
./shell.sh plantpulse-server-web    # 특정 컨테이너

들어갈 수 있는 서비스 목록은 ./status.sh 로 확인합니다.

클러스터 워커는 이 목록에 없습니다

shell.sh 는 기본 스택의 서비스만 이름으로 해석합니다. 워커는 생성된 오버레이(compose/docker-compose.worker.yml)에 있으므로 docker exec -ti plantpulse-worker-<n> /bin/bash 로 접속합니다.

컴포넌트 단위 재시작

컨테이너가 나뉘어 있으므로 재시작 방법도 두 가지입니다.

앱 여섯 — 컨테이너 단위로 재시작

앱은 각자 자기 컨테이너에서 돌기 때문에, 컨테이너를 다시 띄우는 것이 곧 그 앱의 재시작입니다. 다른 앱과 인프라는 영향을 받지 않습니다.

cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

컨테이너	무엇이 도나
plantpulse-server-web	웹 콘솔
plantpulse-batch-web	배치
plantpulse-warehouse	데이터 웨어하우스
plantpulse-plugin-opcua-server	OPC-UA 플러그인
plantpulse-plugin-aasx-server	AASX 플러그인
plantpulse-ha	이중화 복구 데몬

docker compose restart 는 의존 순서를 지키지 않습니다

여러 앱을 함께 되살려야 한다면 ./restart.sh 로 스택 전체를 재시작하는 편이 안전합니다. 기동 순서는 plantpulse-server-web → plantpulse-batch-web → 나머지 넷입니다.

데이터레이크 안 컴포넌트 — 컨테이너 내부 스크립트

스토리지·분석·메시징 같은 인프라 컴포넌트는 plantpulse-datalake 컨테이너 한 개 안에서 함께 돌기 때문에, 컨테이너 안으로 들어가 개별 스크립트를 사용합니다.

# 호스트에서 데이터레이크 진입
./shell.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

스크립트	대상
pd restart storage	Cassandra, PostgreSQL, Valkey, MinIO
pd restart analytics	Spark, Hive, Kyuubi, Gravitino
pd restart messaging	Kafka, MQTT
pd restart timeseries	시계열 엔진 및 UI
pd restart workflow	Temporal, Kestra
pd restart cep	복합 이벤트 처리 엔진
pd restart data-gateway	데이터 조회 게이트웨이
pd restart sql	SQL 쿼리 도구
restart-monitor.sh	시스템 모니터링

참고: 인프라 컴포넌트를 재시작한 경우, 그 컴포넌트에 의존하는 앱 컨테이너도 함께 재시작해 주시는 것이 좋습니다.

앱 재시작 스크립트를 데이터레이크 안에서 실행하지 마세요

restart-server.sh · restart-batch.sh · restart-warehouse.sh · restart-opcua-server.sh · restart-aasx-server.sh 는 스크립트 파일 자체는 남아 있지만, 각 앱의 자기 컨테이너 안에서만 의미가 있습니다. 데이터레이크 컨테이너에는 그 앱의 실행 파일이 없으므로 «모듈이 없다»는 오류로 끝납니다. 앱은 위의 컨테이너 단위 재시작을 사용해 주세요.

플랫폼 업데이트

새 이미지가 릴리즈되면 아래 명령으로 업데이트합니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./update.sh

자동 수행 순서:

1. 새 이미지 docker pull
2. 기존 컨테이너 graceful 종료
3. 새 이미지로 컨테이너 재생성
4. health 검증 — 실패 시 이전 이미지로 자동 rollback

대상 태그는 PP_IMAGE_TAG(기본 latest)가 정합니다. 데이터는 볼륨에 별도 저장되므로 업데이트 중에도 안전하게 보존됩니다.

로그 관리

로그 보기 — logs.sh

cd /opt/kopens/plantpulse-platform-docker/bin

./logs.sh                             # 전체 컨테이너를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh plantpulse-server-web       # 그 컨테이너의 로그
./logs.sh cassandra                   # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list                      # 볼 수 있는 대상 전체 목록
./logs.sh -n 500 cep                  # 500줄만
./logs.sh -f plantpulse-server-web    # 계속 따라가기 (Ctrl-C 로 종료)

기본은 「한 번 출력하고 끝」입니다

logs.sh 는 마지막 N줄(기본 200)을 찍고 종료합니다. 계속 따라가려면 -f 를 붙이세요. --no-follow 는 호환을 위해 받아 주지만 지금은 그것이 기본이라 붙일 필요가 없습니다.

어느 컨테이너인지 모를 때는 인자 없이

문제가 생겼을 때 그 문제가 어느 컨테이너에 있는지 미리 알기 어렵습니다. 인자 없이 실행하면 여덟 컨테이너의 로그가 시간순으로 섞여 나오므로, 한 컨테이너만 보다가 정작 원인을 놓치는 일이 없습니다.

--list 는 compose 에서 서비스 목록을, 데이터레이크 컨테이너에서 컴포넌트 로그 디렉토리를 직접 읽어 보여줍니다. 손으로 관리하는 목록이 아니라 그 시점의 실제 목록입니다.

컨테이너 내부 로그 디렉토리

데이터레이크 컨테이너 안의 컴포넌트별 로그 경로입니다. (./shell.sh 로 진입 후 확인)

모듈	로그 경로
Valkey	plantpulse-storage/cache/valkey/logs/system.log
PostgreSQL	plantpulse-storage/db/postgres/logs/system.log
Cassandra	plantpulse-storage/db/cassandra/logs/system.log
MinIO	plantpulse-storage/object/minio/logs/system.log
Gravitino	plantpulse-analytics/gravitino/logs/system.log
Hive	plantpulse-analytics/hive/logs/system.log
Spark	plantpulse-analytics/spark/logs/system.log
Kyuubi	plantpulse-analytics/kyuubi/logs/system.log
시계열 엔진	plantpulse-timeseries/engine/logs/system.log
Kafka	plantpulse-messaging/kafka/logs/server.log
MQTT	plantpulse-messaging/mqtt/logs/hivemq.log
Temporal	plantpulse-workflow/temporal/logs/system.log
Kestra	plantpulse-workflow/kestra/logs/system.log
CEP	plantpulse-cep/logs/system.log
Data Gateway	plantpulse-data-gateway/logs/system.log
SQL	plantpulse-sql/logs/system.log
Monitor	plantpulse-monitor/logs/system.log

경로 기준은 /opt/kopens/plantpulse-platform/ 입니다. 앱 여섯의 로그는 각자의 컨테이너 안에 있으므로 ./logs.sh <컨테이너> 로 보는 편이 빠릅니다.

로그 호스트로 복사

cd /opt/kopens/plantpulse-platform-docker/bin
./tools/copy-log-to-local.sh

장애 진단

cd /opt/kopens/plantpulse-platform-docker/bin
./doctor.sh

진단 tarball(/tmp/pp-doctor-<호스트>-<타임스탬프>.tar.zst)을 만듭니다. 모든 컨테이너의 상태·health probe 출력·로그와 설정, 호스트 환경을 담으며, 비밀번호와 키는 마스킹됩니다. 시스템은 전혀 변경하지 않습니다.

생성된 tarball 을 KOPENS 기술 지원팀에 전달하시면 신속한 분석이 가능합니다.

워커 관리 (클러스터 환경)

마스터 노드 하나로 운영하다가 처리량 확장이 필요한 경우 워커 컨테이너를 추가합니다. 워커 목록의 정본은 compose/workers.roster 이며(한 줄에 <id> <ip>), 오버레이 compose 파일은 여기서 생성됩니다.

cd /opt/kopens/plantpulse-platform-docker

# 추가 — roster 등록 → 오버레이 재생성 → 볼륨 → pull → up → 링 조인 확인
bin/worker-add.sh                  # 빈 id·주소 자동 선택
bin/worker-add.sh 3                # id 지정
bin/worker-add.sh 3 10.99.0.103    # id·주소 지정

# 진입
docker exec -ti plantpulse-worker-3 /bin/bash

# 제거 — 반드시 이 순서
bin/worker-decommission.sh 3       # 데이터 이관 + 링 이탈 확인 + 복제 슬롯 정리
bin/worker-remove.sh               # 그 다음에 컨테이너 제거

살아 있는 워커에 docker rm 은 제거가 아니라 «유기» 입니다

Cassandra 는 그 노드의 토큰 레인지와 host id 를 계속 붙들고 있고(RF=3 이면 QUORUM 이 그대로 성립해 아무 경보도 뜨지 않습니다), 마스터는 그 워커의 PostgreSQL 물리 복제 슬롯을 놓지 않아 디스크가 찰 때까지 WAL 을 고정합니다. 반드시 worker-decommission.sh 를 먼저 실행해 주세요 — worker-remove.sh 는 컨테이너가 돌고 있으면 거부합니다.

삭제된 워커 스크립트

worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh 는 2026-08-31 에 삭제되었습니다. 손으로 관리하던 워커 목록을 전제로 만들어진 것들이라 roster 방식으로 바꾸면서 없앴습니다. 대체는 각각 worker-add.sh(pull 포함) · compose 동사 · compose pull+up -d · docker exec 입니다.

자세한 내용은 클러스터 설치 페이지를 참고해 주세요.

설치 후 초기 접속

항목	값
웹 콘솔 URL	https://[서버IP] (80/443)
관리 UI URL	https://[서버IP]:7443
모니터 UI URL	https://[서버IP]:4950
기본 관리자 ID	admin
기본 비밀번호	admin123!

보안 안내: 최초 로그인 후에는 보안을 위해 기본 비밀번호를 변경해 주시는 것을 권장합니다. → 초기 비밀번호

노드 관리 스크립트 (데이터레이크 컨테이너 내부)

Cassandra 및 데이터베이스 관리는 plantpulse-datalake 컨테이너 안의 pd CLI(/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd)가 담당합니다. ./shell.sh 로 진입한 뒤 사용해 주세요.

Cassandra 관리

스크립트	설명	사용 시기
pd node status	클러스터 상태 확인	정기 점검, 문제 확인 시
pd node info	노드 상세 정보	노드 설정 확인 시
pd node compact	수동 컴팩션 실행	디스크 공간 확보 시
pd node compactionstats	컴팩션 진행 상태 확인	성능 점검 시
pd node flush	Memtable 플러시	메모리 정리 시
pd node drain	노드 Drain (안전한 종료 준비)	노드 종료 전
pd node repair	노드 데이터 복구/동기화	데이터 불일치 시
pd node repair-table	특정 테이블 복구	테이블 단위 복구
pd node cleanup	노드 정리 (불필요 데이터 삭제)	노드 변경 후
pd node remove	클러스터에서 노드 제거	노드 해제 시
pd node add	클러스터에 노드 추가	확장 시
pd node upgrade	노드 업그레이드	버전 업그레이드 시
pd node tpstats	스레드풀 통계	성능 분석 시
pd node proxyhistograms	프록시 히스토그램	지연 분석 시
pd node table-histograms	테이블 히스토그램	테이블 성능 분석
pd node table-stats	테이블 통계	데이터 크기/건수 확인
pd node sstable-size	SSTable 크기 확인	디스크 사용량 확인
pd node cache-clear	캐시 초기화	캐시 문제 시
pd node topic	Kafka 토픽 관리	메시징 점검 시
pd node disk	디스크 사용량 확인	용량 점검 시
pd node errors	에러 로그 확인	에러 진단 시
pd node train-zstd	ZStandard 압축 학습	압축 최적화 시
pd node init-cms	CMS 초기화	초기 설정 시

데이터베이스 접속

스크립트	설명
pd node psql	PostgreSQL 셸 접속 (메타데이터 DB)
pd node cql	Cassandra CQL 셸 접속 (시계열 DB)

설정 스크립트

스크립트	설명
configure.sh	데이터레이크 설정 생성 (env 기반으로 각 서비스 설정 자동 생성)
prepared.sh	시작 전 환경 검증 및 준비 (필수 디렉토리, 권한 등 확인)

env-reset.sh 를 컨테이너 안에서 실행하지 마세요

env-reset.sh 는 모든 PP_* 를 unset 한 뒤 env.sh 를 다시 읽는 개발 전용 도구입니다. 데이터레이크 컨테이너 안에서 실행하면 compose 가 주입한 값까지 사라지고 이미지 내장 기본값으로 되돌아갑니다.

바이너리 설치 환경

현재 릴리즈는 바이너리(네이티브) 설치를 지원하지 않습니다

현행 출하본은 위의 Docker Compose 스택 하나입니다. 바이너리 설치로 구축된 기존 시스템의 운영 명령은 바이너리 설치 페이지에 남겨 두었으니 그쪽을 참고해 주세요. 신규 구축에는 사용하지 말아 주세요.

자주 쓰는 명령 요약

cd /opt/kopens/plantpulse-platform-docker/bin

./preflight.sh            # 설치 전 비파괴 사전 점검
./install.sh              # 최초 설치 (OS+Docker+방화벽+스택)
./up.sh                   # 기동 — 준비될 때까지 대기 (0 = 준비 완료)
./down.sh                 # 정지 (상태 보존)
./restart.sh              # graceful 재시작 (drain + 준비 대기)
./status.sh               # 서비스 / health / 볼륨 요약 (0=정상 / 2=비정상)
./logs.sh [서비스]        # 로그 보기 — 1회 출력. -f 로 따라가기 (인자 없으면 전체, 목록은 --list)
./shell.sh [서비스]       # 컨테이너 bash 진입
./ops-check.sh            # 운영 health + critical log 점검
./update.sh               # 이미지 갱신 (pull + recreate + rollback)
./remove.sh               # 컨테이너 제거 (볼륨은 보존)
./backup.sh               # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh               # 장애 진단 tarball 생성
./passwd.sh --list        # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh    # 스택 전체 준비 판정

모든 동사가 --help 를 지원합니다.