スタートガイド

概要

ワンラインインストールまたは Docker インストールで PlantPulse Platform をインストール済みなら、すべての運用スクリプトは /opt/kopens/plantpulse-platform-docker/bin/ ディレクトリにあります。このページでは、Docker Compose スタックで動作するプラットフォームの起動と運用方法を説明します。

プラットフォームは 9 つのコンテナで構成されます。証明書ワンショット 1 つ、データレイク 1 つ、アプリ 6 つ、プロキシ 1 つです。構成全体は 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 は引き続き動作します(新しい名前を 1 行説明した後、同じ処理を行います)。

環境変数の設定

プラットフォーム起動前に、環境変数を確認してください。リソース値はインストール時にホストを参照して自動計算されるため、ほとんどのサーバーでは調整が必要な場合がほぼありません。

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

よく調整される項目

変数	説明	デフォルト値
`PP_LANG`	プラットフォームロケール (`ko` / `en`)	`en`
`PP_TZ`	プラットフォームタイムゾーン	`Asia/Seoul`
`DOCKER_PP_CPUS`	コンテナに割り当てる vCPU 数	`nproc` の結果
`DOCKER_PP_MEMORY`	メモリ上限	ホスト RAM の 90%
`DOCKER_DATALAKE_MEMORY`	データレイクメモリ上限	`80G` (ホストが小さい場合は RAM の 90%)
`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 を使用してください。

プラットフォームの起動

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

インストール (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        (완료까지 — 원샷)
      │
plantpulse-datalake     (healthy 까지)
      │
plantpulse-server-web   (healthy 까지) ──── plantpulse-proxy
      │
plantpulse-batch-web    (healthy 까지)
      │
      ├── plantpulse-warehouse
      ├── plantpulse-plugin-opcua-server
      ├── plantpulse-plugin-aasx-server
      └── plantpulse-ha        (이 넷은 서로 순서가 없습니다)

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

順序	カテゴリ	コンポーネント
1	ストレージ	Valkey(Redis)、PostgreSQL、Cassandra、MinIO
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 分かかります。Cassandra スキーママイグレーションと安定化が最も時間がかかります。

実測値 (2026-08-31、32 vCPU / 128GiB): データレイク 217 秒、Web サーバー 316 秒。既存データがある再起動は大幅に高速です。

ブート検証

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

stack-verify-boot.sh は1 つのコンテナではなくスタック全体を判定します。ワンショットが正常に終了したか、データレイクとアプリが running・healthy か、プロキシが 443 をサービスしているか、すべてを確認します。ノードティア (PP_TIER — FULL / DATALAKE / APP) を認識して、該当ティアに存在するコンポーネントのみ検証します。

up.sh と restart.sh はこのスクリプトが完了するまでポーリングし、それが両コマンドの終了コード 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 で8 つが (healthy) で、plantpulse-certs が Exited (0) なら正常です。ワンショットの Exited (0) は成功状態であり、障害ではありません。

プラットフォームの停止

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

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

注意: docker kill またはホストの強制シャットダウンはデータ整合性を破損する可能性があります。必ず ./down.sh を使用してください。

プラットフォームの再起動

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

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

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

サービス状態の確認

全体サマリー

./status.sh

サービスリスト、コンテナ状態、ヘルスチェック結果、ボリューム情報を一度に表示します。終了コードが契約 です。0 が正常、2 が異常なので、監視の自動化にそのまま使用できます。

運用点検

./ops-check.sh

コンテナヘルス、ヘルス 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`	Web コンソール
`plantpulse-batch-web`	バッチ処理
`plantpulse-warehouse`	データウェアハウス
`plantpulse-plugin-opcua-server`	OPC-UA プラグイン
`plantpulse-plugin-aasx-server`	AASX プラグイン
`plantpulse-ha`	冗長化復旧デーモン

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

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

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

ストレージ・分析・メッセージングなどのインフラコンポーネントは plantpulse-datalake コンテナ内で一緒に実行されるため、コンテナ内に入って個別スクリプトを使用します。

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

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

スクリプト	対象
`pd restart storage`	Cassandra、PostgreSQL、Valkey、MinIO
`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 sql`	SQL クエリツール
`restart-monitor.sh`	システムモニタリング

注: インフラコンポーネントを再起動した場合、そのコンポーネントに依存するアプリコンテナも一緒に再起動することをお勧めします。

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

restart-server.sh · restart-batch.sh · restart-warehouse.sh · restart-opcua-server.sh · restart-aasx-server.sh はスクリプトファイル自体は存在していますが、各アプリの自身のコンテナ内でのみ 意味があります。データレイクコンテナにはそのアプリの実行ファイルがないため、「モジュールが見つからない」エラーで終了します。アプリは上記のコンテナ単位再起動を使用してください。

プラットフォームの更新

新しいイメージがリリースされたら、以下のコマンドで更新します。

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

自動実行順序:

新しいイメージを docker pull
既存コンテナの graceful シャットダウン
新しいイメージで新しいコンテナを再作成
ヘルスチェック検証 — 失敗時は前のイメージに自動 rollback

ターゲットタグは PP_IMAGE_TAG (デフォルト latest) が決定します。データはボリュームに別途保存されるため、更新中も安全に保持されます。

ログ管理

ログの表示 — `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 つのコンテナのログが時間順に混在して表示されるため、1 つのコンテナだけを見ていて実際の原因を見落とすことがありません。

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

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

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

モジュール	ログパス
Valkey	`plantpulse-storage/cache/valkey/logs/system.log`
PostgreSQL	`plantpulse-storage/db/postgres/logs/system.log`
Cassandra	`plantpulse-storage/db/cassandra/logs/system.log`
MinIO	`plantpulse-storage/object/minio/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`
SQL	`plantpulse-sql/logs/system.log`
Monitor	`plantpulse-monitor/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) を作成します。すべてのコンテナ の状態・ヘルスプローブ出力・ログと設定、ホスト環境が含まれ、パスワードとキーはマスキングされます。システムはまったく変更されません。

生成された tarball を KOPENS テクニカルサポートチームに提供いただければ、迅速な分析が可能です。

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

1 つのマスターノードで運用していたが、処理容量の拡張が必要な場合は、ワーカーコンテナを追加します。ワーカーリストの正本は compose/workers.roster です (1 行に <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 は削除ではなく「放置」です

Cassandra はそのノードのトークンレンジとホスト ID を引き続き保持し (RF=3 なら QUORUM がそのまま成立してアラートが出ません)、マスターはそのワーカーの PostgreSQL 物理レプリケーションスロットを手放さないため、ディスクが満杯になるまで WAL を固定します。 必ず worker-decommission.sh を最初に実行してください。worker-remove.sh はコンテナが実行中なら拒否します。

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

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 です。

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

インストール後の初回アクセス

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

セキュリティに関する注: 初回ログイン後は、セキュリティ上の理由からデフォルトパスワードを変更することをお勧めします。→ 初期パスワード

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

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

Cassandra 管理

スクリプト	説明	使用時期
`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 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`	Cassandra CQL シェルアクセス (時系列 DB)

設定スクリプト

スクリプト	説明
`configure.sh`	データレイク設定生成 (env に基づいて各サービスの設定を自動生成)
`prepared.sh`	起動前の環境検証と準備 (必須ディレクトリ、パーミッションなどを確認)

env-reset.sh をコンテナ内で実行しないでください

env-reset.sh はすべての PP_* を unset した後、env.sh を再度読み込む開発専用ツール です。データレイクコンテナ内で実行すると、compose が注入した値まで消去され、イメージ内蔵のデフォルト値に戻ります。

バイナリインストール環境

現在のリリースはバイナリ(ネイティブ)インストールをサポートしていません

現行の出荷版は上記の Docker Compose スタックのみです。バイナリインストールで構築された既存システムの運用コマンドはバイナリインストールページに保持されているので、そちらを参照してください。新規構築には使用しないでください。

よく使用するコマンドサマリー

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 점검
./update.sh               # 이미지 갱신 (pull + recreate + rollback)
./remove.sh               # 컨테이너 제거 (볼륨은 보존)
./backup.sh               # 볼륨 백업 (기본 pp-data · pp-security)
./doctor.sh               # 장애 진단 tarball 생성
./passwd.sh --list        # 바꿀 수 있는 비밀번호 목록
./stack-verify-boot.sh    # 스택 전체 준비 판정

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

概要​

環境変数の設定​

よく調整される項目​

プラットフォームの起動​

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

停止中のスタックの起動​

起動順序​

ブート検証​

正常起動の確認​

プラットフォームの停止​

プラットフォームの再起動​

サービス状態の確認​

全体サマリー​

運用点検​

ホスト側リソース確認​

コンテナ内部へのアクセス​

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

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

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

プラットフォームの更新​

ログ管理​

ログの表示 — logs.sh​

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

ホストへのログコピー​

トラブルシューティング​

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

インストール後の初回アクセス​

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

Cassandra 管理​

データベース接続​

設定スクリプト​

バイナリインストール環境​

よく使用するコマンドサマリー​

概要