Docker 設置

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

クイック設置 vs このページ

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

native との同時使用禁止

---

1. イメージ座標

項目	値
Registry	docker.kopens.io/pe (anonymous pull)
イメージ名	plantpulse-edge
全体座標	docker.kopens.io/pe/plantpulse-edge:<tag>
Tag 形式	YYYY.MM-YYYYMMDD-HHMM 例: 2026.11-20261103-1006 (設置時は latest も可能、OTA は不変タグのみ)
ダウンロードサーバ	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. install.sh 本体 9段階実行

⌨️ 設置時の«問い合わせ項目» — 空値にした場合に再質問されるシーンが含まれています。実際に設置を走らせた画面ではなく（録画する機械が本当に設定されてしまうため）、設置機が使用するプロンプトライブラリをそのまま実行して再現したものです。再質問などの«動作»は本物であり、項目リストは CI が設置機の宣言と双方向に照合し、乖離が起きないように管理しています

モードによって«問い合わせ内容»が異なります — 基本は EDGE

ターミナルで直接実行すると問い合わせが発生します(基本動作)。大括弧内がデフォルト値であり、Enter で承諾します。

• EDGE(基本) — プラットフォームアドレスと API キーを必ず問い合わせ、空欄の場合は再問い合わせします。
• STANDALONE — 上記の2項目を一切問い合わせません。
• Edge id デフォルト値はボックスごとに異なります (NET1 MAC から導出された EDGE_3F8A21 形式)。 現場番号を指定する場合は、ここで入力してください。

curl | bash では問い合わせできません — 値を環境変数で指定してください

パイプで実行するとターミナルが接続されていないため、問い合わせができません。その場合は**「問い合わせ不可」と通知した後**、環境変数とデフォルト値で進行します（静かにスキップされることはありません）。

curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh | \
  sudo EDGE_ID=EDGE_00303 DEV_MODE=EDGE \
       SERVER_HOST=<플랫폼IP> SERVER_API_KEY=<token> bash

値を問い合わせさせるには、スクリプトをダウンロードして直接実行してください。自動化 (CI・無人設置) では INTERACTIVE=0 で確実にオフにする方が安全です。

運用者が設定する箇所は env.sh のみです

スクリプトと同じフォルダの env.sh に記述しておけば、設置時に自動的に読み込まれます。再設置時も同じ値がそのまま適用されます。

2.1a 設置中にプラットフォームキーを«検証します»

DEV_MODE=EDGE の場合、設定を書き込む前にプラットフォームに実際に問い合わせます。以前は値が空であるかのみを確認して設置を終了していたため、起動後にすべての接続が 401 で失敗していました。

状況	設置機の動作
プラットフォームに到達不能	警告のみ — まだ起動していないか、ファイアウォールの設定待ちである可能性があります
サーバが 5xx	警告のみ — 判定不能であり、キーの問題ではありません
401 · 403	🔴 中断 — キーが拒否されました。タイポはこの段階で検知されます
400	🔴 中断 — 設置機側の問題であるため、報告してください

プラットフォームより先に設置する必要がある場合は SKIP_PLATFORM_VERIFY=1 でオフにします。

2.1b 使用方法は --help が正本です

sudo bash install.sh --help      # root 없이도 읽힙니다

⌨️ `--help` 全文 — 0.04秒に一度に表示される出力であるため«静止画»として掲載しています。設置機と«同一の発行実行»から得られた録画であり、現在ダウンロードされるスクリプトの画面です

バナーと共に USAGE · MODE decides what else is required · IDENTITY · PLATFORM · IMAGE · NETWORK · SKIP FLAGS · PROFILE · AFTER INSTALL 節が表示されます。この文書に全文を転記しない理由は、転記されたコピーは静かに陳腐化するためです。実際にこのリポジトリでヘッダーとコードのデフォルト値が乖離していた事例がありました。

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 署名検証 — 設置時は警告のみ、アップグレード時は検証不能な場合に中断)
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 と同時にプラットフォームへ接続すると、同一のエッジとして認識されるため、検証は重複しないように運用してください。

設置時に頻繁に使用される 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.* と自動同期 — app.properties のみを修正すれば完了。
• TLS パスワード: entrypoint が CERT_PASS を cert.env で解釈し、Tomcat server.xml / HiveMQ config / OPC-UA keystore パスワードを一括パッチ。

詳細な env→設定ミラーリングは 環境変数設定、キー別の意味は app.properties リファレンス を参照してください。

---

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

バージョンは /etc/kopens/version.env に固定されます — OTA がこのファイルを検証済みのダイジェストに変更し restart させます。

# 자동 (META-INF/VERSION.JSON 이 가리키는 빌드)
sudo bash /opt/kopens/install/upgrade.sh

# 특정 불변 태그 (YYYY.MM-YYYYMMDD-HHMM). 움직이는 태그는 거부합니다
sudo bash /opt/kopens/install/upgrade.sh --to 2026.11-20261103-1006

# 진행 중인 현재 업그레이드만 롤백 (trial · rollback_failed 상태에서만)
sudo bash /opt/kopens/install/upgrade.sh --rollback

# 사전 점검만 (0 최신, 10 새 빌드 있음)
sudo bash /opt/kopens/install/upgrade.sh --check

状態: cat /etc/kopens/upgrade.status → idle · downloading · verified · snapshot · switching · trial · committed · rolling_back · rolled_back · rollback_failed. フローの詳細は アップグレード を参照してください。

---

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
ウェブ 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台設置手順要約
• 環境変数設定 — PROFILE / PP_LANG / CERT_PASS / -Dpe.conf.dir
• コンテナモード運用 — pe-* ツール / ログ / 障害対応
• 閉域網設置 / 量産ライン (factory.sh)
• プロダクション 인수基準