Binary Installation

The current release does not support binary (native) installation

The current production build is a single Docker Compose stack — consisting of one certificate setup, one data lake, six apps, and one proxy (see what gets installed).

This page is retained for those operating existing systems built with binary installation. For new deployments, use one-line installation or Docker installation.

Additionally, the content below was written before the container migration and may differ from the current product. If you encounter issues in a binary environment, contact webmaster@kopens.com.

Overview

This page guides you through the binary (native) installation procedure for deploying PlantPulse Platform directly on top of an OS. The tar.gz package is extracted and a single setup script configures all OS dependencies, infrastructure, and applications.

To install with data lake/application 2-node separation (PP_TIER), see 2-node split installation. This document covers single-box (FULL) binary installation.

Installation method comparison

Item	Binary Installation	One-line / Docker Installation
Installation time	20–40 minutes	10–20 minutes
Environment dependencies	Packages installed on host OS	All included in containers
Resource isolation	Shared with host	Isolated in containers
Update	tar.gz redistribution + configure	update.sh one line
Rollback	Manual restore from backup	Automatic rollback to previous image
Air-gapped network	setup-offline.sh supported	airgap-load.sh supported
Host OS impact	Direct	Minimal

Supported environments

OS	Version	Verified
Oracle Linux	8.x, 9.x	✓
RHEL / Rocky Linux	8.x, 9.x	✓
Amazon Linux	2, 2023	✓
Ubuntu	22.04+	✓

Hardware recommendations

Category	Minimum	Standard	Large
CPU	16 vCPU	32 vCPU	48+ vCPU
Memory	64GB	128GB	200GB+
Data disk	200GB	1TB	4TB+
Disk IOPS	NVMe SSD recommended	NVMe SSD	NVMe SSD
Network	1Gbps	10Gbps	10Gbps

Validated environment (reference): The production validation environment runs on 48 vCPU / 188GB RAM / 4.8TB NVMe SSD, RHEL 9 / Temurin OpenJDK 21 LTS.

Installation procedure overview

1. Prerequisites

1.1 Obtain root privileges

Installation proceeds with root privileges. To operate as a non-root user, a separate privilege separation procedure is required after installation (contact operations team).

sudo -i

1.2 Mount data disk

Mount a dedicated disk to /data1 for large time series data storage.

# 사용 가능한 디스크 확인
lsblk

# 예: /dev/sdb 를 ext4 로 포맷 후 /data1 에 마운트
mkfs.ext4 /dev/sdb
mkdir -p /data1
mount /dev/sdb /data1

# 부팅 시 자동 마운트
echo "/dev/sdb  /data1  ext4  defaults  0 0" >> /etc/fstab

Disk separation recommended: Separating the OS disk from the data disk simplifies backup, expansion, and fault isolation. Even in smaller environments, use a separate disk or separate LV when possible.

1.3 Time synchronization

Distributed components (Cassandra, Kafka, etc.) are sensitive to time accuracy between nodes. NTP synchronization is mandatory.

# RHEL 계열
dnf install -y chrony
systemctl enable --now chronyd
chronyc tracking

1.4 SELinux / Firewall

setup.sh automatically switches SELinux to permissive and opens the required firewall ports. For corporate and cloud firewalls above, separately add allow rules by referring to the port configuration page.

2. Download and extract package

Place the plantpulse-platform-YYYY.MM.tgz package received from the KOPENS operations team in /opt/kopens/.

mkdir -p /opt/kopens
cd /opt/kopens

# scp 또는 USB / 내부 미러로 패키지 이전
# 예시: scp 로 받은 파일을 풀기
tar -xzvf plantpulse-platform-2026.05.tgz

# 결과 디렉토리 확인
ls /opt/kopens/plantpulse-platform/

After extraction, the following structure is created.

/opt/kopens/plantpulse-platform/
├── plantpulse-startup/            # 모든 운영 스크립트 + startup.jar
│   ├── env.sh                     # 전역 환경 변수 (★ 검토 필요)
│   ├── start.sh / stop.sh         # 시작 / 정지
│   ├── start-daemon.sh            # 데몬 모드 시작
│   ├── restart.sh                 # stop → clean → start-daemon
│   ├── status.sh                  # 포트 기반 상태 점검
│   ├── configure.sh               # 템플릿 → 실제 설정 생성
│   ├── prepare-ssl.sh             # TLS 인증서 생성
│   ├── restart-*.sh               # 모듈별 재시작
│   ├── node-*.sh                  # Cassandra 운영
│   ├── log-viewer.sh              # 통합 로그 뷰어
│   └── ...
├── plantpulse-server/             # 웹 콘솔 (Tomcat 기반)
├── plantpulse-batch/              # 배치 처리
├── plantpulse-cep/                # 복합 이벤트 처리
├── plantpulse-data-gateway/       # 데이터 게이트웨이
├── plantpulse-sql/                # SQL 쿼리 서비스
├── plantpulse-monitor/            # 모니터링
├── plantpulse-warehouse/          # 데이터 웨어하우스
├── plantpulse-plugin/             # OPC-UA / AAS 산업 플러그인
├── plantpulse-storage/            # Cassandra / PostgreSQL / Valkey / MinIO
├── plantpulse-messaging/          # Kafka / MQTT(HiveMQ) / STOMP(ActiveMQ)
├── plantpulse-analytics/          # Spark / Hive / Kyuubi / Gravitino / Hadoop
├── plantpulse-workflow/           # Temporal / Kestra
├── plantpulse-timeseries/         # 시계열 엔진 + UI
├── tools/                         # OS 의존성 / JDK / DB 클라이언트 / 설정 템플릿
│   ├── setup.sh                   # 온라인 셋업
│   ├── setup-offline.sh           # 폐쇄망 셋업
│   ├── java/                      # OpenJDK
│   ├── postgresql/                # psql 클라이언트
│   ├── valkey/                    # redis-cli
│   ├── cron/ firewall/ ssl/ swap/ ntp/ ...
│   └── ...
├── offline/                       # 폐쇄망 설치 리소스 (RPM 리포 + wheels)
└── backup/                        # 자체 백업 디렉토리

3. Run setup script

tools/setup.sh handles OS package installation, JDK installation, data directory creation, and firewall / SELinux / NTP / limits / sysctl configuration all at once.

cd /opt/kopens/plantpulse-platform/tools
./setup.sh

Setup interactive input

setup.sh prompts for the following information:

Item	Description	Example
Node mode	MASTER (single/cluster master) or WORKER	MASTER
HOST IP	Server internal IP	192.168.0.41
SERVICE IP	External access IP or domain	192.168.0.41
MASTER IP (WORKER only)	Master node IP	192.168.0.41
Data disk name	Based on lsblk output	sdb
Data root path	Data storage directory	/data1

Operations performed automatically by setup

Execution time: First run takes approximately 15–30 minutes (including OS updates, package installation, and infrastructure component setup).

4. Environment variable configuration (override with env.local.sh)

/opt/kopens/plantpulse-platform/plantpulse-startup/env.sh is the single configuration source (canonical defaults) for the entire platform. All module template configuration files reference this value.

The full list of PP_* variables (defaults and descriptions) is organized by category in the environment variable reference.

⚠️ Do not edit env.sh directly. For values specific to your server (IP, resources, passwords, and other machine-specific values), write them to env.local.sh in the same directory. This is the standard pattern for binary installation.

Category	Docker installation	Binary installation (this page)
Configuration file	Directly modify bin/env.sh environment variables in DOCKER_PP_*	Write overrides to plantpulse-startup/env.local.sh
Original preservation	—	Keep env.sh original intact, so updates are safe

Why env.local.sh?

env.sh reads env.local.sh first at the top. All variables in env.sh follow the ${PP_XXX:-기본값} pattern, so values declared in env.local.sh as export PP_XXX=... always override defaults.

• env.local.sh is not included in git and will not be overwritten during platform updates (tar.gz redistribution). → Once written, configuration persists after updates.
• Conversely, if you modify env.sh directly, new env.sh replaces it during updates, losing your changes.

Write env.local.sh

If the file does not exist, create it. Write only the variables you need to change as export.

cd /opt/kopens/plantpulse-platform/plantpulse-startup
vi env.local.sh

#!/bin/bash
# env.local.sh — 이 서버 전용 오버라이드 (env.sh 가 먼저 source 하여 우선 적용)
# 여기에 적은 값만 기본값을 덮어씁니다. 적지 않은 변수는 env.sh 기본값을 그대로 사용합니다.

export PP_HOST_IP="192.168.0.41"        # 서버 내부 IP (hostname -I)
export PP_SERVICE_IP="192.168.0.41"     # 브라우저 접속 IP/도메인 (단일 서버면 HOST_IP 와 동일)
export PP_MASTER_IP="192.168.0.41"      # 마스터 IP (단일 서버면 HOST_IP 와 동일)
export PP_DATA_DISK_NAME="sdb"          # 데이터 디스크 이름 (lsblk)
export PP_DATA_DIR="/data1/pp-data"     # 데이터 저장 경로

export PP_CLUSTER_CORES="30"            # 분산 분석에 할당할 코어 (아래 4.1 사이징표 참고)
export PP_CLUSTER_MEMORY_BY_CORE="2G"   # 코어당 메모리

After saving, you must rerun ./configure.sh to apply new values to each module's configuration (step 5). Each time you change something, the pattern is env.local.sh edit → ./configure.sh run.

4.1 Critical variables to verify

Category	Variable	Description	Default
Platform	PP_HOME	Installation path	/opt/kopens/plantpulse-platform
	PP_MODE	Node mode	MASTER / WORKER
Network	PP_HOST_IP	Server internal IP	192.168.0.41
	PP_SERVICE_IP	External access IP	192.168.0.41
	PP_MASTER_IP	Master IP	192.168.0.41
	PP_PUBLIC_IP	External public IP (NAT)	${PP_HOST_IP}
Data	PP_DATA_DIR	Data storage path	/data1/pp-data
	PP_TEMP_DIR	Temporary file path	/data1/pp-temp
	PP_BACKUP_DIR	Backup path	/data1/pp-backup
Resources	PP_CLUSTER_CORES	Cores allocated for distributed analytics	30
	PP_CLUSTER_MEMORY_BY_CORE	Memory per core	2G
Locale	PP_LANG	Locale (ko / en)	en
	PP_TZ	Timezone	Asia/Seoul

The table above is a reference to see variable names and defaults. The values you actually change go into env.local.sh as export (do not modify env.sh directly ✗). The HOST IP / SERVICE IP / disk name you entered in step 3 are already reflected; this step is to verify those values are correct and add only missing items to env.local.sh.

How do I find the values? (confusing items)

# IP 확인 (PP_HOST_IP / PP_SERVICE_IP)
hostname -I | awk '{print $1}'          # 서버 내부 IP
ip -4 addr | grep inet                  # 외부 접속용 IP를 따로 골라야 할 때

# 데이터 디스크 / 코어 / 메모리
lsblk                                   # 데이터 디스크명 (sdb, nvme0n1 …)
nproc                                   # 전체 CPU 코어 수
free -g | awk '/^Mem:/{print $2"G"}'    # 전체 메모리

• PP_HOST_IP = internal IP that points to the server within the same network. For a single server, you can use the same value for PP_SERVICE_IP and PP_MASTER_IP.
• PP_SERVICE_IP = IP/domain that users enter in the browser. For NAT/cloud environments, also add the external public IP to PP_PUBLIC_IP.

Distributed analytics resource sizing (PP_CLUSTER_CORES / PP_CLUSTER_MEMORY_BY_CORE)

These two values allocate resources for distributed analytics like Spark. Do not give the entire host; reserve capacity for storage, messaging, and web servers (60–70% of total recommended).

Server spec	PP_CLUSTER_CORES	PP_CLUSTER_MEMORY_BY_CORE	Total memory used by analytics
16 cores / 64GB	10	2G	20GB
32 cores / 128GB	20	3G	60GB
48 cores / 188GB	30	4G	120GB

코어 수 × 코어당 메모리 is the total memory occupied by analytics. Adjust so this total does not exceed the server's total memory (keep 30%+ free). Exceeding it will cause OOM during startup.

4.2 Service account passwords

In production environments, you must change the following default passwords.

# env.local.sh 안에 추가
export PP_REDIS_PASSWORD=$(openssl rand -base64 18)
export PP_CASSANDRA_PASSWORD=$(openssl rand -base64 18)
export PP_PG_PASSWORD=$(openssl rand -base64 18)
export PP_MQ_PASSWORD=$(openssl rand -base64 18)
export PP_HIVE_PASSWORD=$(openssl rand -base64 18)
export PP_MINIO_PASSWORD=$(openssl rand -base64 18)
export PP_TEMPORAL_PASSWORD=$(openssl rand -base64 18)
export PP_TLS_KEYSTORE_PASSWORD=$(openssl rand -base64 18)

Recommended: Store changed passwords in an operations vault (HashiCorp Vault, AWS Secrets Manager, etc.) and use the pattern of injecting them as overrides from env.local.sh per environment.

4.3 TLS / SSL configuration

# env.local.sh 안에 추가
export PP_TLS_ENABLED=true
export PP_TLS_DOMAIN=plantpulse.io
export PP_TLS_SAN_DNS="localhost,$(hostname -f),plantpulse.io,plantpulse.kopens.com"
export PP_TLS_SAN_IPS="${PP_HOST_IP},${PP_SERVICE_IP},${PP_PUBLIC_IP},127.0.0.1,192.168.0.10"
export PP_TLS_VALID_DAYS=730

Add external IP: In NAT/cloud environments, you must specify the external IP/domain in PP_TLS_SAN_DNS / PP_TLS_SAN_IPS so client certificate validation passes.

4.4 Validation and reset

cd /opt/kopens/plantpulse-platform/plantpulse-startup

./env-validate.sh                  # env.sh + env.local.sh 최종 변수 정합성 검증
./env-reset.sh                     # env.local.sh 변경 후 템플릿 재생성이 필요할 때

env-validate.sh validates the final values after env.local.sh overrides are applied. You can check whether IP, paths, and passwords are correctly set by running this script after writing env.local.sh.

5. Apply template configuration (configure.sh)

Apply the final values from env.sh (+ env.local.sh overrides) to configuration files across all modules.

cd /opt/kopens/plantpulse-platform/plantpulse-startup
./configure.sh

configure.sh internally calls startup.jar CONFIGURE to perform the following:

1. Scan all configuration templates in the template/ directory (*.template)
2. Replace placeholders (env.sh, ${PP_HOST_IP}, etc.) with ${PP_CASSANDRA_PASSWORD} variables
3. Save to actual configuration file locations — web app services (server / batch / cep / sql / data-gateway) write to each module's config/, infrastructure modules to conf/, etc/, etc.

Web app service configurations are externalized in module config/, so configuration persists even if the web app (WAR) is redeployed.

Rerun required after changes: Whenever you modify env.local.sh, rerun ./configure.sh to apply new values to modules.

6. Prepare TLS certificates (prepare-ssl.sh)

If PP_TLS_ENABLED=true, generate certificates before the first startup.

cd /opt/kopens/plantpulse-platform/plantpulse-startup
./prepare-ssl.sh

• Generate self-signed certificate (ECDSA secp256r1)
• Create keystore / truststore (/var/security/plantpulse/)
• Generate separate OPC-UA / Kafka / MQTT / Cassandra / Web certificates
• To use external CA certificates, see security configuration page

7. Start platform

7.1 Foreground startup (initial verification)

After initial installation, it is good practice to watch startup logs directly.

/opt/kopens/plantpulse-platform/plantpulse-startup/start.sh

7.2 Background startup (production mode)

In production environments, start in daemon mode. The platform continues to run even after closing the terminal.

/opt/kopens/plantpulse-platform/plantpulse-startup/start-daemon.sh

7.3 Startup sequence

startup.jar starts components in stages according to dependency order.

Each stage automatically waits until complete, so no manual intervention is needed. Total startup takes 3–5 minutes.

7.4 Successful startup messages

═══════════════════════════════════════════════════════════════════
   ____  _             _   ____        _
  |  _ \| | __ _ _ __ | |_|  _ \ _   _| |___  ___
  | |_) | |/ _` | '_ \| __| |_) | | | | / __|/ _ \
  |  __/| | (_| | | | | |_|  __/| |_| | \__ \  __/
  |_|   |_|\__,_|_| |_|\__|_|    \__,_|_|___/\___|
                                    PLATFORM
═══════════════════════════════════════════════════════════════════
  ● Status   STARTING  [DAEMON]
  ● Host     ...
  ● URLs     https://...              (web)
═══════════════════════════════════════════════════════════════════
...
플랜트펄스 플랫폼이 정상적으로 시작되었습니다.

8. Verify installation

8.1 Check service status

/opt/kopens/plantpulse-platform/plantpulse-startup/status.sh

Each module displays as RUNNING status, along with a summary of system resource usage (CPU / Memory PSS / Disk).

=============================================================================================================
 PLANTPULSE PLATFORM - ALL SERVICE STATUS
=============================================================================================================

<SYSTEM RESOURCE OVERVIEW>
--------------------------------------------------------------------------------------------------------------
  CPU LOAD (AVG)         :   12.3% (48 cores)
  MEMORY USAGE           :   65.2% (123.1G / 188.7G)
  DATA DISK USAGE        :   45.8% (2.2T / 4.8T)
--------------------------------------------------------------------------------------------------------------

<SERVICE STATUS BY PORT>
  SERVICE                     | PORT   | STATUS   | PID     | CPU     | MEMORY (PSS)         | PROCESS
  PP_MESSAGING[KAFKA]         | 9092   | RUNNING  | 12345   |   2.3%  |     8.5G (  4.51%)   | java
  PP_STORAGE[CASSANDRA]       | 9042   | RUNNING  | 12567   |   5.1%  |    16.2G (  8.59%)   | java
  PP_SERVER                   | 80     | RUNNING  | 12890   |   1.2%  |     4.8G (  2.55%)   | java
  ...

8.2 Access web console

Connect via browser to the following address.

URL	Purpose
http://[SERVICE_IP]/	Operations console (port 80)
https://[SERVICE_IP]/	Operations console (port 443, TLS)
https://[SERVICE_IP]:7443/	Management console (separate port)

• Default admin account: admin / admin123!
• Change the password immediately after login.

8.3 Health check endpoint

Use for integration with external monitoring systems.

# 컨테이너 / 프로세스 헬스
curl -kfsS https://127.0.0.1:4950/api/health | jq

# 모니터 모듈
curl -fsS http://127.0.0.1:4949/health

Operations commands summary

cd /opt/kopens/plantpulse-platform/plantpulse-startup

./start.sh                    # 포그라운드 시작
./start-daemon.sh             # 백그라운드 시작
./stop.sh                     # 정지
./restart.sh                  # stop → clean → start-daemon
./status.sh                   # 전체 모듈 상태
./log-viewer.sh               # 통합 로그 뷰어
./log-delete.sh               # 오래된 로그 정리
./clean.sh                    # 임시 파일 정리 (정지 후)
./kill.sh                     # 강제 종료 (응답 없을 때)

# 모듈별 재시작
./restart-server.sh           # 웹 서버
./restart-storage.sh          # 스토리지
./restart-analytics.sh        # 분석
./restart-messaging.sh        # 메시징
./restart-timeseries.sh       # 시계열
./restart-workflow.sh         # 워크플로우
./restart-cep.sh              # CEP
./restart-data-gateway.sh     # 데이터 게이트웨이
./restart-monitor.sh          # 모니터
./restart-batch.sh            # 배치
./restart-warehouse.sh        # 웨어하우스
./restart-plugin.sh           # 플러그인
./restart-opcua-server.sh     # OPC-UA
./restart-aasx-server.sh      # AAS

# Cassandra 운영
./node-status.sh              # 클러스터 상태
./node-info.sh                # 노드 상세
./node-cql.sh                 # CQL 셸
./node-compact.sh             # 수동 컴팩션
./node-cleanup.sh             # 노드 정리
./node-repair.sh              # 데이터 복구

For detailed operations procedures, see startup guide and operations management pages.

Air-gapped network installation

For environments with no internet access, follow this procedure.

Create bundle from build node (internet environment)

cd /opt/kopens/plantpulse-platform/offline
./prepare-offline.sh
# 산출물: /offline-install/kopens-offline.tar.gz

The bundle includes:

• Complete /opt/kopens/plantpulse-platform/ directory
• Required RPMs (offline/repos/rpm/ + repodata/)
• Python wheels (offline/repos/python-wheels/)
• JDK / infrastructure packages (under tools/)

Transfer to air-gapped node

Transfer kopens-offline.tar.gz via USB, internal file server, scp, etc.

Install on air-gapped node

mkdir -p /opt/kopens
tar -xzvf /path/to/kopens-offline.tar.gz -C /opt/kopens/

cd /opt/kopens/plantpulse-platform/tools
./setup-offline.sh

# 환경 변수 작성 및 시작 (env.sh 직접수정 ✗ → env.local.sh 에 오버라이드)
cd /opt/kopens/plantpulse-platform/plantpulse-startup
vi env.local.sh
./configure.sh
./start-daemon.sh
./status.sh

setup-offline.sh uses only local RPM repositories to install OS dependencies and deploys infrastructure components.

Updates

Minor update (configuration / patches)

cd /opt/kopens/plantpulse-platform/plantpulse-startup
./stop.sh

# 패치 파일 적용 (운영팀이 안내한 절차에 따라)
cp -r /tmp/patch/* /opt/kopens/plantpulse-platform/

./configure.sh
./start-daemon.sh
./status.sh

Major update (full redistribution)

# 1. 현재 데이터 / 설정 백업
./stop.sh
cp -a /opt/kopens/plantpulse-platform /opt/kopens/plantpulse-platform.bak-$(date +%Y%m%d)
tar -czf /data1/pp-backup/pre-update-$(date +%Y%m%d).tar.gz /data1/pp-data /data1/pp-backup

# 2. 새 tar.gz 풀기 (env.local.sh / 데이터는 보존)
#    설정값은 env.local.sh 에 있으므로 그 파일만 보존하면 됩니다.
#    env.sh 는 새 버전으로 갱신되어도 무방합니다(기본값 정본).
cd /opt/kopens
tar -xzvf plantpulse-platform-NEW.tgz --exclude='plantpulse-platform/plantpulse-startup/env.local.sh'

# 3. 재구성 및 시작
cd /opt/kopens/plantpulse-platform/plantpulse-startup
./configure.sh
./start-daemon.sh

# 4. 문제 시 롤백
./stop.sh
rm -rf /opt/kopens/plantpulse-platform
mv /opt/kopens/plantpulse-platform.bak-YYYYMMDD /opt/kopens/plantpulse-platform
cd /opt/kopens/plantpulse-platform/plantpulse-startup
./start-daemon.sh

Data protection: Before a major update, perform full backups of /data1/pp-data and /data1/pp-backup and store them on separate disks or external storage.

Troubleshooting essentials

Symptom	First action
Some modules STOPPED after startup	Check which module with ./status.sh then ./restart-<module>.sh
Memory shortage / OOMKilled	Adjust env.local.sh values PP_CLUSTER_CORES / PP_CLUSTER_MEMORY_BY_CORE then ./configure.sh
Port conflict	Identify occupying process with ss -tlnp and kill it, or change port in env.local.sh then ./configure.sh
Disk full	Clean up node-cleanup.sh / node-compact.sh or old backups
Won't start	Check ./log-viewer.sh or tail -F /var/log/plantpulse-startup.log
Forced shutdown needed	./kill.sh (last resort — data corruption risk)

For detailed troubleshooting procedures, see troubleshooting page.

Next steps

• Startup guide — daily start / stop / restart commands
• Operations management — backup, updates, monitoring
• Cluster installation — add worker nodes
• Port configuration — firewall / network setup

Technical support

If you need assistance during installation, contact webmaster@kopens.com. Screenshots from ./log-viewer.sh or validation results from /opt/kopens/plantpulse-platform/plantpulse-startup/test/ will allow faster analysis.