ネイティブインストール — コンテナなしでホストへ直接インストール
このページでは、PlantPulse Edge を Docker なしでホスト OS 上に直接(native)インストールして運用する方式をまとめます。
ゲートウェイランタイム(Tomcat / Cassandra / Redis / HiveMQ / Time-Series-Engine / Node-RED)をそれぞれホストプロセスとして起動し、plantpulse.service (systemd) 1つがスタック全体を管理します。
- 開発 / デバッグ用ワークステーション — コードを直接配置し、JSP / クラスの hot-swap で素早く検証
- 2026.05 未満の legacy ボックスの保守 — すでに native で運用中の現場
- Docker の使用が不可なセキュリティポリシー環境
新規量産/現場1台のインストールの標準はコンテナモードです →
クイックインストール (install.sh) / Docker(コンテナ)インストール詳細。
ネイティブは plantpulse.service、コンテナは plantpulse-edge.service を使用します。
両サービスを同時に起動すると、80/443/1880/9042/12000 などのポートおよび /data1 のデータパスが競合します。
systemctl is-active plantpulse-edge.service が active であれば、そのボックスはコンテナボックスです —
ネイティブを起動する前に必ずどちらかを stop/disable してください。
1. ランタイムモデル — 何がどう動くのか
ネイティブモードでは、ゲートウェイを構成する 7つのコンポーネントをそれぞれホストプロセスとして実行します。
オーケストレーションは $PE_HOME/bin/ の bash スクリプトが担当し、各コンポーネントは自身のディレクトリの
bin/start.sh / bin/stop.sh を持ちます。
| コンポーネント | 役割 | ディレクトリ |
|---|---|---|
Redis (cache) | ポイントキュー (Redisson) | $PE_HOME/cache/ |
HiveMQ (mqtt) | MQTT broker / Sparkplug B | $PE_HOME/mqtt/ |
Cassandra (db) | 時系列保存 (pe keyspace) | $PE_HOME/db/ |
Time-Series-Engine (tse) | 時系列エンジン | $PE_HOME/timeseries/engine/ |
| Dashboard | ダッシュボード | $PE_HOME/timeseries/dashboard/ |
Tomcat (server) | webapp plantpulse-edge-web (収集/REST/OPC-UA/UI) | $PE_HOME/server/ |
Node-RED (node) | フロー (/ui/flow) | $PE_HOME/node/ |
起動順序 (依存関係順) — bin/start.sh がこの順序で起動します:
cache → mqtt → db → tse → dashboard → server → node
- HTTP 80 / HTTPS 443 で Web UI と REST API を提供 (8080 ではない)
- JVM は JDK 21 (class file version 65) — Spring MVC 6.2 (non-boot)
- graceful shutdown:
ServerStartListenerが collector → Redisson → OPC → Cassandra を整理した後Runtime.halt(0)。デッドライン watchdog(-Dplantpulse.edge.shutdown.deadline.ms、デフォルト 9000ms)が STOP_TIMEOUT のレースを防ぎます。
2. ディレクトリ構成 ($PE_HOME = /opt/kopens/plantpulse-edge)
$PE_HOME/
├── app/plantpulse-edge-web/ # webapp (WEB-INF/classes·jsp·lib + public)
├── bin/ # 오케스트레이션 스크립트 (아래 6장)
│ ├── start.sh / stop.sh # full stack — cache→mqtt→db→tse→dashboard→server→node
│ ├── restart.sh # Tomcat(server) + Node-RED 만
│ ├── lifecycle-lib.sh # pp_log / pp_wait_port / run_module_start 헬퍼
│ ├── upgrade.sh / firmware.sh / backup.sh / clean.sh / reboot.sh
│ └── log-viewer.sh / node-*.sh
├── conf/ # canonical 설정 (운영자 편집)
│ ├── app.properties # webapp 설정 (이 박스가 canonical)
│ └── env.sh # JAVA_HOME / PP_LANG / PP_TZ / PE_DATA_DIR …
├── server/ # Tomcat (bin/ conf/ logs/)
│ ├── bin/setenv.sh # JVM 옵션 / LOCALE / -Dpe.conf.dir
│ ├── conf/server.xml # Connector(80/443) / Context
│ └── logs/ # catalina.out / system.log / api.log / driver.log
├── cache/ → Redis (bin/start.sh / stop.sh)
├── db/ → Cassandra (bin/start.sh / stop.sh)
├── mqtt/ → HiveMQ (bin/start.sh / stop.sh)
├── timeseries/engine/ + dashboard/
└── node/ → Node-RED (userDir/node_modules/node-red-contrib-plantpulse-edge/)
データディレクトリは $PE_DATA_DIR(デフォルト /data1)に分離します (Cassandra SSTable / Redis AOF / HiveMQ / Node-RED userDir)。
3. 事前要件 (native)
| 項目 | 基準 |
|---|---|
| OS | Linux (RHEL/Rocky/Alma/Fedora 系推奨) |
| 権限 | root (sudo -i) |
| JDK | OpenJDK 21 (dnf install java-21-openjdk java-21-openjdk-devel) — class file 65 互換 |
| Node.js | Node-RED 用 (nodejs / npm) |
| Python 3 | 補助スクリプト |
| ディスク | /opt/kopens 3GB+、/data1 100GB+ 推奨 |
| メモリ | 最小 8GB (Cassandra heap + Tomcat heap)、16GB+ 推奨 |
| NIC | 産業用アプライアンス標準の2ポート (1=WAN/外部、2=PLC/内部) |
| 時刻 | NTP(chrony) 同期 |
OS パッケージ、sysctl/limits、ファイアウォール、chrony、NIC static、SSL 発行、systemd 登録までを
一括で処理する自動 native インストールツールが別途あります →
(legacy) H/W 全体インストール (tools/setup.sh)。本ページでは、そのツールが配置する
ランタイム構造と手動/デバッグ起動手順を扱います。
4. インストール手順
4.1 自動 (推奨) — tools/setup.sh
OS 起動直後の空のボックスであれば、自動インストールツールがパッケージ・ネットワーク・チューニング・JDK・systemd までを 一括で整備します。ステップごとの入力(ホスト名、NIC、ファイアウォールポート)と22ステップの詳細は (legacy) H/W 全体インストールをそのまま参照してください。
sudo -i
cd /opt/kopens/tools
./setup.sh # 대화형 — 호스트명 + NIC 입력 후 진행, 끝나면 10초 후 자동 reboot
再起動後、plantpulse.service が自動でフルスタックを起動します。
4.2 手動 / デバッグ — ランタイムのみ起動
すでに OS / JDK 21 / ネットワークが準備されたボックス(または開発ワークステーション)にランタイム配置のみを行う場合:
sudo -i
# 1) 런타임 배치를 $PE_HOME 에 펼침 (운영팀 제공 native bundle 기준)
# /opt/kopens/plantpulse-edge/{app,bin,conf,server,cache,db,mqtt,timeseries,node}
# 2) 환경 파일 확인 — JDK 21 / 언어 / 시간대 / 데이터 경로
cat $PE_HOME/conf/env.sh
# export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
# export PP_LANG="${PP_LANG:-en}" / export PP_TZ="${PP_TZ:-Asia/Seoul}"
# export PE_DATA_DIR=/data1
# (상세: env 환경 설정 페이지)
# 3) 메인 설정 — 사이트/플랫폼/DB/MQTT 값
vi $PE_HOME/conf/app.properties # edge.id / edge.site_id / server.host / cassandra.* …
# 4) 풀스택 기동 (cache→mqtt→db→tse→dashboard→server→node)
$PE_HOME/bin/start.sh
env.sh/app.properties環境変数レイヤーの詳細は env 環境設定、app.propertiesキーの全体は app.properties ガイド を参照してください。
5. systemd 統合 — plantpulse.service
インストールが完了すると、systemd がフルスタックを自動管理します。
sudo systemctl enable plantpulse # 부팅 시 자동 시작 등록
sudo systemctl start plantpulse # 시작 (ExecStart → service-start.sh → bin/start.sh)
sudo systemctl stop plantpulse # 정지 (ExecStop → service-stop.sh → bin/stop.sh)
sudo systemctl status plantpulse # 상태
sudo systemctl restart plantpulse # 풀스택 재시작 (60초+ 다운타임)
sudo journalctl -u plantpulse -n 100 # systemd 로그 마지막 100줄
内部の wiring:
plantpulse.service ─ ExecStart=service-start.sh ─→ bin/start.sh (cache→mqtt→db→tse→dashboard→server→node)
└ ExecStop =service-stop.sh ─→ bin/stop.sh
bin/restart.sh は Tomcat(server) + Node-RED のみを再起動します(~6秒、Cassandra/Redis は維持)。
app.properties の修正反映や webapp 更新にはこちらを使ってください。
systemd restart は stop.sh → start.sh のフルスタックであるため、60秒以上のダウンタイムが発生します。
詳細: 再起動 (restart.sh)。
6. bin スクリプトカタログ
| スクリプト | 範囲 | 備考 |
|---|---|---|
bin/start.sh | フルスタック起動 | cache→mqtt→db→tse→dashboard→server→node |
bin/stop.sh | フルスタック停止 | コンポーネント別 stop.sh を呼び出し、STOP_TIMEOUT_SECONDS(デフォルト 10s)超過時は kill -9 |
bin/restart.sh | Tomcat + Node-RED のみ | ~6秒、コード/設定反映用 |
bin/backup.sh | 設定バックアップ | バックアップガイド |
bin/upgrade.sh | アップグレード | アップグレード |
bin/clean.sh | 作業ディレクトリ整理 | 整理/クリーンアップ |
bin/reboot.sh / firmware.sh | ホスト reboot / ファームウェア | — |
bin/log-viewer.sh | 7コンポーネントのログ tail | 無限 tail -f — 自動化/非対話 SSH では直接呼び出し禁止(セッション hang) |
各 run() は catch(Throwable) ガード + awaitTermination で安全に終了します。
7. インストール後の正常動作確認 (1分)
# 1) systemd 서비스 살아있는지
systemctl status plantpulse # active (running)
# 2) 시스템 헬스 — HTTP 200 이면 게이트웨이 정상
curl -s http://127.0.0.1/api/v1/system/health | python3 -m json.tool
# 3) OPC-UA 트리 (등록 0 이어도 빈 배열이면 OK)
curl -s http://127.0.0.1/ui/opcua/tree | python3 -c 'import sys,json;print(len(json.load(sys.stdin)["data"]["tree"]))'
# 4) 웹 UI
# 브라우저 → https://<gateway>/ui/main (로고 + 카드가 보이면 정상)
ログの全数確認 — catalina.out(起動失敗) + system.log(ERROR/Exception) だけでなく、
7コンポーネント(server/cache/db/mqtt/tse/dashboard/node)のログすべてに SEVERE/ERROR がないかを確認する。
自動化では log-viewer.sh(無限 tail) の代わりに、各 logs/*.log を tail -n / timeout で bounded に読む。
restart 後に ServerStartListener が静かに失敗して collector が未完了(OPC カウント 0)の場合は、restart.sh をもう一度。
ただし /api/v1/system/health の data.monitor=null (+ data.api_client=null) は race ではなく設計です
(HealthResponse.livenessWithComponents がその2フィールドを空にしておく)。
8. よく陥る落とし穴
| 症状 | 原因 / 対処 |
|---|---|
UnsupportedClassVersionError (class file 65) | JDK 21 が未インストール/未指定。env.sh の JAVA_HOME=/usr/lib/jvm/java-21-openjdk を確認 |
| UI 言語が意図と異なる(ko/en) | setenv.sh の -Duser.language が JAVA_TOOL_OPTIONS より優先。env 環境設定の LOCALE 動的化を参照 |
connect ECONNREFUSED 127.0.0.1:80 | Tomcat 未起動。bin/restart.sh または bin/stop.sh+start.sh |
| ポート/データの競合 | 同一ボックスで plantpulse-edge.service(コンテナ)も active。どちらかを stop/disable |
停止時に kill -9 が発生 | cleanup(~10s)が STOP_TIMEOUT_SECONDS(10s)とレース。deadline watchdog で緩和。完全に clean にしたい場合は STOP_TIMEOUT 25 + deadline 20000 |
| 再起動後に起動しない | journalctl -u plantpulse --no-pager で unit 失敗原因を確認 → bin/start.sh を直接実行して詰まる箇所を特定 |
9. 次のドキュメント
- env 環境設定 —
env.sh/PP_LANG/PP_TZ/-Dpe.conf.dir - Docker(コンテナ)インストール詳細 — 量産標準デプロイ
- (legacy) H/W 全体インストール (
tools/setup.sh) — 自動 native インストール22ステップ - app.properties ガイド — メイン設定キーの全体
- 再起動 (
restart.sh) / 起動 (start.sh) / 停止 (stop.sh) - インストール直後チェックリスト / 本番受け入れ基準