Native-Installation — Direkte Installation auf dem Host ohne Container

Diese Seite beschreibt den Betrieb von PlantPulse Edge bei direkter (nativer) Installation auf dem Host-Betriebssystem ohne Docker. Die Gateway-Runtime (Tomcat / Cassandra / Redis / HiveMQ / Time-Series-Engine / Node-RED) läuft dabei jeweils als Host-Prozess, und ein einziger plantpulse.service (systemd) verwaltet den gesamten Stack.

Wann native einsetzen

• Entwicklungs-/Debug-Workstation — Code direkt einspielen und per JSP-/Klassen-Hot-Swap schnell verifizieren
• Wartung von Legacy-Boxen älter als 2026.05 — Vor-Ort-Installationen, die bereits nativ laufen
• Umgebungen mit Sicherheitsrichtlinien, die Docker ausschließen

Für Neuinstallationen in Serie bzw. eine Vor-Ort-Einzelinstallation ist der Container-Modus der Standard → Schnellinstallation (install.sh) / Docker-(Container-)Installation im Detail.

Native und Container nicht auf derselben Box mischen

Native verwendet plantpulse.service, Container verwendet plantpulse-edge.service. Laufen beide Dienste gleichzeitig, kollidieren Ports wie 80/443/1880/9042/12000 sowie der Datenpfad /data1. Ist systemctl is-active plantpulse-edge.service auf active, handelt es sich um eine Container-Box — stoppen/deaktivieren Sie unbedingt eine Seite, bevor Sie native starten.

---

1. Runtime-Modell — was läuft wie

Im Native-Modus werden die sieben Komponenten des Gateways jeweils als eigener Host-Prozess ausgeführt. Die Orchestrierung übernimmt ein Bash-Skript unter $PE_HOME/bin/; jede Komponente besitzt im eigenen Verzeichnis ein bin/start.sh / bin/stop.sh.

Komponente	Rolle	Verzeichnis
Redis (cache)	Point-Queue (Redisson)	$PE_HOME/cache/
HiveMQ (mqtt)	MQTT Broker / Sparkplug B	$PE_HOME/mqtt/
Cassandra (db)	Zeitreihen-Speicher (Keyspace pe)	$PE_HOME/db/
Time-Series-Engine (tse)	Zeitreihen-Engine	$PE_HOME/timeseries/engine/
Dashboard	Dashboard	$PE_HOME/timeseries/dashboard/
Tomcat (server)	Webapp plantpulse-edge-web (Erfassung/REST/OPC-UA/UI)	$PE_HOME/server/
Node-RED (node)	Flows (/ui/flow)	$PE_HOME/node/

Startreihenfolge (nach Abhängigkeiten) — bin/start.sh startet in dieser Reihenfolge:

cache → mqtt → db → tse → dashboard → server → node

• Web-UI und REST API über HTTP 80 / HTTPS 443 (nicht 8080)
• JVM ist JDK 21 (class file version 65) — Spring MVC 6.2 (non-boot)
• Graceful Shutdown: ServerStartListener räumt collector → Redisson → OPC → Cassandra auf und danach Runtime.halt(0). Ein Deadline-Watchdog (-Dplantpulse.edge.shutdown.deadline.ms, Standard 9000 ms) verhindert Races mit STOP_TIMEOUT.

---

2. Verzeichnisstruktur ($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/)

Die Datenverzeichnisse werden über $PE_DATA_DIR (Standard /data1) getrennt (Cassandra SSTable / Redis AOF / HiveMQ / Node-RED userDir).

---

3. Voraussetzungen (native)

Punkt	Anforderung
OS	Linux (RHEL/Rocky/Alma/Fedora-Familie empfohlen)
Rechte	root (sudo -i)
JDK	OpenJDK 21 (dnf install java-21-openjdk java-21-openjdk-devel) — kompatibel mit class file 65
Node.js	für Node-RED (nodejs / npm)
Python 3	Hilfsskripte
Festplatte	/opt/kopens 3 GB+, /data1 100 GB+ empfohlen
Arbeitsspeicher	mindestens 8 GB (Cassandra Heap + Tomcat Heap), 16 GB+ empfohlen
NIC	Standard von Industrie-Appliances: 2 Stück (1 = WAN/extern, 2 = PLC/intern)
Zeit	NTP-(chrony-)Synchronisierung

Automatischer Abgleich von OS / Paketen / Netzwerk mit setup.sh

Für OS-Pakete, sysctl/limits, Firewall, chrony, statische NIC-Konfiguration, SSL-Ausstellung und systemd-Registrierung in einem Durchgang existiert ein separates automatisches Native-Installationswerkzeug → (legacy) Komplette H/W-Installation (tools/setup.sh). Diese Seite behandelt die Runtime-Struktur, die dieses Werkzeug anlegt, sowie den manuellen/Debug-Startablauf.

---

4. Installationsablauf

4.1 Automatisch (empfohlen) — tools/setup.sh

Auf einer leeren Box direkt nach dem OS-Boot richtet das automatische Installationswerkzeug Pakete, Netzwerk, Tuning, JDK und systemd in einem Durchgang ein. Die schrittweisen Eingaben (Hostname, NIC, Firewall-Ports) und die 22 Schritte im Detail folgen unverändert (legacy) Komplette H/W-Installation.

sudo -i
cd /opt/kopens/tools
./setup.sh          # 대화형 — 호스트명 + NIC 입력 후 진행, 끝나면 10초 후 자동 reboot

Nach dem Neustart startet plantpulse.service automatisch den kompletten Stack.

4.2 Manuell / Debug — nur die Runtime starten

Wenn auf einer Box mit bereits vorbereitetem OS / JDK 21 / Netzwerk (oder auf einer Entwickler-Workstation) nur das Runtime-Deployment eingespielt wird:

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

Details zu den Umgebungsvariablen-Ebenen env.sh / app.properties siehe env-Konfiguration, sämtliche app.properties-Schlüssel siehe app.properties-Leitfaden.

---

5. systemd-Integration — plantpulse.service

Nach Abschluss der Installation verwaltet systemd den kompletten Stack automatisch.

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줄

Internes Wiring:

plantpulse.service ─ ExecStart=service-start.sh ─→ bin/start.sh   (cache→mqtt→db→tse→dashboard→server→node)
                   └ ExecStop =service-stop.sh  ─→ bin/stop.sh

Für Änderungen nur an Code / app.properties kein Full-Stack-Neustart, sondern restart.sh

bin/restart.sh startet nur Tomcat (server) + Node-RED neu (~6 s, Cassandra/Redis bleiben aktiv). Für die Übernahme von app.properties-Änderungen oder ein Webapp-Update nutzen Sie dieses Skript. systemd restart betrifft den kompletten stop.sh → start.sh-Stack und verursacht über 60 s Ausfallzeit. Details: Neustart (restart.sh).

---

6. Katalog der bin-Skripte

Skript	Umfang	Hinweis
bin/start.sh	Start des kompletten Stacks	cache→mqtt→db→tse→dashboard→server→node
bin/stop.sh	Stopp des kompletten Stacks	ruft die stop.sh der einzelnen Komponenten auf, bei Überschreiten von STOP_TIMEOUT_SECONDS (Standard 10 s) kill -9
bin/restart.sh	nur Tomcat + Node-RED	~6 s, für Code-/Konfigurationsübernahme
bin/backup.sh	Konfigurations-Backup	Backup-Leitfaden
bin/upgrade.sh	Upgrade	Upgrade
bin/clean.sh	Arbeitsverzeichnisse bereinigen	Bereinigung
bin/reboot.sh / firmware.sh	Host-Reboot / Firmware	—
bin/log-viewer.sh	Log-Tail aller 7 Komponenten	endloses tail -f — in Automatisierung/nicht-interaktivem SSH nicht direkt aufrufen (Session hängt)

Jedes run() beendet sich sicher über eine catch(Throwable)-Guard-Prüfung + awaitTermination.

---

7. Funktionsprüfung nach der Installation (1 Minute)

# 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   (로고 + 카드가 보이면 정상)

Vollständige Logprüfung — nicht nur catalina.out (Startfehler) + system.log (ERROR/Exception), sondern die Logs aller 7 Komponenten (server/cache/db/mqtt/tse/dashboard/node) auf SEVERE/ERROR prüfen. In der Automatisierung statt log-viewer.sh (endloses Tail) jedes logs/*.log mit tail -n / timeout begrenzt lesen.

Boot-Race (selten)

Schlägt nach einem Neustart ServerStartListener stillschweigend fehl und der collector bleibt unvollständig (OPC-Anzahl 0), einfach restart.sh erneut ausführen. data.monitor=null (+ data.api_client=null) in /api/v1/system/health ist jedoch kein Race, sondern Absicht (HealthResponse.livenessWithComponents lässt diese beiden Felder leer).

---

8. Häufige Stolperfallen

Symptom	Ursache / Abhilfe
UnsupportedClassVersionError (class file 65)	JDK 21 nicht installiert/nicht gesetzt. JAVA_HOME=/usr/lib/jvm/java-21-openjdk in env.sh prüfen
UI-Sprache weicht ab (ko/en)	-Duser.language in setenv.sh hat Vorrang vor JAVA_TOOL_OPTIONS. Siehe LOCALE-Dynamisierung in env-Konfiguration
connect ECONNREFUSED 127.0.0.1:80	Tomcat nicht gestartet. bin/restart.sh oder bin/stop.sh+start.sh
Port-/Datenkonflikt	Auf derselben Box ist auch plantpulse-edge.service (Container) aktiv. Eine Seite stop/disable
kill -9 beim Stoppen	Cleanup (~10 s) läuft in ein Race mit STOP_TIMEOUT_SECONDS (10 s). Durch Deadline-Watchdog entschärft. Für vollständig sauberen Ablauf STOP_TIMEOUT 25 + deadline 20000
Startet nach Reboot nicht	Mit journalctl -u plantpulse --no-pager die Fehlerursache der Unit ermitteln → bin/start.sh direkt ausführen und Blockadepunkt bestimmen

---

9. Weiterführende Dokumente

• env-Konfiguration — env.sh / PP_LANG / PP_TZ / -Dpe.conf.dir
• Docker-(Container-)Installation im Detail — Standard-Deployment für den Serienbetrieb
• (legacy) Komplette H/W-Installation (tools/setup.sh) — automatische Native-Installation in 22 Schritten
• app.properties-Leitfaden — sämtliche Hauptkonfigurationsschlüssel
• Neustart (restart.sh) / Start (start.sh) / Stopp (stop.sh)
• Checkliste direkt nach der Installation / Abnahmekriterien für den Produktivbetrieb