Docker Installation

Ab Mai 2026 ist die Standardbereitstellung für Serienfertigung und Vor-Ort-Einsätze von PlantPulse Edge ein einzelnes Docker-Container-Image. Sieben Komponenten (Tomcat / Cassandra / Redis / HiveMQ / TSE / Dashboard / Node-RED) sind in einem Image enthalten. install.sh übernimmt die Behandlung von Betriebssystem-Abhängigkeiten bis zur systemd-Registrierung, woraufhin plantpulse-edge.service den Container verwaltet.

Schnellinstallation vs. Diese Seite

Die zusammengefasste Prozedur für die schnelle Inbetriebnahme einer Anlage vor Ort finden Sie unter Schnellinstallation (install.sh). Diese Seite dient als Referenz, die tiefgehend analysiert, was bei dieser Installation intern geschieht — Image-Koordinaten, docker run-Flags, Bind-Mounts, EnvironmentFile und OTA. Für den täglichen Betrieb siehe Container-Modus-Betrieb.

Gleichzeitige Nutzung mit native untersagt

---

1. Image-Koordinaten

Element	Wert
Registry	docker.kopens.io/pe (anonymous pull)
Image-Name	plantpulse-edge
Vollständige Koordinaten	docker.kopens.io/pe/plantpulse-edge:<tag>
Tag-Format	YYYY.MM-YYYYMMDD-HHMM Bsp: 2026.11-20261103-1006 (bei Installation auch latest möglich, OTA nur unveränderliche Tags)
Download-Server	https://product.kopens.io/plantpulse-edge/ (LAN-Alias)

Fixe Pfade im Image: KOPENS_HOME=/opt/kopens, PE_HOME=/opt/kopens/plantpulse-edge, PE_DATA_DIR=/data1, JAVA_HOME=/usr/lib/jvm/java-21-openjdk.

---

2. Installationsfluss — bootstrap.sh → install.sh

2.1 One-Liner

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

install.sh ist identisch mit bootstrap.sh. Dieses Skript führt folgende Schritte aus:

1. Entpacken des Repo-Tarballs (plantpulse-edge-docker.tar.gz) nach /opt/kopens/plantpulse-edge-docker/ (bei Fehler Fallback auf git clone)
2. Anwendung von PROFILE-Presets (falls vorhanden, siehe Kapitel 3)
3. Ausführung der 9 Schritte des install.sh-Hauptteils

⌨️ Installationsabfragen — Szenen, in denen bei leeren Werten erneut gefragt wird. Dies ist kein Screenshot einer realen Installation (da sonst die Maschine tatsächlich konfiguriert würde), sondern eine Rekonstruktion unter Verwendung der vom Installer genutzten Prompt-Bibliothek. «Verhalten» wie Rückfragen sind echt; die Artikellisten werden durch CI bidirektional mit den Installer-Deklarationen abgeglichen, um Konsistenz zu gewährleisten

Abfragen variieren je nach Modus — Standard ist EDGE

Bei direkter Ausführung im Terminal erfolgt eine Abfrage (Standardverhalten). Werte in eckigen Klammern sind Standardwerte und werden per Enter akzeptiert.

• EDGE (Standard) — Fragt zwingend nach Plattformadresse und API-Key; bei leeren Feldern erfolgt eine erneute Abfrage.
• STANDALONE — Fragt diese beiden Werte überhaupt nicht ab.
• Edge id Die Standardwerte variieren pro Box (Format EDGE_3F8A21, abgeleitet von NET1 MAC). Geben Sie hier die Anlagennummer ein, falls diese spezifisch festgelegt werden soll.

Abfragen über curl | bash nicht möglich — Werte per Umgebungsvariablen übergeben

Bei der Ausführung über eine Pipeline ist kein Terminal angebunden, weshalb keine Abfragen möglich sind. In diesem Fall wird ausgegeben, dass «keine Abfrage möglich ist», und die Installation wird mit Umgebungsvariablen und Standardwerten fortgesetzt (kein stilles Überspringen).

curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh | \
  sudo EDGE_ID=EDGE_00303 DEV_MODE=EDGE \
       SERVER_HOST=<플랫폼IP> SERVER_API_KEY=<token> bash

Um Abfragen zu ermöglichen, laden Sie das Skript herunter und führen Sie es direkt aus. Bei Automatisierungen (CI, unbeaufsichtigte Installation) ist es sicherer, die Abfragen über INTERACTIVE=0 explizit zu deaktivieren.

Einziger Anpassungspunkt für Betreiber: env.sh

Wenn Sie dies in der env.sh im selben Ordner wie das Skript hinterlegen, wird es bei der Installation automatisch gelesen. Bei Neuinstallationen werden dieselben Werte beibehalten.

2.1a Plattform-Key-Validierung während der Installation

Wenn DEV_MODE=EDGE aktiv ist, wird vor dem Schreiben der Konfiguration tatsächlich bei der Plattform angefragt. Früher wurde nur geprüft, ob ein Wert vorhanden war, was dazu führte, dass nach dem Booten alle Verbindungen mit einem 401-Fehler scheiterten.

Situation	Verhalten des Installers
Plattform nicht erreichbar	Nur Warnung — System ist eventuell noch nicht gestartet oder Firewall blockiert
Server antwortet mit 5xx	Nur Warnung — Keine Entscheidung möglich, liegt nicht am Key
401 · 403	🔴 Abbruch — Key wurde abgelehnt. Tippfehler werden hier erkannt
400	🔴 Abbruch — Problem auf Seiten des Installers, bitte melden

Falls die Installation vor der Plattform erfolgen muss, deaktivieren Sie dies über SKIP_PLATFORM_VERIFY=1.

2.1b Referenz für die Nutzung ist --help

sudo bash install.sh --help      # root 없이도 읽힙니다

⌨️ Vollständiger Text von `--help` — Da die Ausgabe in 0,04s erfolgt, wird sie als «Stillbild» dargestellt. Es handelt sich um eine Aufnahme aus der «gleichen Ausführung» wie der Installer, also den Bildschirm des aktuell herunterzuladenden Skripts

Zusammen mit dem Banner erscheinen die Abschnitte USAGE · MODE decides what else is required · IDENTITY · PLATFORM · IMAGE · NETWORK · SKIP FLAGS · PROFILE · AFTER INSTALL. Es gibt einen Grund, warum der vollständige Text nicht in dieses Dokument kopiert wird — kopierte Versionen veralten stillschweigend. Tatsächlich gab es Fälle, in denen sich die Standardwerte im Header und im Code in diesem Repository voneinander unterschieden haben.

2.2 Die 9 Schritte von install.sh

#	Schritt
1	OS-Erkennung (Rocky/Alma/RHEL/Ubuntu/Debian)
2	Docker Installation (dnf oder apt)
3	Erstellung der Verzeichnisse /data1, /etc/kopens, /var/log/kopens
4	sysctl + firewalld Ports + chrony + hostname + nmcli statische IP
5	Erstellung von /etc/kopens/app.properties (EDGE_ID / SITE_ID / random Credentials pro Box)
6	Installation der systemd-Unit — plantpulse-edge.service + OTA kopens-upgrade.path/.service
7	docker pull (cosign Signaturprüfung — bei Installation nur Warnung, bei Upgrade Abbruch, falls Prüfung fehlschlägt)
8	systemctl enable --now plantpulse-edge.service
9	Registrierung des wöchentlichen cron-Cleanups

Bei der Erstinstallation werden Passwörter für admin / MQTT / OPC-UA / API key / keystore zufällig pro Box generiert und einmalig in /etc/kopens/credentials.txt (chmod 0600 root) gespeichert.

---

3. PROFILE Preset

Über PROFILE env werden Standardwerte je nach Standorttyp in einem Schritt angewendet.

PROFILE	Angewendete Standardwerte
production	DEV_MODE=EDGE (Plattform SERVER_HOST/SERVER_API_KEY Angabe erforderlich)
staging	DEV_MODE=EDGE, EDGE_ID=EDGE_00303, SITE_ID=SITE_00001, SERVER_HOST=192.168.0.235, SKIP_COSIGN_VERIFY=1
standalone	DEV_MODE=STANDALONE, SKIP_COSIGN_VERIFY=1 (keine Plattformverbindung)
airgap	IMAGE_URL=tarball, SKIP_PULL=1, DEV_MODE=STANDALONE (Air-Gap-Netzwerk Installation)

# 양산 (플랫폼 연결)
curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh \
  | sudo PROFILE=production EDGE_ID=EDGE_00303 \
         SERVER_HOST=10.0.0.5 SERVER_API_KEY=<uuid> bash

# 단독 운영 (플랫폼 없이)
curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh \
  | sudo PROFILE=standalone EDGE_ID=EDGE_LOCAL_01 bash

staging = dev Klon

Die Staging-Box ist ein Klon von dev mit denselben EDGE_00303 / SITE_00001. Einzig die Plattformverbindungsdaten (SERVER_HOST=192.168.0.235 / API key) müssen sich unterscheiden. Wenn ein nicht registrierter Standort verwendet wird, schlägt das OPC-Selbstdiagnose-Tool der Edge aufgrund einer FK-Verletzung fehl; daher werden die registrierten EDGE/Standort-Daten verwendet. Wenn dev und Staging gleichzeitig mit der Plattform verbunden sind, werden sie als dieselbe Edge erkannt; die Validierung muss daher versetzt erfolgen.

Die vollständige Liste der häufig verwendeten envs bei der Installation finden Sie unter env Konfiguration §6.

---

4. Analyse der systemd-Unit — plantpulse-edge.service

install.sh ist die tatsächliche Definition für den Start des Containers, die als /etc/systemd/system/plantpulse-edge.service bereitgestellt wird.

4.1 docker run (ExecStart)

/usr/bin/docker run --rm --name plantpulse-edge \
    --network=host \
    --init \
    --stop-timeout=120 \
    -v /data1:/data1:z \
    -v /etc/kopens:/etc/kopens:z \
    -v /etc/kopens/conf:/opt/kopens/plantpulse-edge/conf:z \
    -v /var/security:/var/security:rw,z \
    -v /etc/localtime:/etc/localtime:ro \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e PP_LANG=${PP_LANG} \
    -e PP_TZ=${PP_TZ} \
    -e CERT_PASS=${CERT_PASS} \
    --cap-drop=ALL \
    --cap-add=NET_BIND_SERVICE \
    --cap-add=NET_RAW \
    --cap-add=DAC_OVERRIDE \
    --cap-add=CHOWN \
    --cap-add=FOWNER \
    --log-driver=journald \
    --log-opt tag="plantpulse-edge" \
    ${KOPENS_IMAGE}:${PE_VERSION}

Flag	Bedeutung
--network=host	Automatische Freigabe von 9 Ports + Multicast / OPC-UA Discovery
--init	tini als PID 1 (Zombie Reap + Signal Forwarding)
--stop-timeout=120	Sicherstellung der Zeit für Cassandra Graceful Drain
--cap-drop=ALL + individuelle --cap-add	Minimalberechtigungen. NET_RAW für PLC-Ping, NET_BIND_SERVICE für 80/443 Bind

4.2 Bind-Mount

Host-Pfad	Container-Pfad	Modus	Verwendung
/data1	/data1	rw,z	Daten (Cassandra/Redis/HiveMQ/Node-RED) — bleibt bei Containerwechsel erhalten
/etc/kopens	/etc/kopens	rw,z	Konfiguration + Signaldaten
/etc/kopens/conf	/opt/kopens/plantpulse-edge/conf	rw,z	app.properties / log4j2.xml
/var/security	/var/security	rw,z	TLS Keystore
/etc/localtime	/etc/localtime	ro	Host-Zeitzone
/var/run/docker.sock	/var/run/docker.sock	rw	Docker App-Management über /ui/apps

4.3 EnvironmentFile + Standardwerte

In der Unit integrierte Standardwerte (wenn keine Datei vorhanden ist):

Environment=PE_VERSION=latest
Environment=KOPENS_IMAGE=docker.kopens.io/pe/plantpulse-edge
Environment=PP_LANG=en
Environment=PP_TZ=Asia/Seoul
Environment=CERT_PASS=kopens123!

EnvironmentFile (bei Vorhandensein Override — aktuellste Werte priorisiert):

Datei	Key	Ersteller
/etc/kopens/version.env	PE_VERSION=<tag>	OTA upgrade.sh
/etc/kopens/i18n.env	PP_LANG / PP_TZ	install.sh
/etc/kopens/cert.env	CERT_PASS	TLS-Ausstellungs-Skript

4.4 Ressourcenlimits / Neustart-Richtlinien

MemoryMax=12G      # 16GB 박스 기준 — 호스트 OOM 방지
MemoryHigh=11G
CPUQuota=600%      # 6 cores
TasksMax=8192

Restart=on-failure
RestartSec=30s
TimeoutStartSec=300
TimeoutStopSec=180

Für die Reduzierung des Heap-Speichers bei 8GB-Boxen (Drop-in Override) siehe Container-Modus §Ressourcenlimits.

---

5. Lesezugriff auf Container-Runtime-Konfiguration

Im WAR-Modus (ab 13.06.2026) wird die Konfiguration direkt aus /etc/kopens des Hosts gelesen — kein Image-Rebuild erforderlich.

/etc/kopens/app.properties                          ← 운영자가 편집하는 canonical
        │  (entrypoint 가 symlink 생성)
        ▼
/etc/kopens/conf/app.properties  ──bind──▶  /opt/kopens/plantpulse-edge/conf/app.properties
                                             ▲
        Tomcat setenv.sh: -Dpe.conf.dir=/opt/kopens/plantpulse-edge/conf

• app.properties: Host /etc/kopens/app.properties ist die Source-of-Truth. Wenn nicht vorhanden, setzt der Entrypoint das Image-Default als Seed. Bearbeitung durch Betreiber → Anwendung über config.sh --restart.
• log4j2.xml: Der Entrypoint kopiert bei jedem Boot vom Webapp-Default nach conf/log4j2.xml (Code-Artefakt — Loglevel-Änderung nach Restart möglich ohne Image-Rebuild).
• HiveMQ auth.properties: Der Entrypoint synchronisiert bei jedem Boot automatisch mit mqtt.server.* in app.properties — es muss nur app.properties bearbeitet werden.
• TLS Passwort: Der Entrypoint interpretiert CERT_PASS in cert.env und patcht Tomcat server.xml / HiveMQ Config / OPC-UA Keystore Passwörter einheitlich.

Weitere Details zur env→Konfig-Spiegelung siehe Umgebungsvariablen-Konfiguration, Bedeutungen der einzelnen Keys siehe app.properties Referenz.

---

6. OTA Upgrade / Rollback

Die Version ist in /etc/kopens/version.env fixiert — OTA ersetzt diese Datei durch einen validierten Digest und startet neu.

# 자동 (META-INF/VERSION.JSON 이 가리키는 빌드)
sudo bash /opt/kopens/install/upgrade.sh

# 특정 불변 태그 (YYYY.MM-YYYYMMDD-HHMM). 움직이는 태그는 거부합니다
sudo bash /opt/kopens/install/upgrade.sh --to 2026.11-20261103-1006

# 진행 중인 현재 업그레이드만 롤백 (trial · rollback_failed 상태에서만)
sudo bash /opt/kopens/install/upgrade.sh --rollback

# 사전 점검만 (0 최신, 10 새 빌드 있음)
sudo bash /opt/kopens/install/upgrade.sh --check

Status: cat /etc/kopens/upgrade.status → idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed. Details zum Ablauf siehe Upgrade.

---

7. Manuelle docker run für Debugging

Der Betrieb erfolgt zwingend über systemd / install.sh, für isoliertes Debugging ist jedoch ein manueller Start möglich:

sudo docker run --rm --name pe-debug \
    --network=host --init \
    -v /data1:/data1:z \
    -v /etc/kopens:/etc/kopens:z \
    -v /etc/kopens/conf:/opt/kopens/plantpulse-edge/conf:z \
    -v /var/security:/var/security:rw,z \
    -e PP_LANG=en -e PP_TZ=Asia/Seoul -e CERT_PASS="$(. /etc/kopens/cert.env; echo $CERT_PASS)" \
    docker.kopens.io/pe/plantpulse-edge:<tag>

Bereitstellung nur über Pipeline — Image (Re)build / Push / Staging-Neuverteilung darf nicht lokal erfolgen, sondern über die Release-Chain von plantpulse-edge-docker (edge:libs → edge:deploy-dev → edge:image → edge:staging → edge:version, Trigger über Pipeline-Variable RELEASE=1). Der obige Befehl gilt nur für isoliertes Debugging.

---

8. Validierung nach der Installation

systemctl is-active plantpulse-edge.service
sudo bash /opt/kopens/install/bin/status.sh

# version: container_mode=true 여야 함
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool
# health: HTTP 200 + components UP
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool

Ansicht	URL
Web UI	https://<gateway-ip>/ui/main
Node-RED	https://<gateway-ip>/ui/flow/
Swagger UI	https://<gateway-ip>/public/swagger-ui/index.html

Maßnahmen bei Symptomen siehe Fehlerbehebung bei Installation, täglicher Betrieb/Störungen siehe Container-Modus-Betrieb.

---

9. Weitere Dokumente

• Schnellinstallation (install.sh) — Zusammenfassung der Installationsprozedur für einzelne Anlagen vor Ort
• Umgebungsvariablen-Konfiguration — PROFILE / PP_LANG / CERT_PASS / -Dpe.conf.dir
• Container-Modus-Betrieb — pe-* Tools / Logs / Störungsbehebung
• Air-Gap-Netzwerk Installation / Serienfertigungslinie (factory.sh)
• Produktionsabnahmekriterien