インストール概要

PlantPulse AI は docker compose スタック一つで動きます。正本は compose/docker-compose.yml で、運用スクリプトもすべてこのファイルを経由してコンテナを扱います。

ほとんどはこの一行で終わります

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

詳しくはワンラインインストールを参照してください。このページは 何がどこに配置されるかと、インストールスクリプトが実際に行うことを説明します。

どこに配置されるか

/opt/kopens/
├── plantpulse-ai-docker/                  ← 설치 본체 (bin · compose)
├── plantpulse-ai-inference-server/        ← 형제 저장소
└── plantpulse-timeseries-insight-server/  ← 형제 저장소

兄弟リポジトリ二つが «必ず» 必要です

compose/docker-compose.yml は二つのリポジトリのファイルを相対パスで bind-mount します（例: ゲートウェイ設定 litellm-config.yaml）。無いとスタックが起動しません — START=1 であってもインストーラが起動を拒否し、足りないリポジトリ名を表示します。ワンラインインストールと閉域網バンドルは三つを一緒に取得して展開するため気にする必要はありませんが、手動で git clone する場合は三つを兄弟ディレクトリとして配置しなければなりません。

何	どこ
インストール本体	`/opt/kopens/plantpulse-ai-docker`
設定・資格情報の正本	`/etc/kopens/plantpulse-ai.env`（0600）
その元テンプレート	`<설치 본체>/compose/env.gb10.example`（AWS g7e は `env.g7e.example`）
ハードウェアプロファイル	`<설치 본체>/compose/profiles/gb10.env` · `g7e.env` — GPU 配分。ホスト env の `PP_HW_PROFILE` が選びます
Docker 保存ルート	`/data1/docker-data`（`DOCKER_DATA_DIR` で変更）

何が起動するか — コンテナ二十五

分類	コンテナ	すること
入口	`plantpulse-proxy`	nginx（非root）。ホストの 80・443 と管理コンソール HTTPS（5960）を受けて内部に渡す
画面	`plantpulse-copilot-web` · `plantpulse-admin-web`	コパイロット画面・管理コンソール（HTTP 5959）
推論	`plantpulse-llm` · `plantpulse-emb` · `plantpulse-rerank`	vLLM — 生成・埋め込み・再ランキング
ゲートウェイ	`plantpulse-litellm`（4000）	モデル呼び出しを一か所に集約する
文書	`plantpulse-rag-api` · `plantpulse-lightrag` · `plantpulse-docling-serve` · `plantpulse-document-understanding-api`	文書を読み・分割し・検索する
知識	`plantpulse-neo4j`（7474・7687）· `plantpulse-qdrant`	知識グラフ・ベクトルインデックス
デジタルスレッド	`plantpulse-digital-thread-api`（7140、ホストには開きません）· `plantpulse-digital-thread-neo4j`	工場グラフのミラーとコネクタレジストリ・その専用 Neo4j（ホストには開きません）
時系列	`plantpulse-timeseries-insight-api`（8970）· `plantpulse-timeseries-insight-server`（8980、ホストには開きません）	異常検知・予測
視覚	`plantpulse-vision-api`	画像理解
管理	`plantpulse-admin-api`	管理コンソールバックエンド
観測	`plantpulse-phoenix`（6006、ホストには開きません）· `plantpulse-dcgm`	トレース UI・GPU 指標
録取	`plantpulse-asr` · `plantpulse-asr-audio`	音声 → テキスト（vLLM Whisper）・そのオーディオライブラリをボリュームに移して終了する一回限りのサービス。映像・音声を有効化したインストール（`PI_MEDIA_ENABLED=true`）でのみ起動します → 映像・音声収集
レジストリ	`plantpulse-registry` · `plantpulse-registry-ui`	閉域網用の内部イメージストレージ — 基本起動では起動しません

基本で起動するのは録取二つとレジストリ二つを除いた二十一です。映像・音声を有効にすると録取二つが加わり二十三になります（plantpulse-asr-audio は仕事を終えて «Exited (0)» で残るのが正常です）。デジタルスレッド二つは 2026.10 に新しく追加されました。

8970 と 7115 は MCP クライアントが直接接続する箇所です（プラットフォーム CEP 異常検知、 Claude Desktop のようなもの）。残りはプロキシの背後にあります。

install.sh が行うこと

ワンラインインストールは bootstrap.sh がリポジトリを取得してこのスクリプトを実行するものです。 OS を判別（RHEL 系 / Debian 系）した後、ログに表示される番号順に処理します。

段階	すること	ホストグローバル
1	ロケール（`ko_KR.UTF-8`）・タイムゾーン — `PP_TZ` の値を一つに決めてホスト OS もそのタイムゾーンに合わせます（インストール時に与えた値 → 既に env にあった値 → ホストのタイムゾーン（UTC でなければ）→ `Asia/Seoul`）	✅
2	スワップ解除（`/etc/fstab` にも反映）	✅
3	Docker CE + buildx + compose v2 プラグインのインストール — 既にあればスキップ
3b	NVIDIA ドライバ + container toolkit のインストール、Docker に `nvidia` ランタイムを登録（`SKIP_GPU=1` ならスキップ）
4	`/etc/docker/daemon.json` とデータディレクトリ（下記）
5	OS チューニング — chrony・limits・sysctl・tmpfiles	✅
6	ファイアウォール開放 — compose が実際に公開するポートのみ開きます（SSH 22 は先に開けておきます）。そのポートのうちこのスタック以外のプロセスが既に占有しているものを警告として表示し、変更できるキーを知らせます	✅
7	社内レジストリのログイン確認（`SKIP_LOGIN=1` ならスキップ）
8	設定サイドカーの準備 — テンプレートを `/etc/kopens/plantpulse-ai.env` にコピーして値を埋める → `START=1` のときのみモデル受信・イメージ pull・起動

«ホストグローバル» の印が付いた段階は、この製品ではなくホスト全体の設定を変更します。 HOST_TUNING がこの四段階を扱います（下表）。

他のコンテナが既に動いているホストでは «出力のみ» です

HOST_TUNING を与えていないのにこの compose プロジェクト外のコンテナが Up の場合、デフォルトが plan になります — 変更内容だけを表示し、何も書き込みません。出力を見て適用してよければ HOST_TUNING=apply で再度実行してください。専用機（他のコンテナが無い）であればデフォルトは apply です。 sysctl はホストに既により高い値があれば下げません。

4段階 — 既存の Docker には手を加えません

このホストの Docker	すること
今回の実行で新規インストールした	デフォルト値（`overlay2`、`DOCKER_DATA_DIR`=`/data1/docker-data`）で `daemon.json` を書き込みます
元々あった	ストレージ（`data-root`・storage-driver）は稼働中デーモンの `docker info` を正本と見なし、新規に書き込みません。変更内容は出力のみで再起動しません

元々あった Docker の設定を変更し再起動まで許可するには ALLOW_DOCKER_RECONFIGURE=1 を与えます。別の DOCKER_DATA_DIR を使おうとするときもこれが必要です。

ストレージを変更すると既存コンテナ・イメージが «消えたように» 見えます

以前は既存の daemon.json にキーが無ければデフォルト値を埋め込んでおり、その結果別のストレージルートを使っていたホストのコンテナとイメージが見えなくなったことがありました。今はそのためデフォルトが «触らない» になっています。 ALLOW_DOCKER_RECONFIGURE=1 は、その結果を理解した上で与えるときのみ使用してください。

デフォルトは «準備まで» です

START=1 を与えないと設定ファイルを作成して止まります。値を確認してから自分で起動したい運用者のためのデフォルト値です。

よく使う環境変数

変数	意味
`START=1`	`.env` の準備だけで止まらず起動まで進む — モデル自動受信とインストール検証もこの時点で行います
`INTERACTIVE=1`	空の値を尋ねる（デフォルトは非対話式）
`ENV_TEMPLATE`	サイドカーの元テンプレート。デフォルトは `env.gb10.example`（GB10・arm64）、AWS g7e は `env.g7e.example`（amd64）。自動では選びません
`ENV_TEMPLATE_SKIP_ARCH_CHECK=1`	テンプレートとこのマシンのアーキテクチャが食い違うとインストーラが停止します。新しいハードウェアを試すなど意図した場合にのみこの検査を飛ばします
`HOST_TUNING`	`skip`・`plan`・`apply` — ホストグローバル設定（ロケール・タイムゾーン・スワップ・chrony・limits・sysctl・tmpfiles・ファイアウォール）とパッケージインストール（Docker CE・NVIDIA ドライバ/toolkit・jq）。`skip`・`plan` であればパッケージをインストールせず、nvidia ランタイム登録（Docker 再起動）も行いません — することだけを表示し、それ無しでは動けない段階で停止します。デフォルトは `apply`、他のコンテナが動いているホストなら `plan`
`DOCKER_DATA_DIR`	今回の実行で新規にインストールする Docker の保存ルート（デフォルト `/data1/docker-data`）。元々あった Docker は自分のルートをそのまま使います
`ALLOW_DOCKER_RECONFIGURE=1`	元々あった（稼働中の）Docker の `daemon.json` 変更・再起動を許可する
`SKIP_GPU=1`	3b段階（NVIDIA ドライバ・toolkit インストール）をスキップする — ドライバを運用チームが別途管理するホスト向け
`SKIP_WAIT=1`	`START=1` の後の «応答するまで待機» とインストール検証をスキップする
`WAIT_READY_MIN`	上記待機の上限（分）。デフォルト `15`
`SKIP_LOGIN=1`	社内レジストリのログインをスキップする — 閉域網用。イメージ pull も合わせてスキップ
`SKIP_PULL=1`	インターネットに繋がる機器で既に取得済みのイメージで起動する
`INSECURE_REGISTRY`	顧客社内レジストリ（HTTP）を `daemon.json` 許可リストに追加

SKIP_PULL=1 は «古いビルドで起動する» 可能性があります

イメージタグが YYYY.MM で、**同じ名前で更新されます。**ローカルにキャッシュされた同名タグが先月のビルドである可能性があります。バージョンを確実に合わせる必要があればこのオプションを使わないでください。

何を尋ね何を «作るか»

インストーラは人やプラットフォームだけが知る値を尋ね、スタック内だけで使う秘密は自分で作ります。

	値
尋ねます	TLS 証明書 SAN（`PP_PROXY_CERT_SAN`）・プラットフォーム資格情報を受け取るアドレスとキー（`PP_DATALAKE_ADMIN_URL`・`PP_DATALAKE_ADMIN_API_KEY`） — その後、残りのプレースホルダ（プラットフォーム API トークン・管理者パスワード・Neo4j パスワードなど）を一つずつ
作ります	ゲートウェイマスターキー・ソルト・推論サーバーキー・インバウンドキー・RAG キー・管理セッションシークレット・保存資格情報暗号化キー二つ（`PI_COPILOT_SECRET_KEY`・`PI_DT_SECRET_KEY`）

尋ねるのは INTERACTIVE=1 の場合です。尋ねる値はすべて同じ名前の環境変数でも渡せます — PP_DATALAKE_ADMIN_URL=… PP_DATALAKE_ADMIN_API_KEY=… PP_API_TOKEN=… PI_ADMIN_PASSWORD=… bash のように与えると、インストーラが まだプレースホルダのまま残っているキーのみその値で埋めます（2026.10 再リリース — 以前は TLS SAN とプラットフォーム資格情報の二値のみ受け取っていました）。それでも残っているものは対話式で埋めるか /etc/kopens/plantpulse-ai.env を直接修正します。作る値も プレースホルダのときのみ埋め、人が既に入れた値は上書きしません。env ファイルに既に書かれている TLS SAN も再インストール時にそのまま残します — 変更するには PP_PROXY_CERT_SAN=… を明示して実行してください。

プラットフォームアカウント・パスワードは尋ねません（2026.10）

プラットフォームホスト（PP_HOST）とプラットフォーム PG・Aster TSDB・Redis アカウント・パスワードは、もはや尋ねることも env に書くこともありません。プラットフォームホストは PP_DATALAKE_ADMIN_URL のホストから算出され、アカウント・パスワードはコンテナとホストスクリプトが **起動時にプラットフォームから受け取ります。**この実行に PP_PG_USER のような値を渡すと、env に書き込まないという警告だけが表示されます。信頼アンカー root.crt はインストーラが配置しないため、自分で用意してください → 下記「プラットフォーム資格情報を受け取る — 起動前に準備すること」

TLS SAN — 接続アドレスを証明書に入れます

プロキシの自己署名証明書に人が接続する際に使うアドレス・名前が含まれていないと、ブラウザがブロックします。インストーラはこのホストのアドレスをデフォルト値として採用しますが、NAT 外部のパブリック IP・ロードバランサー VIP・ドメイン名はこの箱からは見えません。対話式インストールでは必ず尋ね、非対話式ならホストアドレスだけを採用した上で警告します。外部名で接続する場合はカンマで複数渡してください。

curl -fsSL https://product.kopens.io/plantpulse-ai/install.sh \
  | sudo PP_PROXY_CERT_SAN=ai.example.com,203.0.113.10 bash

人に秘密を八つ手入力させません

書き取らせると短く重複した値が入力されます — 実際に二つのホストが文書に記載されていたサンプルキーをそのまま一緒に使っていたことがありました。今はインストーラが作成し、運用者はローテーションだけすればよくなっています。

インバウンドキーが空だと何も起動しません

インストーラが作成するインバウンドキー（PI_INBOUND_API_KEY）は RAG・時系列インサイト・文書理解・ビジョン・デジタルスレッドが共通して使う入口キーです。空の場合は起動前の判定（bin/lint-env.sh）がスタックを起動せず、各サービスも個別に起動を拒否します — キー無しで開いたまま起動する経路は、開発用スイッチ PI_INBOUND_AUTH_DISABLED=true をわざと与えたときのみです。手動で env を作成した場合は必ずこの行を埋めてください → 環境変数設定

START=1 のときに起こること — さらに三つあります

2026.09 から起動経路は値を «受け取り・埋め・確認します»。

段階	すること
プレースホルダ確認	🔴 `CHANGE_ME_` や `<PLACEHOLDER>` が残っていると停止します。*以前は警告のみで「インストール完了」として終わっていました
プラットフォーム資格情報事前確認	イメージを取得する前にプラットフォームから資格情報を一度受け取ってみます。キーが間違っているか `root.crt` が無い場合、`[FATAL] [platform-credentials] …` で何も起動せずに停止します。両値が空でも停止します
モデル自動受信	不足しているモデルを `model.kopens.ai` から受け取りSHA256 を検証した後展開します。以前は人が手作業で行う手順でした
応答待機	管理コンソール（`:5959/health`）と RAG ゲートウェイ（`:7115/ping`）が応答するまで最大 `WAIT_READY_MIN`（15）分待ちます。超過するとインストール失敗として終わります。コンソール HTTPS（`:5960`）が応答するかも表示しますが、失敗判定には含めません
インストール検証	スタックが «起動しているか» ではなく «動作しているか» を確認します（下記）

値が空のまま緑色のスタックの方がより悪いです

プレースホルダが残ったまま起動すると画面は正常でも機能だけ死にます。そのため START=1 であれば **起動を拒否します。**準備だけであれば START を与えなければよいです（閉域網インストールは値を後から入れる流れそのままです）。2026.10 からは後で bin/up.sh で起動するときも同じ検査を行います — プレースホルダが残っていると残っているキー名を表示し起動を拒否します。

「21/21 running」は「動作している」という意味ではありません

クリーンインストールでステータスがすべて running・HTTP 200 なのに三つが死んでいたことがあります — 三つともコンテナヘルスチェックは通過します。

誰もモデルを受け取らず、推論サーバーだけが再起動を繰り返す
ゲートウェイキーが空の値ですべてのチャットが 401
プラットフォームトークンがプレースホルダで MCP ツールが静かに 0 個

インストール検証（bin/verify-install.sh）がこの三つを見ます。各検査は OK・FAIL・**「測定不能」**で答え、測定不能なものは通過として数えません。

インストールが «正常» かを見る四段階

bin/status.sh — 21/21 running · HTTP=200（基本で起動する二十一）
bin/verify-install.sh — OK 4 · FAIL 0。一つでも FAIL ならインストールが失敗として終わります
AI 管理コンソール › MCP ゲートウェイ › サーバー — プラットフォーム・時系列インサイト・デジタルスレッド・工学計算などの内蔵サーバーが正常で、ツール数が 0 でないはずです。 0 ならプラットフォームトークンを確認してください → MCP ツールマップ
尋ねるで一度試してみてください — 1〜3 がすべて緑でもチャットだけ 401 だったことがあります

既知の落とし穴二つ

**最初に起動するホストでは起動を二回行う必要がある場合があります。**文書パーサが依存関係待機時間内に正常化しないとそこで止まります。再度起動すると 21/21 になります。
🔴 **docker compose up を直接実行するとデプロイしたイメージが元に戻ります。**デプロイはタグをその呼び出しにのみ紐付け、.env には残しません（意図した動作です）。起動するときは提供されたスクリプトを使ってください。

プラットフォーム資格情報を受け取る — 起動前に準備すること

2026.10 からプラットフォーム PG・Aster TSDB・Redis・RustFS のアカウント・パスワード・ポートはコンテナが起動するときにプラットフォームから受け取ります（コパイロット・時系列インサイト API・LightRAG・RAG API・デジタルスレッド・LiteLLM）。 compose はこの値を渡さないため、下記四つが揃っていないとそのコンテナがFATAL で停止します。

準備すること	どこで
`PP_DATALAKE_ADMIN_URL`	`https://<플랫폼 호스트>:4950` — このホストがそのまま `PP_HOST` です
`PP_DATALAKE_ADMIN_API_KEY`	プラットフォームホスト `/etc/kopens/plantpulse-platform.env` の同名行
プラットフォーム許可リスト	🔴 AI ホストの IP がプラットフォーム側の許可リストにあることで受け取れます
`/etc/kopens/ca/root.crt`	プラットフォーム信頼アンカー — プラットフォーム `GET /api/credentials/tls` 応答の `root_pem`。同じ応答の `root_fingerprint_sha256` と指紋を照合した上で配置します
`/etc/kopens/ca/CA.crt`	`root.crt` と同じ内容。アプリがこの名前で読みます

前の二値は /etc/kopens/plantpulse-ai.env に入ります — テンプレートにプレースホルダとして入っており、対話式インストールが尋ねるか環境変数で渡します。compose が /etc/kopens/ca ディレクトリを丸ごとコンテナにマウントします。

二値は必須です。空であれば compose が起動を拒否し、片方だけあればコンテナが拒否します。
ホストスクリプト（起動前の DB プロビジョニングなど）も同じ二値と root.crt でプラットフォームから受け取ります。ホスト env にはプラットフォームアカウント・パスワードはありません。
サーバー証明書は root.crt のみで検証します — ファイルが無ければ FATAL で検証を無効にする方法はありません。
受け取りに成功したかはログで確認します — キー名と個数だけが表示されます。

docker logs plantpulse-copilot-web 2>&1 | grep credentials:

→ 環境変数設定 · トラブルシューティング

映像・音声を使うには — インストール後に一行

映像・音声収集とチャットの音声で尋ねるはデフォルトで無効になっています。使用するにはホスト env に PI_MEDIA_ENABLED=true の一行を入れ、bin/fetch-models.sh で録取モデル（Aura-ASR-Turbo、約 1.5 GB）を受け取った後 bin/restart.sh してください。手順と確認は映像・音声収集にあります。

インストール後に

順序	すること	コマンド・文書
1	デフォルトパスワードを変更する	初期パスワード変更
2	スタックが生きているか確認する	`bin/status.sh`・`bin/health.sh`
3	どこが詰まっているか特定する	`bin/doctor.sh`

よく使う運用コマンドは bin/ にあります — up.sh・down.sh・restart.sh・ logs.sh・backup.sh・update.sh・passwd.sh。詳しくはサービス運用を参照してください。

どこに配置されるか​

何が起動するか — コンテナ二十五​

install.sh が行うこと​

4段階 — 既存の Docker には手を加えません​

よく使う環境変数​

何を尋ね何を «作るか»​

START=1 のときに起こること — さらに三つあります​

インストールが «正常» かを見る四段階​

プラットフォーム資格情報を受け取る — 起動前に準備すること​

映像・音声を使うには — インストール後に一行​

インストール後に​

関連文書​