env-Umgebungskonfiguration — env.sh / PPLANG / CERTPASS / -Dpe.conf.dir
Die in diesem Dokument genannten Passwörter (CERT_PASS usw.) sind Standardwerte der internen Dev-Box und keine Geheimnisse.
In Kunden-/Serienbereitstellungen dürfen sie nicht unverändert übernommen werden:
install.sherzeugt bei fehlender Angabe vonCERT_PASSein 14-stelliges Zufallspasswort (bin/install.sh:298). Der erzeugte Wert wird in/etc/kopens/credentials.txt(0600, root) sowie im Factory-Label festgehalten.- Auch das Passwort für den OS-Zugang der Box wird bei der Installation geändert.
- Die Standardwerte aus der Dokumentation gelten daher nur für eine einzige interne Dev-Box.
Die Konfiguration von PlantPulse Edge gliedert sich in zwei Ebenen.
| Ebene | Was | Wo |
|---|---|---|
| Umgebungsvariablen (env) ← diese Seite | Sprache/Zeitzone, JDK-Pfad, TLS-Passwort, Datenpfade, Standortwerte bei der Installation | env.sh / /etc/kopens/*.env / systemd / docker -e |
| Anwendungskonfiguration (properties) | edge.id / cassandra.* / mqtt.* / OPC-UA und weitere Runtime-Keys | app.properties → app.properties-Leitfaden |
Die env-Ebene legt Sprache · Zeitzone · JVM-Optionen · Passwörter · Speicherort des Konfigurationsverzeichnisses fest; darauf aufbauend läuft app.properties. Es handelt sich um Werte, die pro Box einmal festgelegt werden und sich danach kaum noch ändern.
1. Die zentralen env-Variablen auf einen Blick
| Variable | Bedeutung | Standardwert |
|---|---|---|
PP_LANG | Sprache von UI/OS/JVM (BCP 47) — eine einzige Sprache pro Box | en |
PP_TZ | Zeitzone (java.util.TimeZone-ID) | Asia/Seoul |
JAVA_HOME | JDK-Pfad (class file 65 → JDK 21) | /usr/lib/jvm/java-21-openjdk |
PE_HOME | Gateway-Root | /opt/kopens/plantpulse-edge |
PE_DATA_DIR | Datenverzeichnis (Cassandra/Redis/HiveMQ/Node-RED) | /data1 |
CERT_PASS | TLS-Keystore-Passwort (gemeinsam für Tomcat/HiveMQ/OPC-UA) | kopens123! (legacy) / bei Installation zufällig |
CLEAN_ON_STARTUP | Bereinigung von work/temp beim Booten | false |
JAVA_TOOL_OPTIONS | Gemeinsame Optionen aller JVMs (entrypoint/setenv.sh injiziert Sprache/Zeitzone) | (automatisch konfiguriert) |
CERT_PASS / SERVER_API_KEY und sämtliche Passwörter dürfen nicht in der Shell-History, in ps-argv oder in Logs auftauchen.
Verwenden Sie eine *_FILE-Injektion (z. B. EDGE_ADMIN_PASSWORD_HASH_FILE, CASSANDRA_PASSWORD_FILE) oder eine root-Datei mit 0600, die Sie vor der Installation source. Die von install.sh erzeugten Zufallszugangsdaten werden einmalig in /etc/kopens/credentials.txt (chmod 0600 root) gespeichert.
2. Sprache / Zeitzone — PP_LANG / PP_TZ
PlantPulse erzwingt eine einzige Sprache/Zeitzone pro Box. Benutzerspezifische Cookies bzw. Accept-Language werden ignoriert; Webapp, Host-OS, Container-OS und JVM verwenden alle denselben Wert.
PP_LANG=en PP_TZ=Asia/Seoul # 글로벌 default (영문 UI + 한국 시간)
PP_LANG=ko PP_TZ=Asia/Seoul # 완전 한국 박스
PP_LANG=en PP_TZ=UTC # 완전 영문 박스
2.1 Weitergabekette (4 Layer)
env.sh / i18n.env ─→ install.sh ─→ systemd EnvironmentFile + docker -e ─→ container-entrypoint.sh ─→ webapp PpFixedLocaleResolver
(값 정의) (host locale) (PP_LANG / PP_TZ 주입) (OS LANG/TZ + JAVA_TOOL_OPTIONS) (UI 언어 결정)
2.2 Was der entrypoint im Container tut
container-entrypoint.sh mappt PP_LANG auf ein POSIX-Locale und stellt die JVM-Optionen zusammen:
PP_LANG="${PP_LANG:-en}"; PP_TZ="${PP_TZ:-Asia/Seoul}"
case "$PP_LANG" in
ko|ko_*|ko-*) LANG=ko_KR.UTF-8 ; lang=ko country=KR ;;
en|en_*|en-*) LANG=en_US.UTF-8 ; lang=en country=US ;;
esac
export LANG TZ="$PP_TZ"
ln -sf "/usr/share/zoneinfo/$PP_TZ" /etc/localtime
# 모든 JVM 프로세스 통일
export JAVA_TOOL_OPTIONS="$JAVA_TOOL_OPTIONS -Duser.language=$lang -Duser.country=$country -Duser.timezone=$PP_TZ"
Die Werte werden zusätzlich in /etc/locale.conf, /etc/environment und /etc/timezone eingetragen und bleiben so auch bei erneuter Anmeldung oder beim Aufruf von Tools erhalten.
Die Sprache wird beim Booten einmal festgelegt und lässt sich weder per Cookie noch über Accept-Language ändern.
Ein Umschalten ko↔en erfordert eine Änderung von PP_LANG plus Neustart von Container/Tomcat.
2.3 LOCALE im native-Modus (setenv.sh)
Im native-Modus muss LOCALE in server/bin/setenv.sh dynamisch sein — es gab Fälle, in denen ein alt hartkodiertes -Duser.language=ko -Duser.country=KR Vorrang vor JAVA_TOOL_OPTIONS hatte und ko gewann.
# server/bin/setenv.sh
LOCALE="-Duser.language=${PP_LANG:-en} -Duser.country=${PP_COUNTRY:-US} -Duser.timezone=${PP_TZ:-Asia/Seoul}"
Und in conf/env.sh dann export PP_LANG / export PP_TZ / export JAVA_HOME=/usr/lib/jvm/java-21-openjdk.
3. native conf/env.sh
Die Umgebungsdatei der native-Box. bin/start.sh sourced sie vor dem Start.
# $PE_HOME/conf/env.sh
export PE_HOME=/opt/kopens/plantpulse-edge
export PE_DATA_DIR=/data1
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk # JDK 21 — class file 65 호환 (필수)
export PP_LANG="${PP_LANG:-en}"
export PP_TZ="${PP_TZ:-Asia/Seoul}"
export CLEAN_ON_STARTUP=false
| Key | Bedeutung |
|---|---|
PE_HOME | Gateway-Root (Bezugspfad der Skripte) |
PE_DATA_DIR | Verzeichnis für getrennte Datenhaltung (üblicherweise eigene Partition /data1) |
JAVA_HOME | Bei fehlender Angabe von JDK 21: UnsupportedClassVersionError |
PP_LANG / PP_TZ | Sprache / Zeitzone (siehe Kapitel 2) |
CLEAN_ON_STARTUP | Bereinigung von work/temp beim Booten |
Die gesamte native-Installationsstruktur finden Sie unter Native Installation.
4. Container /etc/kopens/*.env (systemd EnvironmentFile)
Auf Container-Boxen liest die systemd-Unit die folgenden Dateien als EnvironmentFile ein und injiziert sie als docker -e.
Existiert eine Datei, überschreibt sie die in der Unit hinterlegten Standardwerte.
| Datei | Key | Erzeuger | Zweck |
|---|---|---|---|
/etc/kopens/version.env | PE_VERSION=<tag> | OTA upgrade.sh | Image-Tag fixieren — OTA/Rollback ändert nur diese eine Zeile |
/etc/kopens/i18n.env | PP_LANG / PP_TZ | install.sh | Sprache / Zeitzone |
/etc/kopens/cert.env | CERT_PASS | TLS-Ausstellungsskript | Keystore-Passwort |
# plantpulse-edge.service (발췌)
EnvironmentFile=-/etc/kopens/version.env
EnvironmentFile=-/etc/kopens/i18n.env
EnvironmentFile=-/etc/kopens/cert.env
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!
Um die Sprache zu ändern:
sudo tee /etc/kopens/i18n.env <<'EOF'
PP_LANG=ko
PP_TZ=Asia/Seoul
EOF
sudo systemctl restart plantpulse-edge.service
Die vollständige Analyse der systemd-Unit finden Sie unter Docker-Installation §4.
5. Speicherort des Konfigurationsverzeichnisses — -Dpe.conf.dir
Die zentrale env-/System-Property, die festlegt, von wo app.properties und log4j2.xml gelesen werden.
Im WAR-Modus (ab 2026-06-13) wird die Konfiguration direkt vom Host aus /etc/kopens gelesen — ein Neubau von Image oder Batch entfällt.
| Modus | -Dpe.conf.dir | Kanonische Datei |
|---|---|---|
| Container | /opt/kopens/plantpulse-edge/conf (= host /etc/kopens/conf bind-mount) | /etc/kopens/app.properties |
| native | $PE_HOME/conf | $PE_HOME/conf/app.properties |
- Container:
/etc/kopens/conf/app.propertiesauf dem Host ist die reale Datei und die Source of Truth./etc/kopens/app.propertiesist lediglich ein Symlink darauf zur Legacy-Kompatibilität (ln -sfn /etc/kopens/conf/app.properties /etc/kopens/app.properties). log4j2.xmlist ein Code-Artefakt — der entrypoint kopiert es bei jedem Boot aus den Webapp-Defaults (bei reiner Änderung des Log-Levels genügt ein restart, kein Image-Neubau).
Die Konfigurations-Keys selbst (was einzutragen ist) behandeln der app.properties-Leitfaden und der Konfigurationsbildschirm. Diese Seite behandelt, von wo und wie diese Dateien gelesen werden.
6. env-Overrides bei der Installation mit install.sh
Zum Installationszeitpunkt werden Standortwerte, Netzwerkparameter und Zugangsdaten der Box per env injiziert (install.sh wird in app.properties übernommen).
sudo PROFILE=production \
EDGE_ID=EDGE_00303 \
SITE_ID=SITE_00001 \
SERVER_HOST=192.168.0.41 \
SERVER_API_KEY='<platform-api-key>' \
PP_LANG=en PP_TZ=Asia/Seoul \
CERT_PASS='<keystore-pass>' \
bash install.sh
| Variable | Bedeutung | Standardwert |
|---|---|---|
PROFILE | Preset production / staging / standalone / airgap | — |
EDGE_ID | Eindeutige ID der Box (^EDGE_[A-Z0-9_]{1,60}$) | automatisch auf MAC-Basis erzeugt |
SITE_ID | Standort-ID (für die Registrierung an der Platform erforderlich) | SITE_00001 |
DEV_MODE | EDGE (mit Platform verbunden) / STANDALONE (nicht verbunden) | EDGE |
SERVER_HOST / SERVER_API_KEY | Anbindung an die Platform-API (im EDGE-Modus erforderlich) | — |
PP_LANG / PP_TZ | Sprache / Zeitzone | en / Asia/Seoul |
ADMIN_PASS / API_KEY / MQTT_PASS / OPCUA_PASS | Override der initialen Zugangsdaten | pro Box zufällig |
CERT_PASS | TLS-Keystore-Passwort | kopens123! (legacy) / zufällig |
CERT_DOMAIN / CERT_SAN_DNS / CERT_SAN_IP | Zertifikat CN / SAN | plantpulse.io / automatisch |
NET1_IFACE / NET2_IFACE …, NET2_IP / NET2_GATEWAY / NET2_DNS | NIC-Zuordnung / statische IP | automatische Erkennung / DHCP |
IMAGE_TAG | docker-Image-Tag fixieren | latest |
SKIP_PULL=1 | docker pull überspringen (Air-Gap/erneuter Lauf) | 0 |
SKIP_COSIGN_VERIFY=1 | Prüfung der Image-Signatur überspringen | 0 (staging/standalone 1) |
dev.modeunterstützt sowohlEDGEals auchSTANDALONE; nurPLATFORMwird abgelehnt. BeiSTANDALONEentfallen die AbfragenSERVER_HOST/SERVER_API_KEY(server.hostblank →DiagnosticSenderinit skip).
7. JVM-Heap-env (Container)
| env | Komponente | Standard | Override-Beispiel |
|---|---|---|---|
HIVEMQ_HEAP | HiveMQ | -Xms2g -Xmx2g | 1g |
CASSANDRA_HEAP | Cassandra | auto auf Basis von host /proc/meminfo (~1/4) | 1g |
TOMCAT_HEAP | Tomcat | -Xms2g -Xmx2g | 1g |
Das Drop-in-Override für 8-GB-Boxen (override.conf) finden Sie unter Container-Modus §Ressourcengrenzen.
8. Wirksamwerden nach Änderungen
| Geändert | Wirksam durch |
|---|---|
PP_LANG / PP_TZ (i18n.env / env.sh) | Neustart von Container/Tomcat (Locale nur beim Booten) |
CERT_PASS (cert.env) | Container-Neustart (entrypoint patcht das Keystore-Passwort neu) |
PE_VERSION (version.env) | systemctl restart plantpulse-edge.service |
app.properties (Container) | config.sh --set … && config.sh --restart |
app.properties (native) | vi conf/app.properties → bin/restart.sh (~6 s) |
PP_LANG in app.properties einzutragen bleibt wirkungslos — die Sprache bestimmt die env-Ebene (env.sh / i18n.env).
Umgekehrt gehören Runtime-Keys wie cassandra.host nicht in env, sondern in app.properties.
9. Häufige Stolperfallen
| Symptom | Ursache / Abhilfe |
|---|---|
| UI-Sprache ändert sich nicht | in app.properties eingetragen oder kein Neustart. i18n.env (Container) / env.sh (native) anpassen und neu starten |
| Unter native gewinnt weiterhin ko | LOCALE in setenv.sh ist hartkodiert. ${PP_LANG} dynamisch machen (siehe 2.3) |
UnsupportedClassVersionError | JAVA_HOME ist nicht JDK 21 |
| Fehler beim OPC-UA-Keystore-Passwort | CERT_PASS in cert.env und opc.ua.server.keystore.password=${ENV:CERT_PASS:}-Mirror stimmen nicht überein |
Passwort erscheint in ps/Logs | statt argv *_FILE oder eine root-env-Datei mit 0600 sourcen |
| Konfigurationsänderung wirkt nicht | die von -Dpe.conf.dir referenzierte kanonische Datei wurde nicht bearbeitet (Container = /etc/kopens, native = $PE_HOME/conf) |
10. Weiterführende Dokumente
- app.properties-Leitfaden — alle Runtime-Konfigurations-Keys
- Konfigurationsbildschirm (
/ui/system/config) — app.properties im Web bearbeiten - Native Installation / Docker-(Container-)Installation im Detail
- Schnellinstallation (
install.sh) — Ablauf der env-Injektion bei der Installation - Betriebsleitfaden Container-Modus — config.sh / Ressourcengrenzen / OTA