env 環境設定 — env.sh / PPLANG / CERTPASS / -Dpe.conf.dir

デフォルトパスワードは顧客への配備時に必ず変更する

本ドキュメントに登場するパスワード(CERT_PASS など)は 社内 dev ボックスのデフォルト値 であり、秘密情報ではありません。顧客向け/量産配備ではそのまま使用しないでください:

install.sh は CERT_PASS が未指定の場合、14文字のランダム値を生成します(bin/install.sh:298)。生成された値は /etc/kopens/credentials.txt(0600, root)と factory ラベルに記録されます。
ボックス OS のログインパスワードもインストール時に変更します。
したがって、ドキュメントのデフォルト値が有効な範囲は 社内 dev ボックス1台のみ です。

PlantPulse Edge の設定は 2つのレイヤー に分かれます。

レイヤー	内容	場所
環境変数 (env) ← 本ページ	言語/タイムゾーン、JDK パス、TLS パスワード、データパス、インストール時のサイト値	`env.sh` / `/etc/kopens/*.env` / systemd / `docker -e`
アプリケーション設定 (properties)	`edge.id` / `cassandra.` / `mqtt.` / OPC-UA などのランタイムキー	`app.properties` → app.properties ガイド

env レイヤーが 言語・タイムゾーン・JVM オプション・パスワード・設定ディレクトリの位置 を決定し、その上で app.properties が動作します。ボックス単位で一度決めればほとんど変更されない値です。

1. 主要 env 変数一覧

変数	意味	デフォルト値
`PP_LANG`	UI/OS/JVM の言語 (BCP 47) — ボックス単位で単一言語	`en`
`PP_TZ`	タイムゾーン (`java.util.TimeZone` ID)	`Asia/Seoul`
`JAVA_HOME`	JDK パス (class file 65 → JDK 21)	`/usr/lib/jvm/java-21-openjdk`
`PE_HOME`	ゲートウェイルート	`/opt/kopens/plantpulse-edge`
`PE_DATA_DIR`	データディレクトリ (Cassandra/Redis/HiveMQ/Node-RED)	`/data1`
`CERT_PASS`	TLS keystore パスワード (Tomcat/HiveMQ/OPC-UA 共通)	`kopens123!` (legacy) / インストール時に random
`CLEAN_ON_STARTUP`	起動時に work/temp を整理するか	`false`
`JAVA_TOOL_OPTIONS`	全 JVM 共通オプション (entrypoint/`setenv.sh` が言語/タイムゾーンを注入)	(自動構成)

秘密値を argv/ログ/履歴に残さないでください

CERT_PASS / SERVER_API_KEY / 各種 password は shell history、ps argv、ログに露出してはいけません。 *_FILE による注入(例: EDGE_ADMIN_PASSWORD_HASH_FILE、CASSANDRA_PASSWORD_FILE)または root 0600 のファイルを source したうえでインストールを実行してください。install.sh が生成する random 資格情報は /etc/kopens/credentials.txt (chmod 0600 root) に1回だけ保存されます。

2. 言語 / タイムゾーン — `PP_LANG` / `PP_TZ`

PlantPulse は ボックス単位の単一言語/タイムゾーン を強制します。ユーザーごとの cookie / Accept-Language は無視され、webapp + ホスト OS + コンテナ OS + JVM が すべて同じ値 を使用します。

PP_LANG=en  PP_TZ=Asia/Seoul   # 글로벌 default (영문 UI + 한국 시간)
PP_LANG=ko  PP_TZ=Asia/Seoul   # 완전 한국 박스
PP_LANG=en  PP_TZ=UTC          # 완전 영문 박스

2.1 伝播 chain (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 コンテナで entrypoint が行うこと

container-entrypoint.sh が PP_LANG を POSIX locale にマッピングし、JVM オプションを構成します:

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"

/etc/locale.conf、/etc/environment、/etc/timezone にも記録され、再ログインやツール呼び出しでも維持されます。

PpFixedLocaleResolver は起動時1回のみ — runtime 変更は不可

言語は起動時に一度決定され、cookie / Accept-Language では変更できません。 ko↔en の切り替えには PP_LANG の変更 + コンテナ/Tomcat の再起動 が必要です。

2.3 native モードの LOCALE (`setenv.sh`)

native では server/bin/setenv.sh の LOCALE が動的である必要があります — 旧来の hardcode -Duser.language=ko -Duser.country=KR が JAVA_TOOL_OPTIONS より優先され、ko が勝ってしまう事例がありました。

# server/bin/setenv.sh
LOCALE="-Duser.language=${PP_LANG:-en} -Duser.country=${PP_COUNTRY:-US} -Duser.timezone=${PP_TZ:-Asia/Seoul}"

そして conf/env.sh に export PP_LANG / export PP_TZ / export JAVA_HOME=/usr/lib/jvm/java-21-openjdk。

3. native `conf/env.sh`

native ボックスの環境ファイルです。bin/start.sh が起動前に source します。

# $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

キー	意味
`PE_HOME`	ゲートウェイルート (スクリプトの基準パス)
`PE_DATA_DIR`	データ分離ディレクトリ (通常は別パーティション `/data1`)
`JAVA_HOME`	JDK 21 未指定時は `UnsupportedClassVersionError`
`PP_LANG` / `PP_TZ`	言語 / タイムゾーン (上記2章)
`CLEAN_ON_STARTUP`	起動時に work/temp を整理

native インストール構成の全体はネイティブインストールを参照してください。

4. コンテナ `/etc/kopens/*.env` (systemd EnvironmentFile)

コンテナボックスでは systemd unit が以下のファイルを EnvironmentFile として読み込み、docker -e に注入します。ファイルが存在する場合、unit 内蔵のデフォルト値を override します。

ファイル	キー	生成元	用途
`/etc/kopens/version.env`	`PE_VERSION=<tag>`	OTA `upgrade.sh`	イメージ tag の固定 — OTA/rollback はこの1行のみを変更
`/etc/kopens/i18n.env`	`PP_LANG` / `PP_TZ`	`install.sh`	言語 / タイムゾーン
`/etc/kopens/cert.env`	`CERT_PASS`	TLS 発行スクリプト	keystore パスワード

# 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!

言語を変更するには:

sudo tee /etc/kopens/i18n.env <<'EOF'
PP_LANG=ko
PP_TZ=Asia/Seoul
EOF
sudo systemctl restart plantpulse-edge.service

systemd unit 全体の詳細は Docker インストール §4 を参照してください。

5. 設定ディレクトリの位置 — `-Dpe.conf.dir`

app.properties と log4j2.xml を どこから読むか を決定する中核的な env/システムプロパティです。 WAR モード(2026-06-13~)では設定はホストの /etc/kopens から直接読み込まれるため、イメージ/バッチの再ビルドは不要です。

モード	`-Dpe.conf.dir`	canonical ファイル
コンテナ	`/opt/kopens/plantpulse-edge/conf` (= host `/etc/kopens/conf` の bind-mount)	`/etc/kopens/app.properties`
native	`$PE_HOME/conf`	`$PE_HOME/conf/app.properties`

コンテナ: ホストの /etc/kopens/conf/app.properties が実ファイルであり source-of-truth です。 /etc/kopens/app.properties はそれを指す legacy 互換のシンボリックリンクです (ln -sfn /etc/kopens/conf/app.properties /etc/kopens/app.properties)。
log4j2.xml は コードの生成物 — entrypoint が起動ごとに webapp default からコピーします(ログレベルのみ変更して restart すれば反映され、イメージの再ビルドは不要)。

設定キー自体(何を記述するか)は app.properties ガイドと環境設定画面を参照してください。本ページはそのファイルを どこから/どのように読むか を扱います。

6. install.sh インストール時の env override

インストール時点でボックスのサイト値/ネットワーク/資格情報を env で注入します(install.sh が app.properties に反映)。

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

変数	意味	デフォルト値
`PROFILE`	`production` / `staging` / `standalone` / `airgap` preset	—
`EDGE_ID`	ボックス固有 ID (`^EDGE_[A-Z0-9_]{1,60}$`)	MAC ベースで自動生成
`SITE_ID`	サイト ID (プラットフォーム登録に必須)	`SITE_00001`
`DEV_MODE`	`EDGE` (プラットフォーム接続) / `STANDALONE` (未接続)	`EDGE`
`SERVER_HOST` / `SERVER_API_KEY`	プラットフォーム API 連携 (EDGE モードで必須)	—
`PP_LANG` / `PP_TZ`	言語 / タイムゾーン	`en` / `Asia/Seoul`
`ADMIN_PASS` / `API_KEY` / `MQTT_PASS` / `OPCUA_PASS`	初期資格情報の override	ボックスごとに random
`CERT_PASS`	TLS keystore パスワード	`kopens123!`(legacy) / random
`CERT_DOMAIN` / `CERT_SAN_DNS` / `CERT_SAN_IP`	証明書 CN / SAN	`plantpulse.io` / 自動
`NET1_IFACE` / `NET2_IFACE` …、`NET2_IP` / `NET2_GATEWAY` / `NET2_DNS`	NIC マッピング / static IP	自動検出 / DHCP
`IMAGE_TAG`	docker イメージ tag の固定	`latest`
`SKIP_PULL=1`	docker pull の省略 (airgap/再実行)	`0`
`SKIP_COSIGN_VERIFY=1`	イメージ署名検証の省略	`0` (staging/standalone `1`)

dev.mode は EDGE と STANDALONE の両方をサポートし、PLATFORM のみ reject されます。STANDALONE 時は SERVER_HOST / SERVER_API_KEY のプロンプトは省略されます (server.host blank → DiagnosticSender init skip)。

7. JVM heap env (コンテナ)

env	コンポーネント	デフォルト	override 例
`HIVEMQ_HEAP`	HiveMQ	`-Xms2g -Xmx2g`	`1g`
`CASSANDRA_HEAP`	Cassandra	host /proc/meminfo ベースの auto (~1/4)	`1g`
`TOMCAT_HEAP`	Tomcat	`-Xms2g -Xmx2g`	`1g`

8GB ボックス向けの drop-in override(override.conf)はコンテナモード §リソース上限にあります。

8. 変更後の反映

変更した内容	反映方法
`PP_LANG` / `PP_TZ` (i18n.env / env.sh)	コンテナ/Tomcat の再起動 (locale は起動時1回)
`CERT_PASS` (cert.env)	コンテナ再起動 (entrypoint が keystore パスワードを再パッチ)
`PE_VERSION` (version.env)	`systemctl restart plantpulse-edge.service`
`app.properties` (コンテナ)	`config.sh --set … && config.sh --restart`
`app.properties` (native)	`vi conf/app.properties` → `bin/restart.sh` (約6秒)

env レイヤー ≠ app.properties

PP_LANG を app.properties に記述しても適用されません — 言語は env レイヤー(env.sh / i18n.env)が決定します。逆に cassandra.host のようなランタイムキーは env ではなく app.properties に記述します。

9. よくある落とし穴

症状	原因 / 解決
UI 言語が変わらない	`app.properties` に記述している、または再起動していない。`i18n.env`(コンテナ)/`env.sh`(native) を修正後に再起動
native で ko が勝ち続ける	`setenv.sh` の LOCALE が hardcode。`${PP_LANG}` を動的化 (上記2.3)
`UnsupportedClassVersionError`	`JAVA_HOME` が JDK 21 ではない
OPC-UA keystore password エラー	`cert.env` の `CERT_PASS` と `opc.ua.server.keystore.password=${ENV:CERT_PASS:}` の mirror が不一致
パスワードが `ps`/ログに露出	argv の代わりに `*_FILE` または root 0600 の env ファイルを source
設定変更が反映されない	`-Dpe.conf.dir` が指す canonical ファイルを修正していない (コンテナ=`/etc/kopens`、native=`$PE_HOME/conf`)

10. 次のドキュメント

app.properties ガイド — ランタイム設定キー全一覧
環境設定画面 (/ui/system/config) — Web から app.properties を編集
ネイティブインストール / Docker(コンテナ)インストール詳細
クイックインストール (install.sh) — インストール時の env 注入手順
コンテナモード運用ガイド — config.sh / リソース上限 / OTA

1. 主要 env 変数 一覧​

2. 言語 / タイムゾーン — PP_LANG / PP_TZ​

2.1 伝播 chain (4 layer)​

2.2 コンテナで entrypoint が行うこと​

2.3 native モードの LOCALE (setenv.sh)​

3. native conf/env.sh​

4. コンテナ /etc/kopens/*.env (systemd EnvironmentFile)​

5. 設定ディレクトリの位置 — -Dpe.conf.dir​

6. install.sh インストール時の env override​

7. JVM heap env (コンテナ)​

8. 変更後の反映​

9. よくある落とし穴​

10. 次のドキュメント​