環境変数の設定

デフォルトパスワードは顧客先への配布時に必ず変更される

このドキュメントに記載されているパスワード（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 が動作します。ボックス単位で一度決定すると、ほとんど変更されない値です。

値が決定される順序

env.sh はインストール・アップグレード・起動スクリプトがすべて source する単一ソースです。同じ変数が複数箇所にある場合、先に定義されたものが優先されます。シェルの ${VAR:-기본값} は VAR が「ない場合のみ」発動するためです。

順序	場所	内容
1	`/etc/kopens/env.sh.generated`	`install.sh` が最初の一回に作成するサイドカー。`API_KEY` ・ `ADMIN_PASS` ・ `MQTT_PASS` ・ `OPCUA_PASS` ・ `CERT_PASS`。`0600` root
2	`env.sh` 内の `${VAR:-기본값}`	ファイルで宣言されたデフォルト値
3	`env.sh` 後方のオペレーター `export` 行	最後に記述したものが優先される

サイドカーはデフォルト値とオペレーターの間に位置します

インストール時に作成された秘密情報は install.sh を再実行しても保存されます（1番が先に決定されるため）。それでもオペレーターが値を強制したい場合は、env.sh の後方に export を1行追加してください。

サイドカーを削除して再インストールすると資格情報が新しく生成されます

/etc/kopens/env.sh.generated を削除した状態で install.sh を再実行すると、パスワードとAPIキーが 新しく生成されます。上位プラットフォームに登録したAPIキーと不一致となり、収集が停止します。削除前に /etc/kopens/credentials.txt を確認してください。

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 共通)	インストール時にランダム生成
`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 が生成するランダム資格情報は /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 伝搬チェーン (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回のみ — ランタイム変更不可

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

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

native では server/bin/setenv.sh の LOCALE が動的である必要があります。以前、ハードコードされた -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 ユニットが以下のファイルを EnvironmentFile として読み込み、docker -e として注入します。ファイルが存在する場合、ユニット内蔵のデフォルト値をオーバーライドします。

ファイル	キー	作成者	用途
`/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 ユニットの詳細解析はドッカーインストール §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 はそれを指すシンボリックリンクです (ln -sfn /etc/kopens/conf/app.properties /etc/kopens/app.properties)。
log4j2.xml はコード成果物です。entrypoint が毎起動時に webapp default からコピーします（ログレベルのみ変更して restart すると反映され、イメージ再ビルドは不要です）。

設定キー自体の内容は app.properties リファレンスとウェブUI環境設定を参照してください。このページでは、そのファイルをどこで/どのように読み込むかを扱います。

6. install.sh インストール時の env オーバーライド

インストール時にボックスサイト値/ネットワーク/資格情報を 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` プリセット	—
`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`	初期資格情報オーバーライド	ボックス別ランダム
`CERT_PASS`	TLS keystore パスワード	インストール時にランダム生成
`CERT_DOMAIN` / `CERT_SAN_DNS` / `CERT_SAN_IP`	証明書 CN / SAN	`plantpulse.io` / 自動
`NET1_IFACE` / `NET2_IFACE` …, `NET2_IP` / `NET2_GATEWAY` / `NET2_DNS`	NICマッピング / 固定IP	自動検知 / DHCP
`IMAGE_TAG`	docker イメージ tag 固定	`latest`
`SKIP_PULL=1`	docker pull 省略 (airgap/再実行)	`0`
`SKIP_COSIGN_VERIFY=1`	インストール時のイメージ署名検証省略。OTAアップグレードには適用されません	`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	コンポーネント	デフォルト	オーバーライド例
`HIVEMQ_HEAP`	HiveMQ	`-Xms2g -Xmx2g`	`1g`
`CASSANDRA_HEAP`	Cassandra	host /proc/meminfo ベース auto (~1/4)	`1g`
`TOMCAT_HEAP`	Tomcat	`-Xms2g -Xmx2g`	`1g`

8GBボックスのドロップイン・オーバーライド（override.conf）はコンテナモード資源限度に記載されています。

8. 変更後の反映

変更内容	反映方法
`PP_LANG` / `PP_TZ` (i18n.env / env.sh)	コンテナ/Tomcat 再起動 (ロケールは起動時に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-app.sh` (アプリのみ、30~90秒)

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 がハードコードされている。`${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:}` ミラーの不一致
パスワードが `ps`/ログに露出	argv の代わりに `*_FILE` または root 0600 env ファイルを source
設定変更が反映されない	`-Dpe.conf.dir` が指す canonical ファイルを修正していない (コンテナ=`/etc/kopens`, native=`$PE_HOME/conf`)

10. 次のドキュメント

app.properties リファレンス — ランタイム設定キー一覧
環境設定画面 (/ui/system/config) — ウェブでの app.properties 編集
インストールガイド / Dockerインストール
クイックインストール (install.sh) — インストール時の env 注入手順
コンテナモード運用 — config.sh / 資源限度 / OTA

値が決定される順序​

1. 主要env変数の概要​

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

2.1 伝搬チェーン (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 オーバーライド​

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

8. 変更後の反映​

9. よくある陥りやすい点​

10. 次のドキュメント​