시작 가이드

개요

원라인 설치 또는 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	데이터레이크 메모리 상한	96G(최소치, 호스트 RAM 의 90% 를 넘지 않음 — 호스트 107G 미만은 사양 미달)
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        (healthy 까지)
      │
plantpulse-datalake     (healthy 까지)
      │
plantpulse-server-web   (healthy 까지) ──── plantpulse-proxy
      │
plantpulse-batch-web    (healthy 까지)
      │
      ├── plantpulse-warehouse
      ├── plantpulse-plugin-opcua
      ├── plantpulse-plugin-aasx
      └── plantpulse-ha        (이 넷은 서로 순서가 없습니다)

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

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

소요 시간

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

실측(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 을 서비스하는지까지 봅니다.

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) 이면 정상입니다.

플랫폼 중지

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-web	데이터 웨어하우스
plantpulse-plugin-opcua	OPC-UA 플러그인
plantpulse-plugin-aasx	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	Aster TSDB, PostgreSQL, Valkey, RustFS
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 admin-api	관리 콘솔 API (2026-09-03 까지 «monitor»)

받는 이름은 services/order.txt 에 있는 것뿐입니다 — storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api. 그 밖의 이름은 unknown service 로 끝납니다. SQL 쿼리 도구(Kyuubi·Hive)는 따로 있지 않고 analytics 에 들어 있습니다.

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

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

restart-server.sh · restart-batch.sh · restart-warehouse.sh 는 파일이 남아 있지만 호스트의 bin/ 에 있고, 각 앱의 자기 컨테이너를 상대로만 의미가 있습니다. 데이터레이크 컨테이너 안에서 부르면 그 앱의 실행 파일이 없어 «모듈이 없다»로 끝납니다.

restart-opcua-server.sh 와 restart-aasx-server.sh 는 더 이상 없습니다. OPC-UA 와 AAS 는 각각 plantpulse-plugin-opcua · plantpulse-plugin-aasx 라는 자기 컨테이너로 떠 있으므로, 컨테이너를 직접 재시작하십시오.

docker restart plantpulse-plugin-opcua
docker restart plantpulse-plugin-aasx

플랫폼 업데이트

새 판이 릴리즈되면 설치 원라이너를 같은 서버에서 다시 실행합니다. 새 판의 운영 스크립트 · compose · 이미지가 함께 들어오고, 데이터는 볼륨에 그대로 남습니다.

sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash

./update.sh 는 공식 업그레이드 절차가 아닙니다 — 이미지만 바꾸고 새 판에 생긴 서비스를 모릅니다. 하기 전에 할 일과 확인 방법은 업그레이드에 있습니다.

로그 관리

로그 보기 — 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
Aster TSDB	plantpulse-storage/db/cassandra/logs/system.log
RustFS	plantpulse-storage/object/rustfs/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
관리 콘솔 API	plantpulse-datalake-admin-api/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 은 제거가 아니라 «유기» 입니다

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

스크립트를 쓰면 RF 는 알아서 내려갑니다

worker-decommission.sh 가 안에서 pd node rf <남는 수> 를 먼저 부릅니다. 손으로 pd node remove 를 치는 경우에만 순서를 직접 지켜야 합니다 → pd node rf

:::

삭제된 워커 스크립트

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] (웹 콘솔과 같은 주소)
모니터 UI URL	https://[서버IP]:4950
기본 관리자 ID	admin
기본 비밀번호	admin123!

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

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

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

Aster TSDB 관리

스크립트	설명	사용 시기
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 rf 로 RF 를 먼저 내린 뒤에
pd node rf [--check] [노드수]	링에 맞춰 모든 키스페이스의 복제 계수를 조정	노드를 넣거나 뺄 때
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	Aster TSDB CQL 셸 접속 (시계열 DB)

자주 쓰는 명령 요약

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 점검
./remove.sh               # 컨테이너 제거 (볼륨은 보존)
./backup.sh               # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh               # 장애 진단 tarball 생성
./passwd.sh --list        # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh    # 스택 전체 준비 판정

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