Docker(コンテナ)インストール詳細 — plantpulse-edge.service

2026.05 以降、PlantPulse Edge の量産/現場標準配布は単一 Docker コンテナイメージです。 7つのコンポーネント(Tomcat / Cassandra / Redis / HiveMQ / TSE / Dashboard / Node-RED)が1つのイメージの中に 含まれており、install.sh が OS 依存関係から systemd 登録までを処理した後、plantpulse-edge.service が コンテナを管理します。

クイックインストール vs このページ

現場で1台を素早く立ち上げる手順の要約は クイックインストール (install.sh) にあります。 このページは、そのインストールが内部で何をしているのか — イメージ座標、docker run フラグ、bind mount、 EnvironmentFile、OTA — を深く掘り下げるリファレンスです。日常運用は コンテナモード運用ガイドを参照してください。

native との同時使用は禁止

コンテナは plantpulse-edge.service、native は plantpulse.service です。systemd unit に Conflicts=plantpulse.service が設定されていますが、両サービスを強制的に同時起動するとポート/データが競合します。

---

1. イメージ座標

項目	値
Registry	docker.kopens.io/pe (anonymous pull)
イメージ名	plantpulse-edge
完全座標	docker.kopens.io/pe/plantpulse-edge:<tag>
Tag 形式	<VERSION>-<BUILD_DATE> 例: 2026-20260524 (または latest)
ダウンロードサーバ	https://product.kopens.io/plantpulse-edge/ (LAN alias)

イメージ内の固定パス: KOPENS_HOME=/opt/kopens、PE_HOME=/opt/kopens/plantpulse-edge、 PE_DATA_DIR=/data1、JAVA_HOME=/usr/lib/jvm/java-21-openjdk。

---

2. インストールの流れ — bootstrap.sh → install.sh

2.1 ワンライナー

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

install.sh は bootstrap.sh と同一です。このスクリプトは:

1. repo tarball(plantpulse-edge-docker.tar.gz)を /opt/kopens/plantpulse-edge-docker/ に展開 (失敗時は git clone fallback)
2. PROFILE preset 適用(存在する場合、下記3章)
3. 対話型 prompt — Edge ID (MAC ベースで自動提示) / Site ID (デフォルト SITE_00001) / Mode (1=EDGE デフォルト / 2=STANDALONE) / EDGE モードの場合はプラットフォームサーバ + API key
4. install.sh 本体9ステップの実行

2.2 install.sh 9ステップ

#	ステップ
1	OS 検出 (Rocky/Alma/RHEL/Ubuntu/Debian)
2	Docker インストール (dnf または apt)
3	/data1、/etc/kopens、/var/log/kopens ディレクトリ作成
4	sysctl + firewalld ポート + chrony + hostname + nmcli static IP
5	/etc/kopens/app.properties 生成 (EDGE_ID / SITE_ID / 筐体ごとの random 認証情報)
6	systemd unit インストール — plantpulse-edge.service + OTA kopens-upgrade.path/.service
7	docker pull (cosign 署名検証 — デフォルトは soft-fail)
8	systemctl enable --now plantpulse-edge.service
9	cron weekly cleanup 登録

初回インストール時、admin / MQTT / OPC-UA / API key / keystore のパスワードが筐体ごとに random で生成され、 /etc/kopens/credentials.txt (chmod 0600 root) に1回だけ保存されます。

---

3. PROFILE preset

PROFILE env でサイト種別ごとのデフォルト値を一括適用します。

PROFILE	適用されるデフォルト値
production	DEV_MODE=EDGE (プラットフォームの SERVER_HOST/SERVER_API_KEY の明示が必要)
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 (プラットフォーム未接続)
airgap	IMAGE_URL=tarball、SKIP_PULL=1、DEV_MODE=STANDALONE (オフラインインストール)

# 양산 (플랫폼 연결)
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 クローン

staging 筐体は dev と同じ EDGE_00303 / SITE_00001 のクローンです。異なるべきなのは プラットフォーム接続情報(SERVER_HOST=192.168.0.235 / API key)のみです。プラットフォームに未登録の site を使うと エッジの自己診断 OPC が FK 違反で失敗するため、登録済みの EDGE/site をそのまま使います。 dev と同時にプラットフォームへ接続すると同一 edge と認識されるため、検証は重ならないように運用します。

インストール時によく使う env の全一覧は env 環境設定 §6 を参照してください。

---

4. systemd unit 解剖 — plantpulse-edge.service

install.sh が /etc/systemd/system/plantpulse-edge.service に配置する実際のコンテナ起動定義です。

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}

フラグ	意味
--network=host	9つのポートを自動公開 + multicast / OPC-UA discovery が自然に動作
--init	tini が PID 1 (zombie reap + signal forward)
--stop-timeout=120	Cassandra の graceful drain 時間を確保
--cap-drop=ALL + 個別 --cap-add	最小権限。NET_RAW は PLC ping、NET_BIND_SERVICE は 80/443 バインド用

4.2 bind mount

Host パス	コンテナパス	モード	用途
/data1	/data1	rw,z	データ (Cassandra/Redis/HiveMQ/Node-RED) — コンテナ入れ替えでも保持
/etc/kopens	/etc/kopens	rw,z	設定 + シグナルファイル
/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	ホストのタイムゾーン
/var/run/docker.sock	/var/run/docker.sock	rw	/ui/apps Docker アプリ管理

4.3 EnvironmentFile + デフォルト値

unit 組み込みのデフォルト値(ファイルが無い場合):

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 (存在すれば override — 最新値が優先):

ファイル	キー	生成者
/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 発行スクリプト

4.4 リソース上限 / 再起動ポリシー

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

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

8GB 筐体向けの heap 縮小 override(drop-in)は コンテナモード §リソース上限 を参照してください。

---

5. コンテナランタイムの設定読み込み経路

WAR モード(2026-06-13~)では、設定はホストの /etc/kopens から直接読み込みます — イメージの再ビルドは不要です。

/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: ホストの /etc/kopens/app.properties が source-of-truth。無い場合は entrypoint が image default で seed します。運用者が編集 → config.sh --restart で反映。
• log4j2.xml: entrypoint が起動ごとに webapp default から conf/log4j2.xml へコピー(コード成果物 — イメージ再ビルドなしでログレベルを変更して restart)。
• HiveMQ auth.properties: entrypoint が起動ごとに app.properties の mqtt.server.* と自動 sync — app.properties だけ修正すれば済みます。
• TLS パスワード: entrypoint が CERT_PASS を cert.env から解決し、Tomcat の server.xml / HiveMQ config / OPC-UA keystore のパスワードを一括パッチ。

env→設定のミラーリング詳細は env 環境設定、キーごとの意味は app.properties ガイド を参照してください。

---

6. OTA アップグレード / ロールバック

バージョンは /etc/kopens/version.env の PE_VERSION の1行で固定されます — OTA はこのファイルだけを変更して restart します。

# 최신으로 업그레이드 (pre-snapshot → pull → restart → 90초 health probe → 실패 시 auto-rollback)
sudo bash /opt/kopens/install/upgrade.sh

# 특정 tag 로
sudo bash /opt/kopens/install/upgrade.sh --to 2026-20260601

# 직전 tag 로 rollback
sudo bash /opt/kopens/install/upgrade.sh --rollback

# 새 빌드 존재만 확인
sudo bash /opt/kopens/install/upgrade.sh --check

手動ロールバック:

echo 'PE_VERSION=2026-20260524' > /etc/kopens/version.env
sudo systemctl restart plantpulse-edge.service

状態: cat /etc/kopens/upgrade.status → idle | running | success | rolling-back | rolled-back | error。 流れの詳細は コンテナモード §OTA。

---

7. デバッグ用の手動 docker run

運用では必ず systemd / install.sh 経由としますが、隔離デバッグ時の手動起動:

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>

配布はパイプライン経由のみ — イメージの (re)build / push / staging 再配布はローカルで行わず、 plantpulse-edge-docker のリリースチェーン(edge:libs → edge:deploy-dev → edge:image → edge:staging → edge:version、パイプライン変数 RELEASE=1 でトリガー)で実施します。上記コマンドは隔離デバッグ限定です。

---

8. インストール後の検証

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

画面	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

症状別の対処は インストールのトラブルシューティング、日常運用/障害は コンテナモード運用ガイド。

---

9. 次のドキュメント

• クイックインストール (install.sh) — 現場1台のインストール手順の要約
• env 環境設定 — PROFILE / PP_LANG / CERT_PASS / -Dpe.conf.dir
• ネイティブインストール — コンテナなしで直接インストール (dev/legacy)
• コンテナモード運用ガイド — pe-* ツール / ログ / 障害対応
• オフライン / 閉域網インストール / 量産ライン (factory.sh)
• プロダクション受入基準