スタートガイド

概要

ワンラインインストールまたは Docker インストールで PlantPulse Platform をインストールされた場合、すべての運用スクリプトは /opt/kopens/plantpulse-platform-docker/bin/ ディレクトリにあります。このページでは、Docker Compose スタックとして動作する Platform の起動および運用方法を案内します。

Platform は 9 つのコンテナで構成されます — 証明書 1 つ、データレイク 1 つ、アプリ 6 つ、プロキシ 1 つ。9 つすべてが常時動作します。 全体の構成は Docker インストール — インストールされる構成にあります。

古いスクリプト名を使用している場合

以下の左側の名前はもう存在しません。 右側の共通動詞を使用してください。

旧名称	現在の名称
`start.sh`	`up.sh`
`platform-stop.sh`	`down.sh`
`platform-update.sh`	`update.sh`
`platform-remove.sh`	`remove.sh`
`platform-bash.sh`	`shell.sh`
`platform-verify-boot.sh`	`stack-verify-boot.sh`
`worker-run.sh` · `worker-stop.sh` · `worker-update.sh` · `worker-bash.sh`	ワーカー管理を参照

stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh はそのまま動作します（新しい名前を一行案内した後、同じ処理を行います）。

環境変数設定

Platform の起動前に環境変数を確認してください。リソース値はインストール時にホストを参照して自動計算されるため、ほとんどのサーバーでは変更する必要はほぼありません。

vi /opt/kopens/plantpulse-platform-docker/bin/env.sh

よく調整される項目

変数	説明	デフォルト値
`PP_LANG`	Platform ロケール (`ko` / `en`)	`en`
`PP_TZ`	Platform タイムゾーン	`Asia/Seoul`
`DOCKER_PP_CPUS`	コンテナに割り当てる vCPU 数	`nproc` の結果
`DOCKER_PP_MEMORY`	メモリ上限	ホスト RAM の 90%
`DOCKER_DATALAKE_MEMORY`	データレイクメモリ上限	`96G`（最小値、ホスト RAM の 90% を超えない — ホスト 107G 未満は要件未達）
`DOCKER_PP_DATA_DISK_NAME`	データディスク名	自動逆追跡 (失敗時は `sda`)
`DOCKER_PP_EXTERNAL_IP`	NAT 環境の外部 advertise IP	空値

環境変数の全リストは環境変数リファレンスページを参照してください。

変更の適用: env.sh を修正した後は、必ず ./restart.sh で再起動해야 새 설정이 반영됩니다.

パスワードは env.sh で変更できません

インストールが完了したノードでは、シークレットサイドカー(/etc/kopens/plantpulse-platform.env)が env.sh およびシェル export の両方よりも優先されます。 パスワード変更はパスワードローテーションの passwd.sh を使用してください。

Platform 起動

初回インストール後の起動

インストール(install.sh)が完了すると、スタックは既に実行されています。状態のみ確認してください。

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh

停止したスタックの起動

./down.sh またはホストの再起動などでスタックが停止した場合、再起動します。

cd /opt/kopens/plantpulse-platform-docker/bin
./up.sh

up.sh は冪等であり、準備が整うまで待機します。 終了コード 0 は「コマンドが成功した」ということではなく、「今から利用可能である」 という意味です。

環境変数	デフォルト値	意味
`PP_READY_TIMEOUT`	`900`	準備待機上限(秒)
`PP_READY_INTERVAL`	`15`	確認間隔(秒)
`PP_WAIT=0`	—	待機しない (この時の `0` は準備完了ではありません)

ボリューム(pp-data, pp-temp, pp-backup, pp-security, pp-proxy-certs)のデータはそのまま維持されます。テンプレート/設定はホストバインドマウント(/etc/kopens/conf)で管理されます。

起動順序

コンテナは compose の depends_on で定められた順序で起動します。service_healthy 条件であるため、「プロセスが起動した」ことではなく「利用可能である」ことを待ちます。

plantpulse-certs        (healthy 까지)
      │
plantpulse-datalake     (healthy 까지)
      │
plantpulse-server-web   (healthy 까지) ──── plantpulse-proxy
      │
plantpulse-batch-web    (healthy 까지)
      │
      ├── plantpulse-warehouse
      ├── plantpulse-plugin-opcua
      ├── plantpulse-plugin-aasx
      └── plantpulse-ha        (이 넷은 서로 순서가 없습니다)

データレイクコンテナ内部では、インフラコンポーネントが再び順に起動します。

順序	カテゴリ	コンポーネント
1	ストレージ	Valkey(Redis), PostgreSQL, Aster TSDB, RustFS
2	分析	Spark, Hadoop, Hive, Kyuubi, Gravitino
3	時系列	時系列エンジン, 時系列 UI
4	メッセージング	Kafka, MQTT
5	ワークフロー	Temporal, Kestra
6	処理	CEP, Data Gateway, SQL, Monitor

所要時間

プロセス自体の起動は 3~~5 分（JVM ウォーミングアップ）ですが、クリーンインストールでは**全コンポーネントが安定するまで 15~~18 分**かかります。Aster TSDB のスキーママイグレーションと安定化が最も時間を要します。

実測(2026-08-31, 32 vCPU / 128GiB): データレイク 217秒, ウェブサーバー 316秒. データが既に存在する再起動はこのより大幅に高速です。

ブート検証

cd /opt/kopens/plantpulse-platform-docker/bin
./stack-verify-boot.sh

stack-verify-boot.sh はコンテナ単体ではなくスタック全体を判定します — 9 つすべてが running·healthy であるか、プロキシが 443 をサービスしているかまで確認します。

up.sh と restart.sh はこのスクリプトがパスするまでポーリングし、それが 2 つのコマンドの終了コード 0 が「利用可能である」ことを意味する根拠となります。

正常起動の確認

# 서비스 / health / 볼륨 요약 (0 = 정상 / 2 = 비정상)
./status.sh

# 운영 health + 최근 critical log 점검
./ops-check.sh

# 헬스체크 엔드포인트 직접 호출
curl -kfsS https://<server-ip>:4950/api/health | jq

# Docker 상태
docker ps

docker ps で** 9 つすべてが (healthy)** であれば正常です。

Platform 停止

cd /opt/kopens/plantpulse-platform-docker/bin
./down.sh

スタックを安全に停止します。データは Docker ボリュームにそのまま保存されるため、./up.sh で再起動すれば以前の状態が維持されます。

注意: docker kill やホストの強制終了はデータ整合性を損なう可能性があります。必ず ./down.sh を使用してください。

Platform 再起動

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh

内部コンポーネントを graceful に終了(drain)させた後、スタックを依存順序の逆順で停止し、再び depends_on の順序で起動して準備が整うまで待機します。

env.sh の変更、運用中に発生した一時的な問題の解消、定期的な再起動に使用します。

サービス状態確認

全体サマリ

./status.sh

サービスリスト、コンテナ状態、health 結果、ボリューム情報を一括して表示します。終了コードが仕様です — 0 が正常、2 が異常であるため、監視自動化にそのまま利用できます。

運用点検

./ops-check.sh

コンテナ health、ヘルス API 応答、最近の critical ログを併せて検査します。** 8 つのコンテナすべて**を走査します。

ホスト側リソース確認

docker stats --no-stream        # 컨테이너별 CPU / 메모리
docker ps                       # 컨테이너 상태

コンテナごとに mem_limit が設定されているため、どのコンテナが限界に達しているかを個別に確認できます。アプリ別限界値は環境変数リファレンスにあります。

コンテナ内部接続

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh                          # 인자가 없으면 데이터레이크
./shell.sh plantpulse-server-web    # 특정 컨테이너

接続可能なサービスリストは ./status.sh で確認します。

クラスターワーカーはこのリストに含まれません

shell.sh は基本スタックのサービスのみを名前で解決します。ワーカーは生成されたオーバーレイ(compose/docker-compose.worker.yml)にあるため、docker exec -ti plantpulse-worker-<n> /bin/bash で接続します。

コンポーネント単位の再起動

コンテナが分かれているため、再起動方法も 2 種類あります。

アプリ 6 つ — コンテナ単位で再起動

アプリはそれぞれ自身のコンテナで動作するため、コンテナを再起動させることがそのままそのアプリの再起動となります。他のアプリやインフラには影響しません。

cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web

コンテナ	動作内容
`plantpulse-server-web`	ウェブコンソール
`plantpulse-batch-web`	バッチ
`plantpulse-warehouse-web`	データウェアハウス
`plantpulse-plugin-opcua`	OPC-UA プラグイン
`plantpulse-plugin-aasx`	AASX プラグイン
`plantpulse-ha`	二重化復旧デーモン

docker compose restart は依存順序を遵守しません

複数のアプリを同時に復旧させる必要がある場合は、./restart.sh でスタック全体を再起動する方が安全です。起動順序は plantpulse-server-web → plantpulse-batch-web → 残り 4 つです。

データレイク内コンポーネント — コンテナ内部スクリプト

ストレージ・分析・メッセージングなどのインフラコンポーネントは plantpulse-datalake コンテナ** 1 つの中で**共に動作するため、コンテナ内部に入り個別のスクリプトを使用します。

# 호스트에서 데이터레이크 진입
./shell.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

スクリプト	対象
`pd restart storage`	Aster TSDB, PostgreSQL, Valkey, RustFS
`pd restart analytics`	Spark, Hive, Kyuubi, Gravitino
`pd restart messaging`	Kafka, MQTT
`pd restart timeseries`	時系列エンジンおよび UI
`pd restart workflow`	Temporal, Kestra
`pd restart cep`	複合イベント処理エンジン
`pd restart data-gateway`	データ照会ゲートウェイ
`pd restart admin-api`	管理コンソール API (2026-09-03 まで «monitor»)

受け付ける名称は services/order.txt にあるもののみです — storage · analytics · messaging · timeseries · cep · workflow · data-gateway · admin-api. それ以外の名称は unknown service で終了します。SQL クエリツール(Kyuubi·Hive)は単独ではなく analytics に含まれています。

参考: インフラコンポーネントを再起動した場合、そのコンポーネントに依存するアプリコンテナも併せて再起動することを推奨します。

アプリ再起動スクリプトをデータレイク内で実行しないでください

restart-server.sh · restart-batch.sh · restart-warehouse.sh はファイルが残っていますが、ホストの bin/ にあり、各アプリ自身のコンテナに対してのみ意味を持ちます。データレイクコンテナ内で呼び出すと、そのアプリの実行ファイルが存在しないため «モジュールがない» という結果になります。

restart-opcua-server.sh と restart-aasx-server.sh はもうありません。 OPC-UA および AAS はそれぞれ plantpulse-plugin-opcua · plantpulse-plugin-aasx という自身のコンテナで起動しているため、コンテナを直接再起動してください。

docker restart plantpulse-plugin-opcua
docker restart plantpulse-plugin-aasx

Platform アップデート

新バージョンがリリースされた際は、同じサーバーでインストールワンライナーを再実行します。新バージョンの運用スクリプト・compose・イメージが導入され、データはボリュームにそのまま残ります。

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

./update.sh は公式のアップグレード手順ではありません — イメージのみを変更し、新バージョンで追加されたサービスを認識しません。実施前の準備と確認方法はアップグレードにあります。

ログ管理

ログの閲覧 — `logs.sh`

cd /opt/kopens/plantpulse-platform-docker/bin

./logs.sh                             # 전체 컨테이너를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh plantpulse-server-web       # 그 컨테이너의 로그
./logs.sh cassandra                   # 데이터레이크 안 컴포넌트 로그 파일
./logs.sh --list                      # 볼 수 있는 대상 전체 목록
./logs.sh -n 500 cep                  # 500줄만
./logs.sh -f plantpulse-server-web    # 계속 따라가기 (Ctrl-C 로 종료)

デフォルトは「一度出力して終了」です

logs.sh は最後の N 行（デフォルト 200 行）を表示して終了します。継続的に追跡するには -f を付けてください。 --no-follow は互換性のために受け付けていますが、現在はそれがデフォルトであるため付ける必要はありません。

どのコンテナか不明な場合は引数なしで

問題が発生した際、それがどのコンテナに起因するかを事前に把握することは困難です。引数なしで実行すると、8 つのコンテナログが時系列に混在して表示されるため、単一のコンテナのみを監視して原因を見逃すことを防げます。

--list は compose からサービスリストを、データレイクコンテナからコンポーネントログディレクトリを直接読み込んで表示します。手動管理のリストではなく、その時点の実際のリストです。

コンテナ内部ログディレクトリ

データレイクコンテナ内のコンポーネント別ログパスです。 (./shell.sh で進入後確認)

モジュール	ログパス
Valkey	`plantpulse-storage/cache/valkey/logs/system.log`
PostgreSQL	`plantpulse-storage/db/postgres/logs/system.log`
Aster TSDB	`plantpulse-storage/db/cassandra/logs/system.log`
RustFS	`plantpulse-storage/object/rustfs/logs/system.log`
Gravitino	`plantpulse-analytics/gravitino/logs/system.log`
Hive	`plantpulse-analytics/hive/logs/system.log`
Spark	`plantpulse-analytics/spark/logs/system.log`
Kyuubi	`plantpulse-analytics/kyuubi/logs/system.log`
時系列エンジン	`plantpulse-timeseries/engine/logs/system.log`
Kafka	`plantpulse-messaging/kafka/logs/server.log`
MQTT	`plantpulse-messaging/mqtt/logs/hivemq.log`
Temporal	`plantpulse-workflow/temporal/logs/system.log`
Kestra	`plantpulse-workflow/kestra/logs/system.log`
CEP	`plantpulse-cep/logs/system.log`
Data Gateway	`plantpulse-data-gateway/logs/system.log`
管理コンソール API	`plantpulse-datalake-admin-api/logs/system.log`

パス基準は /opt/kopens/plantpulse-platform/ です。アプリ 6 つのログはそれぞれのコンテナ内にあるため、./logs.sh <컨테이너> で見る方が迅速です。

ログをホストへコピー

cd /opt/kopens/plantpulse-platform-docker/bin
./tools/copy-log-to-local.sh

障害診断

cd /opt/kopens/plantpulse-platform-docker/bin
./doctor.sh

診断 tarball(/tmp/pp-doctor-<호스트>-<타임스탬프>.tar.zst)を作成します。すべてのコンテナの状態・health probe 出力・ログと設定、ホスト環境を格納し、パスワードとキーはマスキングされます。システムを一切変更しません。

生成された tarball を KOPENS 技術支援チームに送付することで、迅速な分析が可能になります。

ワーカー管理 (クラスター環境)

マスターノード 1 つで運用し、スループット拡張が必要な場合にワーカーコンテナを追加します。ワーカーリストの正本は compose/workers.roster であり（一行に <id> <ip>）、オーバーレイ compose ファイルはここで生成されます。

cd /opt/kopens/plantpulse-platform-docker

# 추가 — roster 등록 → 오버레이 재생성 → 볼륨 → pull → up → 링 조인 확인
bin/worker-add.sh                  # 빈 id·주소 자동 선택
bin/worker-add.sh 3                # id 지정
bin/worker-add.sh 3 10.99.0.103    # id·주소 지정

# 진입
docker exec -ti plantpulse-worker-3 /bin/bash

# 제거 — 반드시 이 순서
bin/worker-decommission.sh 3       # 데이터 이관 + 링 이탈 확인 + 복제 슬롯 정리
bin/worker-remove.sh               # 그 다음에 컨테이너 제거

生存しているワーカーへの docker rm は削除ではなく «遺棄» です

Aster TSDB はそのノードのトークンレンジと host id を保持し続け（RF=3 であれば QUORUM がそのまま成立するため警告すら出ません）、マスターはそのワーカーの PostgreSQL 物理複製スロットを解放しないため、ディスクが一杯になるまで WAL を固定します。 必ず worker-decommission.sh を先に実行してください — worker-remove.sh はコンテナが動作している場合は拒否されます。

スクリプトを使用すれば RF は自動的に降下します

worker-decommission.sh が内部で pd node rf <남는 수> を先に呼び出します。手動で pd node remove を入力する場合のみ、順序を直接遵守する必要があります → pd node rf

:::

削除されたワーカースクリプト

worker-run.sh · worker-stop.sh · worker-update.sh · worker-bash.sh は 2026-08-31 に削除されました。手動管理のワーカーリストを前提としていたため、roster 方式への変更に伴い廃止されました。代替はそれぞれ worker-add.sh (pull 含む) · compose 動詞 · compose pull+up -d · docker exec です。

詳細はクラスターインストールページを参照してください。

インストール後初期接続

項目	値
ウェブコンソール URL	`https://[서버IP]` (80/443)
管理 UI URL	`https://[서버IP]` (ウェブコンソールと同一アドレス)
モニター UI URL	`https://[서버IP]:4950`
デフォルト管理者 ID	admin
デフォルトパスワード	admin123!

セキュリティ案内: 初回ログイン後、セキュリティのためにデフォルトパスワードを変更することを推奨します。 → 初期パスワード

ノード管理スクリプト (データレイクコンテナ内部)

Aster TSDB およびデータベース管理は plantpulse-datalake コンテナ内の pd CLI(/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd)が担当します。./shell.sh で進入した後に使用してください。

Aster TSDB 管理

スクリプト	説明	使用タイミング
`pd node status`	クラスター状態確認	定期点検、問題確認時
`pd node info`	ノード詳細情報	ノード設定確認時
`pd node compact`	手動コンパクション実行	ディスク空間確保時
`pd node compactionstats`	コンパクション進行状態確認	性能点検時
`pd node flush`	Memtable フラッシュ	メモリ整理時
`pd node drain`	ノード Drain (安全な終了準備)	ノード終了前
`pd node repair`	ノードデータ復旧/同期	データ不一致時
`pd node repair-table`	特定テーブル復旧	テーブル単位復旧
`pd node cleanup`	ノード整理 (不要データ削除)	ノード変更後
`pd node remove`	クラスターからノード除去	ノード解除時 — `pd node rf` で RF を先に下げた後に
`pd node rf [--check] [노드수]`	リングに合わせて全キースペースの複製係数を調整	ノード追加・除去時
`pd node add`	クラスターにノード追加	拡張時
`pd node upgrade`	ノードアップグレード	バージョンアップグレード時
`pd node tpstats`	スレッドプール統計	性能分析時
`pd node proxyhistograms`	プロキシヒストグラム	遅延分析時
`pd node table-histograms`	テーブルヒストグラム	テーブル性能分析
`pd node table-stats`	テーブル統計	データサイズ/件数確認
`pd node sstable-size`	SSTable サイズ確認	ディスク使用量確認
`pd node cache-clear`	キャッシュ初期化	キャッシュ問題時
`pd node topic`	Kafka トピック管理	メッセージング点検時
`pd node disk`	ディスク使用量確認	容量点検時
`pd node errors`	エラーログ確認	エラー診断時
`pd node train-zstd`	ZStandard 圧縮学習	圧縮最適化時
`pd node init-cms`	CMS 初期化	初期設定時

データベース接続

スクリプト	説明
`pd node psql`	PostgreSQL シェル接続 (メタデータ DB)
`pd node cql`	Aster TSDB CQL シェル接続 (時系列 DB)

よく使うコマンドサマリ

cd /opt/kopens/plantpulse-platform-docker/bin

./preflight.sh            # 설치 전 비파괴 사전 점검
./install.sh              # 최초 설치 (OS+Docker+방화벽+스택)
./up.sh                   # 기동 — 준비될 때까지 대기 (0 = 준비 완료)
./down.sh                 # 정지 (상태 보존)
./restart.sh              # graceful 재시작 (drain + 준비 대기)
./status.sh               # 서비스 / health / 볼륨 요약 (0=정상 / 2=비정상)
./logs.sh [서비스]        # 로그 보기 — 1회 출력. -f 로 따라가기 (인자 없으면 전체, 목록은 --list)
./shell.sh [서비스]       # 컨테이너 bash 진입
./ops-check.sh            # 운영 health + critical log 점검
./remove.sh               # 컨테이너 제거 (볼륨은 보존)
./backup.sh               # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh               # 장애 진단 tarball 생성
./passwd.sh --list        # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh    # 스택 전체 준비 판정

すべての動詞が --help をサポートしています。

概要​

環境変数設定​

よく調整される項目​

Platform 起動​

初回インストール後の起動​

停止したスタックの起動​

起動順序​

ブート検証​

正常起動の確認​

Platform 停止​

Platform 再起動​

サービス状態確認​

全体サマリ​

運用点検​

ホスト側リソース確認​

コンテナ内部接続​

コンポーネント単位の再起動​

アプリ 6 つ — コンテナ単位で再起動​

データレイク内コンポーネント — コンテナ内部スクリプト​

Platform アップデート​

ログ管理​

ログの閲覧 — logs.sh​

コンテナ内部ログディレクトリ​

ログをホストへコピー​

障害診断​

ワーカー管理 (クラスター環境)​

インストール後 初期接続​

ノード管理スクリプト (データレイクコンテナ内部)​

Aster TSDB 管理​

データベース接続​

よく使うコマンドサマリ​

概要