Umgebungsvariablen-Konfiguration

Standardpasswörter müssen bei der Auslieferung an Kunden zwingend geändert werden

Die in diesem Dokument aufgeführten Passwörter (z. B. CERT_PASS) sind Standardwerte für interne Dev-Boxen und nicht geheim. Bei der Auslieferung an Kunden oder in die Serienproduktion dürfen sie nicht so verwendet werden:

install.sh generiert bei nicht spezifizierter CERT_PASS zufällig 14 Zeichen (bin/install.sh:298). Der generierte Wert wird in /etc/kopens/credentials.txt (0600, root) und im Factory-Label vermerkt.
Das Passwort für den Zugriff auf das Box-OS wird ebenfalls bei der Installation geändert.
Daher gelten die Standardwerte dieses Dokuments nur für eine einzige interne Dev-Box.

Die Konfiguration von PlantPulse Edge ist in zwei Ebenen unterteilt.

Ebene	Was	Wo
Umgebungsvariablen (env) ← Diese Seite	Sprache/Zeitzone, JDK-Pfad, TLS-Passwort, Datenpfad, Website-Werte bei Installation	`env.sh` / `/etc/kopens/*.env` / systemd / `docker -e`
Applikationskonfiguration (properties)	`edge.id` / `cassandra.` / `mqtt.` / OPC-UA etc. Runtime-Keys	`app.properties` → app.properties Referenz

Wenn die env-Ebene Sprache · Zeitzone · JVM-Optionen · Passwörter · Speicherort des Konfigurationsverzeichnisses festlegt, läuft darauf app.properties. Dies sind Werte, die einmal pro Box festgelegt werden und sich kaum noch ändern.

Reihenfolge der Wertbestimmung

env.sh ist die einzige Quelle, die von allen Installations-, Upgrade- und Startskripten gesourced wird. Wenn dieselbe Variable an mehreren Stellen definiert ist, gewinnt der zuerst festgelegte Wert — da die ${VAR:-기본값} der Shell nur greift, «wenn die Variable nicht vorhanden ist».

Reihenfolge	Wo	Was
1	`/etc/kopens/env.sh.generated`	Sidecar, das `install.sh` einmalig erstellt. `API_KEY` · `ADMIN_PASS` · `MQTT_PASS` · `OPCUA_PASS` · `CERT_PASS`. `0600` root
2	`${VAR:-기본값}` innerhalb von `env.sh`	In der Datei deklarierte Standardwerte
3	Operatoren-`export`-Zeilen am Ende von `env.sh`	Der zuletzt geschriebene Wert gewinnt

Das Sidecar liegt zwischen den Standardwerten und dem Operator

Geheimnisse, die bei der Installation erstellt wurden, bleiben auch beim erneuten Ausführen von install.sh erhalten (da Schritt 1 zuerst festgelegt wird). Falls ein Operator dennoch Werte erzwingen möchte, kann eine weitere Zeile mit export hinter env.sh hinzugefügt werden.

Wenn das Sidecar gelöscht und neu installiert wird, werden die Anmeldedaten neu generiert

Wenn /etc/kopens/env.sh.generated gelöscht wird und install.sh erneut ausgeführt wird, werden Passwörter und API-Keys neu generiert. Dies führt zu einer Diskrepanz mit den in der übergeordneten Platform registrierten API-Keys, wodurch die Erfassung stoppt — prüfen Sie /etc/kopens/credentials.txt, bevor Sie löschen.

1. Kern-env-Variablen auf einen Blick

Variable	Bedeutung	Standardwert
`PP_LANG`	UI/OS/JVM Sprache (BCP 47) — Einheitliche 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)	Zufällig bei Installation erstellt
`CLEAN_ON_STARTUP`	Bereinigung von work/temp beim Booten	`false`
`JAVA_TOOL_OPTIONS`	Gemeinsame Optionen für alle JVMs (entrypoint/`setenv.sh` injiziert Sprache/Zeitzone)	(Automatische Konfiguration)

Geheimwerte nicht in argv/Logs/History hinterlassen

CERT_PASS / SERVER_API_KEY / diverse Passwörter dürfen nicht in der Shell-History, den ps argv oder in Logs auftauchen. Führen Sie die Installation aus, nachdem Sie die Injektion über *_FILE (z. B. EDGE_ADMIN_PASSWORD_HASH_FILE, CASSANDRA_PASSWORD_FILE) oder root 0600 Dateien mittels source vorgenommen haben. Die von install.sh generierten zufälligen Anmeldedaten 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. Benutzerweise Cookies / Accept-Language werden ignoriert; webapp + Host-OS + Container-OS + 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 Propagationskette (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 Aufgaben des entrypoints im Container

container-entrypoint.sh bildet PP_LANG auf den POSIX-Locale ab und konfiguriert die JVM-Optionen:

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"

Dies wird auch in /etc/locale.conf, /etc/environment und /etc/timezone vermerkt, sodass es bei erneuter Anmeldung oder Tool-Aufrufen erhalten bleibt.

PpFixedLocaleResolver wird einmalig beim Booten gesetzt — Runtime-Änderung nicht möglich

Die Sprache wird einmal beim Booten festgelegt und kann nicht über Cookies / Accept-Language geändert werden. Ein Wechsel zwischen ko↔en erfordert eine Änderung von PP_LANG + Neustart von Container/Tomcat.

2.3 LOCALE im native Modus (`setenv.sh`)

Im native Modus muss die LOCALE von server/bin/setenv.sh dynamisch sein — es gab Fälle, in denen ein alter Hardcode in -Duser.language=ko -Duser.country=KR Vorrang vor JAVA_TOOL_OPTIONS hatte, wodurch «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 stehen export PP_LANG / export PP_TZ / export JAVA_HOME=/usr/lib/jvm/java-21-openjdk.

3. native `conf/env.sh`

Dies ist die Umgebungsdatei für die native Box. bin/start.sh sourct diese 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

Schlüssel	Bedeutung
`PE_HOME`	Gateway-Root (Pfad basierend auf dem Skript)
`PE_DATA_DIR`	Verzeichnis zur Datentrennung (üblicherweise separate Partition `/data1`)
`JAVA_HOME`	JDK 21, falls nicht spezifiziert `UnsupportedClassVersionError`
`PP_LANG` / `PP_TZ`	Sprache / Zeitzone (siehe Kapitel 2)
`CLEAN_ON_STARTUP`	Bereinigung von work/temp beim Booten

Die gesamte native Installationsstruktur entnehmen Sie bitte dem Installationsleitfaden.

4. Container `/etc/kopens/*.env` (systemd EnvironmentFile)

In der Container-Box liest die systemd-Unit die folgenden Dateien als EnvironmentFile ein und injiziert sie als docker -e. Wenn Dateien vorhanden sind, werden die in der Unit eingebetteten Standardwerte überschrieben.

Datei	Schlüssel	Ersteller	Zweck
`/etc/kopens/version.env`	`PE_VERSION=<tag>`	OTA `upgrade.sh`	Fixierung des Image-Tags — 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-Ausstellungs-Skript	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`

Dies sind die zentralen env/System-Properties, die bestimmen, wo app.properties und log4j2.xml gelesen werden. Im WAR-Modus (ab 2026-06-13) werden Konfigurationen direkt vom Host /etc/kopens gelesen — ein erneuter Build des Images/Deployments ist nicht erforderlich.

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: Der Host /etc/kopens/conf/app.properties ist die reale Datei und Source-of-Truth. /etc/kopens/app.properties ist ein Symlink, der darauf verweist (ln -sfn /etc/kopens/conf/app.properties /etc/kopens/app.properties).
log4j2.xml ist ein Code-Artefakt — der entrypoint kopiert dies bei jedem Booten aus dem webapp-Default (Änderungen an Loglevels werden nach Neustart übernommen, kein Image-Rebuild nötig).

Die Konfigurationsschlüssel selbst (was eingetragen wird) finden Sie in der app.properties Referenz und in den Web-UI Umgebungseinstellungen. Diese Seite behandelt, wo und wie diese Dateien gelesen werden.

6. env-Override bei install.sh Installation

Zum Zeitpunkt der Installation werden Box-Site-Werte, Netzwerk und Anmeldedaten als env injiziert (install.sh wird in app.properties reflektiert).

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`	`production` / `staging` / `standalone` / `airgap` Preset	—
`EDGE_ID`	Eindeutige Box-ID (`^EDGE_[A-Z0-9_]{1,60}$`)	Automatische Generierung basierend auf MAC
`SITE_ID`	Site-ID (Registrierung in Platform erforderlich)	`SITE_00001`
`DEV_MODE`	`EDGE` (Platform-Verbindung) / `STANDALONE` (keine Verbindung)	`EDGE`
`SERVER_HOST` / `SERVER_API_KEY`	Platform-API-Kopplung (erforderlich im EDGE-Modus)	—
`PP_LANG` / `PP_TZ`	Sprache / Zeitzone	`en` / `Asia/Seoul`
`ADMIN_PASS` / `API_KEY` / `MQTT_PASS` / `OPCUA_PASS`	Override der initialen Anmeldedaten	Zufällig pro Box
`CERT_PASS`	TLS-Keystore-Passwort	Zufällig bei Installation erstellt
`CERT_DOMAIN` / `CERT_SAN_DNS` / `CERT_SAN_IP`	Zertifikats-CN / SAN	`plantpulse.io` / Automatisch
`NET1_IFACE` / `NET2_IFACE` …, `NET2_IP` / `NET2_GATEWAY` / `NET2_DNS`	NIC-Mapping / Statische IP	Automatische Erkennung / DHCP
`IMAGE_TAG`	Fixierung des Docker-Image-Tags	`latest`
`SKIP_PULL=1`	Überspringen von docker pull (Airgap/Neustart)	`0`
`SKIP_COSIGN_VERIFY=1`	Überspringen der Image-Signaturprüfung bei Installation. Gilt nicht für OTA-Upgrades	`0` (Staging/Standalone `1`)

dev.mode unterstützt sowohl EDGE als auch STANDALONE, lehnt jedoch PLATFORM ab. Bei STANDALONE werden die Prompts für SERVER_HOST / SERVER_API_KEY übersprungen (server.host leer → DiagnosticSender Init übersprungen).

7. JVM-Heap-env (Container)

env	Komponente	Standard	Beispiel-Override
`HIVEMQ_HEAP`	HiveMQ	`-Xms2g -Xmx2g`	`1g`
`CASSANDRA_HEAP`	Cassandra	Automatisch basierend auf Host /proc/meminfo (~1/4)	`1g`
`TOMCAT_HEAP`	Tomcat	`-Xms2g -Xmx2g`	`1g`

Ein Drop-in-Override (override.conf) für 8GB-Boxen finden Sie unter Container-Modus Ressourcenlimits.

8. Anwendung von Änderungen

Geänderter Wert	Anwendungsmethode
`PP_LANG` / `PP_TZ` (i18n.env / env.sh)	Neustart von Container/Tomcat (Locale wird einmalig beim Booten gesetzt)
`CERT_PASS` (cert.env)	Neustart des Containers (entrypoint patcht das Keystore-Passwort erneut)
`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-app.sh` (nur App, 30~90 Sek.)

env-Ebene ≠ app.properties

Das Eintragen von PP_LANG in app.properties bewirkt keine Änderung — die Sprache wird durch die env-Ebene (env.sh / i18n.env) bestimmt. Umgekehrt werden Runtime-Keys wie cassandra.host nicht in der env, sondern in app.properties eingetragen.

9. Häufige Fehlerquellen

Symptom	Ursache / Lösung
UI-Sprache ändert sich nicht	In `app.properties` eingetragen oder Neustart nicht erfolgt. Nach Änderung von `i18n.env` (Container) / `env.sh` (native) neu starten
Im native Modus gewinnt dauerhaft «ko»	LOCALE in `setenv.sh` ist hardcodiert. Dynamisierung gemäß `${PP_LANG}` (siehe 2.3)
`UnsupportedClassVersionError`	`JAVA_HOME` ist nicht JDK 21
OPC-UA Keystore-Passwort Fehler	Spiegelung zwischen `CERT_PASS` und `opc.ua.server.keystore.password=${ENV:CERT_PASS:}` in `cert.env` ist nicht konsistent
Passwörter in `ps`/Logs sichtbar	Statt argv die Quelle über `*_FILE` oder root 0600 env-Datei nutzen
Konfigurationsänderungen greifen nicht	Die kanonische Datei, auf die `-Dpe.conf.dir` verweist, wurde nicht geändert (Container = `/etc/kopens`, native = `$PE_HOME/conf`)

10. Weiterführende Dokumente

app.properties Referenz — Alle Runtime-Konfigurationsschlüssel
Konfigurationsbildschirm (/ui/system/config) — Bearbeiten von app.properties über das Web
Installationsleitfaden / Docker Installation
Schnellinstallation (install.sh) — Verfahren zur env-Injektion bei Installation
Container-Modus Betrieb — config.sh / Ressourcenlimits / OTA

Reihenfolge der Wertbestimmung​

1. Kern-env-Variablen auf einen Blick​

2. Sprache / Zeitzone — PP_LANG / PP_TZ​

2.1 Propagationskette (4 Layer)​

2.2 Aufgaben des entrypoints im Container​

2.3 LOCALE im native Modus (setenv.sh)​

3. native conf/env.sh​

4. Container /etc/kopens/*.env (systemd EnvironmentFile)​

5. Speicherort des Konfigurationsverzeichnisses — -Dpe.conf.dir​

6. env-Override bei install.sh Installation​

7. JVM-Heap-env (Container)​

8. Anwendung von Änderungen​

9. Häufige Fehlerquellen​

10. Weiterführende Dokumente​