Getting Started

Overview

If you installed the PlantPulse Platform via one-line install or Docker install, all operational scripts are located in the /opt/kopens/plantpulse-platform-docker/bin/ directory. This page explains how to start and operate the Platform running as a Docker Compose stack.

The Platform consists of nine containers — one certificate one-shot, one data lake, six apps, and one proxy. The complete configuration is in Docker Installation — Stack Shape.

If you are using old script names

The names on the left below no longer exist. Please use the common verbs on the right.

Old name	Use now
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	See Worker Management

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh continue to work (they provide new naming guidance, then perform the same function).

Environment Variable Setup

Before starting the Platform, verify your environment variables. Resource values are calculated automatically at installation by examining the host, so most servers require minimal adjustment.

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

Frequently adjusted items

Variable	Description	Default
PP_LANG	Platform locale (ko / en)	en
PP_TZ	Platform timezone	Asia/Seoul
DOCKER_PP_CPUS	Number of vCPUs for containers	nproc result
DOCKER_PP_MEMORY	Memory limit	90% of host RAM
DOCKER_DATALAKE_MEMORY	Data lake memory limit	80G (90% of host RAM if host is small)
DOCKER_PP_DATA_DISK_NAME	Data disk name	Auto-detection (sda if detection fails)
DOCKER_PP_EXTERNAL_IP	External advertise IP in NAT environments	Empty value

For the complete list of environment variables, see the Environment Variable Reference page.

Applying changes: After modifying env.sh, you must restart with ./restart.sh for new settings to take effect.

Password cannot be changed via env.sh

On an installed node, the secret sidecar (/etc/kopens/plantpulse-platform.env) overrides both env.sh and shell exports. For password changes, use passwd.sh in Password Rotation.

Starting the Platform

Starting after initial installation

After installation (install.sh) completes, the stack is already running. Simply verify its status.

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

Starting a stopped stack

If the stack has stopped due to ./down.sh or host reboot, restart it.

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

up.sh is idempotent and waits until ready. Exit code 0 does not mean "command succeeded" but rather "now usable."

Environment variable	Default	Meaning
PP_READY_TIMEOUT	900	Wait timeout (seconds)
PP_READY_INTERVAL	15	Check interval (seconds)
PP_WAIT=0	—	Do not wait (0 in this case is not "ready")

Volume data (pp-data, pp-temp, pp-backup, pp-security, pp-proxy-certs) is preserved. Templates and configuration are managed via host bind mount (/etc/kopens/conf).

Startup sequence

Containers start in the order defined by compose's depends_on. Since service_healthy conditions apply, startup waits for "usable" not "process started."

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        (이 넷은 서로 순서가 없습니다)

Inside the data lake container, infrastructure components boot in sequence.

Order	Category	Component
1	Storage	Valkey(Redis), PostgreSQL, Cassandra, MinIO
2	Analytics	Spark, Hadoop, Hive, Kyuubi, Gravitino
3	Time series	Time series engine, time series UI
4	Messaging	Kafka, MQTT
5	Workflow	Temporal, Kestra
6	Processing	CEP, Data Gateway, SQL, Monitor

Time required

Process startup itself takes 3–5 minutes (JVM warm-up), but a clean installation takes 15–18 minutes for all components to stabilize. Cassandra schema migration and stabilization are the slowest.

Measured (2026-08-31, 32 vCPU / 128GiB): data lake 217 seconds, web server 316 seconds. Restart with existing data is much faster.

Boot validation

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

stack-verify-boot.sh judges the entire stack, not a single container — whether the one-shot terminated normally, whether data lake and apps are running·healthy, whether the proxy services 443. It recognizes node tier (PP_TIER — FULL / DATALAKE / APP) and validates only components that exist in that tier.

up.sh and restart.sh poll until this script passes, which is why their exit code 0 means "now usable."

Confirming normal startup

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

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

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

# Docker 상태
docker ps

If eight are (healthy) in docker ps and plantpulse-certs is Exited (0), all is normal. The one-shot's Exited (0) is a success state, not a failure.

Stopping the Platform

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

Safely stops the stack. Data is preserved in Docker volumes, so restarting with ./up.sh retains the previous state.

Caution: docker kill or forced host shutdown can break data consistency. Always use ./down.sh.

Restarting the Platform

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

Gracefully drains internal components, stops the stack in reverse dependency order, boots again in depends_on order, then waits until ready.

Use this when changing env.sh, resolving transient issues during operation, or for scheduled restarts.

Checking service status

Overall summary

./status.sh

Shows service list, container status, health results, and volume information in one view. Exit code is contractual — 0 is normal, 2 is abnormal, so it integrates directly into monitoring automation.

Operational inspection

./ops-check.sh

Checks container health, health API responses, and recent critical logs together. Examines all eight containers.

Checking host-side resources

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

Each container has mem_limit set separately, so you can check individually which container is approaching its limit. Per-app limits are in Environment Variable Reference.

Accessing container interiors

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

Check the list of accessible services with ./status.sh.

Cluster workers are not in this list

shell.sh interprets service names from only the base stack. Workers live in generated overlays (compose/docker-compose.worker.yml), so access them via docker exec -ti plantpulse-worker-<n> /bin/bash.

Per-component restart

Because containers are separated, restart methods differ.

Six apps — restart per container

Apps run in their own containers, so restarting a container restarts that app. Other apps and infrastructure are unaffected.

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

Container	What runs
plantpulse-server-web	Web console
plantpulse-batch-web	Batch
plantpulse-warehouse	Data warehouse
plantpulse-plugin-opcua-server	OPC-UA plugin
plantpulse-plugin-aasx-server	AASX plugin
plantpulse-ha	Redundancy recovery daemon

docker compose restart does not respect dependency order

If you must revive multiple apps together, it is safer to restart the entire stack with ./restart.sh. Startup order is plantpulse-server-web → plantpulse-batch-web → the other four.

Data lake components — scripts inside the container

Infrastructure components like storage, analytics, and messaging run together inside a single plantpulse-datalake container, so enter the container and use individual scripts.

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

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

Script	Target
pd restart storage	Cassandra, PostgreSQL, Valkey, MinIO
pd restart analytics	Spark, Hive, Kyuubi, Gravitino
pd restart messaging	Kafka, MQTT
pd restart timeseries	Time series engine and UI
pd restart workflow	Temporal, Kestra
pd restart cep	Complex event processing engine
pd restart data-gateway	Data query gateway
pd restart sql	SQL query tool
restart-monitor.sh	System monitoring

Note: When restarting infrastructure components, it is good practice to also restart app containers that depend on them.

Do not run app restart scripts inside the data lake

restart-server.sh · restart-batch.sh · restart-warehouse.sh · restart-opcua-server.sh · restart-aasx-server.sh have script files but are meaningful only inside each app's own container. The data lake container lacks that app's executable, so it exits with "module not found." Use the container-level restart method above for apps.

Updating the Platform

When a new image is released, update using the command below.

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

Automatic procedure:

1. Pull new image docker pull
2. Gracefully shut down existing containers
3. Recreate containers with new image
4. Health validation — auto-rollback to previous image on failure

Target tag is set by PP_IMAGE_TAG (default latest). Data is stored separately in volumes, so it is safely preserved during updates.

Log management

Viewing logs — 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 로 종료)

Default is "print once and exit"

logs.sh prints the last N lines (default 200) and exits. To follow continuously, append -f. --no-follow is accepted for compatibility, but is now the default so it need not be appended.

When unsure which container

When a problem occurs, it is hard to know in advance which container is at fault. Running without arguments mixes logs from all eight containers in time order, so you won't miss the actual cause by watching just one.

--list reads the service list from compose and component log directories from the data lake container directly. It shows the actual list at that moment, not a manually maintained list.

Log directories inside containers

Component log paths inside the data lake container. (Enter with ./shell.sh to check)

Module	Log path
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
Time series engine	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

Paths are relative to /opt/kopens/plantpulse-platform/. The six apps' logs are in their own containers, so viewing via ./logs.sh <컨테이너> is faster.

Copying logs to host

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

Troubleshooting

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

Creates a diagnostic tarball (/tmp/pp-doctor-<호스트>-<타임스탬프>.tar.zst). It contains status, health probe output, logs and config from all containers, and host environment—with passwords and keys masked. The system is not modified at all.

Provide the generated tarball to the KOPENS technical support team for prompt analysis.

Worker management (cluster environments)

When operating with a single master node and expansion capacity is needed, add worker containers. The authoritative source for the worker list is compose/workers.roster (one per line <id> <ip>), and overlay compose files are generated from there.

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               # 그 다음에 컨테이너 제거

Removing docker rm from a live worker is "abandonment," not removal

Cassandra retains that node's token range and host id (if RF=3, QUORUM still holds — no alarms sound), and the master does not release that worker's PostgreSQL physical replication slot, so WAL is pinned until disk fills. Always run worker-decommission.sh first — worker-remove.sh will refuse if the container is running.

Deleted worker scripts

worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh were deleted on 2026-08-31. They assumed manually maintained worker lists; switching to roster format eliminated them. Replacements are worker-add.sh (including pull) · compose verb · compose pull+up -d · docker exec respectively.

For details, see the Cluster Installation page.

Initial access after installation

Item	Value
Web console URL	https://[서버IP] (80/443)
Admin UI URL	https://[서버IP]:7443
Monitor UI URL	https://[서버IP]:4950
Default admin ID	admin
Default password	admin123!

Security note: After first login, we recommend changing the default password for security. → Initial Password

Node management scripts (inside data lake container)

Cassandra and database management are handled by the pd CLI (/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd) inside the plantpulse-datalake container. Enter with ./shell.sh and use it.

Cassandra management

Script	Description	When to use
pd node status	Check cluster status	Regular inspections, troubleshooting
pd node info	Node detailed information	Checking node settings
pd node compact	Run manual compaction	Reclaiming disk space
pd node compactionstats	Check compaction progress	Performance inspection
pd node flush	Flush Memtable	Cleaning memory
pd node drain	Node Drain (safe shutdown prep)	Before node shutdown
pd node repair	Node recovery/sync	Data mismatch
pd node repair-table	Specific table recovery	Table-level recovery
pd node cleanup	Node cleanup (delete unnecessary data)	After node changes
pd node remove	Remove node from cluster	Decommissioning node
pd node add	Add node to cluster	Expansion
pd node upgrade	Node upgrade	Version upgrade
pd node tpstats	Thread pool statistics	Performance analysis
pd node proxyhistograms	Proxy histogram	Latency analysis
pd node table-histograms	Table histogram	Table performance analysis
pd node table-stats	Table statistics	Data size/record count
pd node sstable-size	SSTable size	Disk usage
pd node cache-clear	Clear cache	Cache issues
pd node topic	Kafka topic management	Messaging inspection
pd node disk	Check disk usage	Capacity inspection
pd node errors	Check error log	Error diagnosis
pd node train-zstd	ZStandard compression tuning	Compression optimization
pd node init-cms	Initialize CMS	Initial setup

Database access

Script	Description
pd node psql	PostgreSQL shell access (metadata DB)
pd node cql	Cassandra CQL shell access (time series DB)

Configuration scripts

Script	Description
configure.sh	Generate data lake config (auto-create service configs from env)
prepared.sh	Pre-startup validation and prep (check required directories, permissions, etc.)

Do not run env-reset.sh inside the container

env-reset.sh is a development-only tool that unsets all PP_* and re-reads env.sh. Running it inside the data lake container erases values injected by compose and reverts to image-built defaults.

Binary installation environment

The current release does not support binary (native) installation

The current distribution is the Docker Compose stack described above. Operational commands for existing systems built with binary installation are preserved on the Binary Installation page; refer to that. Do not use for new builds.

Frequently used commands summary

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    # 스택 전체 준비 판정

All verbs support --help.