メインコンテンツまでスキップ

インストール

PlantPulse Studio を顧客のサーバ 1 台にインストールする手順です。 Dockerコンテナ 4 種(ウェブ・サーバ・ビルダーサイドカー・PostgreSQL)で構成され、インストールスクリプトが Docker インストールから起動まで自動的に処理します。

インターネットが利用できない閉域網の場合は、このドキュメント代わりにエアギャップインストールを参照してください。

1. 前提条件​

サーバ仕様​

項目最小推奨備考
CPU4 コア8 コア以上アプリセッションごとにビルドが実行されます
メモリ8 GB16 GB 以上下表を参照してください
ディスク50 GB 空き100 GB 以上コンテナイメージのみ約 6 GB
OSLinux (x86_64)RHEL 9 / Rocky 9 / Ubuntu 22.04 以上systemd + Docker が動作していればよいです

メモリ算定根拠 — スタックが固定で確保する上限値です。

コンテナメモリ上限
studio-server (オーケストレーター)2 GB
agent-server (ビルダーサイドカー)2 GB
studio-web (nginx)256 MB
postgres (バンドルモード)制限なし(実使用数百 MB)
アプリセッションコンテナ 1 個あたり2 GB

アプリセッションコンテナはユーザがプロジェクトを開くたびに 1 つ起動し、30 分間使用されないと自動回収されます。同時作業者数分だけ 2 GB を追加で見込んでください。

同時ユーザ 3～5 名が目標の場合

16 GB メモリ・8 コア・100 GB ディスクを基準に見込むと余裕があります。

ソフトウェア​

  • Docker Engine + Docker Compose v2 (v2.22 以上) インストールされていない場合、ワンラインインストールスクリプトが自動的にインストールします。
  • curl, tar (ほとんどのディストリビューションにデフォルト付属)

ポートとファイアウォール​

スタックは host ネットワークで動作します。つまりコンテナポートがホストにそのまま開かれるため、 アクセス制御はサーバファイアウォールのみで行われます。

ポート用途ファイアウォール
80Studio UI (nginx)開放
5171アプリリスナー — プレビュー・デプロイアプリ・QR アクセス開放(必須)
5170Studio APIウェブが内部プロキシ — 開放不要(診断用)
5432PostgreSQL(バンドルモード)127.0.0.1 のみバインド — 開放禁止
8000ビルダーサイドカー(agent-server)ループバック専用 — 絶対開放禁止
5172MCP ツールブリッジループバック専用 — 絶対開放禁止
5171 をブロックするとプレビューとデプロイアプリが開きません

プレビュー(/preview/…)とデプロイアプリ(/apps/…)はセキュリティ境界の都合上、Studio と異なるオリジン (デフォルト 5171 ポート)から提供されます。チャットで作成したアプリの JavaScript が Studio ログイントークンにアクセスできないようにするための仕組みです。5171 を開かないと画面が空白に見えます。

8000・5172 には認証がありません

両ポートは内部コンポーネント間通信専用で、認証手順がありません。外部に露出すると、すべてのユーザワークスペースを読み書きできるようになります。スタックはデフォルトではループバックのみにバインドしていますが、ファイアウォールでも絶対に開かないでください。

レジストリアクセス​

イメージは KOPENS レジストリ(docker.kopens.io)から取得します。インストール前に一度ログインしてください。 アカウントは KOPENS 運用チームが発行します。

docker login docker.kopens.io

2. データベース選択​

インストール前にどちらかを決めてください。後で変更することもできますがデータ移行が必要です。

=== "(A) バンドル PostgreSQL — デフォルト"

スタックが PostgreSQL コンテナを一緒に起動します。別途 DB サーバがない現場のデフォルト値です。

COMPOSE_PROFILES=bundled-pg
PG_DB=ppstudio
PG_USER=ppstudio
PG_PASSWORD=`<long-random-string>`

データは DATA_ROOT/postgres 以下に保存されます。

=== "(B) 外部・共用 PostgreSQL"

プラットフォーム用の PostgreSQL が既にある現場では、二重インフラを削減できます。 COMPOSE_PROFILES 行を削除して接続 URL のみ指定すれば、PostgreSQL コンテナが まったく起動しません。

# COMPOSE_PROFILES 行削除
DATABASE_URL=postgres://`<user>`:`<password>`@`<db-host>`:5432/`<db-name>`

空のデータベースのみ準備すればよいです — テーブルはサーバが初回起動時に自動作成します。

PG パスワードは初回に決めた値を保持してください

バンドルモードでデータが既に蓄積した後に PG_PASSWORD だけ変更すると、既存データディレクトリのアカウントと不一致となり、スタックが起動しません。パスワードを変更する場合は、PostgreSQL 内でアカウントパスワードを先に変更する必要があります。

3. インストール(ワンライン・推奨)​

サーバに root でアクセスし、1 行を実行します。スクリプトが Docker 確認・インストール → パッケージダウンロード → .env 生成 → スタック起動までを実行します。

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

インストール位置は /opt/kopens/plantpulse-studio-docker で、以降すべての運用コマンドはこのディレクトリから 実行します。

値を事前に決めて無人インストール​

環境変数は**bash の前に**つける必要があり、パイプを通して渡されます。

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh \
  | sudo PLATFORM_API_TARGET=https://192.168.0.41 \
         DATA_ROOT=/data1/pp-studio \
         ANTHROPIC_API_KEY=sk-ant-... \
         bash

値の入力を促す​

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo INTERACTIVE=1 bash

空の項目ごとにプロンプトが表示されます(データルート・PG パスワード・プラットフォームアドレス・管理者アカウントなど)。

再実行しても安全です

同じサーバでインストールスクリプトを再実行すると、コードのみが更新され .env とローカルバックアップ(dist/)は 保存されます。アップグレード目的でそのまま使用できます。

インストールスクリプトが 404 または古いバージョンを提供する場合

CDN キャッシュが残っている可能性があります。URL の後に ?v=$(date +%s) を付けて再度ダウンロードしてください。

4. インストール(手動)​

パッケージを既にダウンロード済みか、.env を直接作成したい場合です。

cd /opt/kopens/plantpulse-studio-docker
sudo cp .env.example /etc/kopens/plantpulse-studio.env
sudo vi /etc/kopens/plantpulse-studio.env   # 아래 표를 보고 값 채우기
sudo chmod 600 /etc/kopens/plantpulse-studio.env
bash bin/start.sh
設定の本体は /etc/kopens/plantpulse-studio.env 1 つです

環境変数ファイルはインストールディレクトリ内ではなく、 リポジトリツリー外の /etc/kopens/plantpulse-studio.env に配置します。権限は 0600 です。platform・ai・studio 3 つのプロダクトが同じ規約で /etc/kopens/plantpulse-<product>.env を使用します。

インストールディレクトリのルートの .env はレガシーパスです。compose も残りのスクリプトも 現在このファイルを読み込まないため、そこを編集してもスタックは変わりません。既存インストールの .env は bin/install.sh が新しいパスに移動します(新規作成ではありません — 新規作成すると DB は古いパスワードなのに env は新しいデフォルト値になり、次の再起動で失敗します)。

環境変数主要項目​

項目説明デフォルト
REGISTRYイメージレジストリ。空にすると pull なしでローカルイメージのみ使用(エアギャップ)docker.kopens.io/ps
TAGイメージタグ。特定バージョン固定時は 2026.08 のように指定latest
DATA_ROOTすべてのデータ(ワークスペース・ビルド・状態・DB)が保存されるパス/var/lib/pp-studio
PLATFORM_API_TARGET実データ・認証を委任する PlantPulse プラットフォームアドレスhttps://192.168.0.41
APPS_PORTアプリリスナーポート(プレビュー・デプロイアプリ)5171
PP_LANGウェブデフォルト言語 ko / enen
PP_TZタイムゾーン(IANA ID)。「今日・昨日・先週」解釈の基準Asia/Seoul
STUDIO_CORS_ORIGINS別ドメインから API を呼び出すときのみ指定。デフォルトはブロック空
COMPOSE_PROFILES / DATABASE_URLデータベース選択 — 上記第 2 節参照bundled-pg
ANTHROPIC_API_KEY などAI・プラットフォームキー — シークレット管理を参照空
アカウントとロールは環境変数では送信されません

STUDIO_LOCAL_USERS・STUDIO_ADMINS・STUDIO_VIEWERS は廃止されました(2026-08-18)。 サーバがアカウントを 1 つも持たない場合、ブートストラップ管理者を DB に埋め込み、その後はアプリの 環境設定 → ユーザ管理でアカウントを追加・削除し、ロール(管理者/ビルダー/ビューアー)を割り当てます。 以下の7. 最初のログインを参照。

韓国語の現場は PP_LANG=ko を直接追加してください

ワンラインインストールが生成する .env には PP_LANG・PP_TZ 行がないため、デフォルト値(en / Asia/Seoul)が 適用されます。韓国語で起動するには .env に PP_LANG=ko を追加して bash bin/restart.sh してください。

.env を変更した後は必ず bin/restart.sh してください

docker restart は .env を再度読み込みません。値が反映されないまま「なぜ変わらないのか」を 長時間探すはめになる代表的なトラップです。詳しくはシークレット管理に記載されています。

5. スタック構成確認​

インストール完了後、4 種類のコンテナが起動しているはずです。

コンテナ役割
pp-studio-webStudio UI(nginx :80) — 静的画面 + API プロキシ
pp-studio-serverオーケストレーター(:5170) — エージェント・セッション・デプロイ・アプリリスナー(:5171)
pp-studio-agent-serverビルダーサイドカー — アプリコードを作成するコーディングエンジン
pp-studio-postgresバンドル PostgreSQL (外部 DB を使用する場合は起動しません)

これに加えて、ユーザがプロジェクトを開くと、アプリセッションコンテナがプロジェクトごとに 1 つ起動します。 スタックコンテナではなく、サーバが必要に応じて作成し、アイドル 30 分後に回収されます。

6. 起動確認​

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh          # 컨테이너 상태 + 헬스 + 세션 컨테이너 수
curl -s localhost:5170/health

インストール直後には、総合点検スクリプトを 1 度実行することをお勧めします。ヘルス・ウェブ応答・実際の ログイン・セッションランタイムイメージ・コンテナ状態をすべてチェックし、1 つでも失敗すると エラーで終了します。

bash bin/smoke-install.sh
✓ health
✓ client-config → {"lang":"ko",...}
✓ web 200
✓ 로그인(부트스트랩 계정)
✓ 세션 런타임 이미지
✓ 컨테이너 running(...)
✅ 설치 스모크 통과
セッションランタイムイメージ

アプリセッションコンテナは plantpulse-studio-runtime イメージを使用します。bin/start.sh が自動的に ダウンロードしてタグ付けしますが、失敗すると ⚠️ 세션 런타임 이미지 없음 警告が表示され、プロジェクトを開くのが 失敗します。この場合、レジストリログイン状態を確認し bash bin/start.sh を再実行してください。

7. 最初のログイン​

ブラウザで http://<server-ip>/ にアクセスします。

アカウントが 1 つもない状態でサーバが初回起動すると、ブートストラップ管理者を DB に埋め込みます。

項目値
ユーザ IDadmin
パスワードadmin123!

起動ログにも記載されます — 부트스트랩 관리자 생성: admin — 로그인 후 비밀번호를 바꿀 것。

最初にこのパスワードを変更してください

すべてのインストールで同じ値です。ログイン直後に環境設定 → ユーザ管理で変更してください (パスワードリセット、6 文字以上)。環境変数ファイルを編集することでは変更されません — サーバは ログイン時に①DB → ②環境変数の順で確認し、DB で見つかるとそこで終了します。

ログイン後の作業:

  1. 環境設定 → ユーザ管理 — ブートストラップ管理者のパスワード変更、現場ユーザアカウント作成、 ロール(管理者/ビルダー/ビューアー)割り当て
  2. パスワード・API キー変更 — DB アカウントと AI キーを bin/passwd.sh で一度に ローテーション。コミッショニング時に 1 度だけ実施します
  3. 環境設定 → AI — AI プロバイダとキー接続状態確認
  4. 環境設定 → プラットフォーム — プラットフォームアドレス・キー接続確認(実データ照会に必要)

詳細な画面説明はスタートガイドと 環境設定(管理者)に記載されています。​

8. 日常運用コマンド​

すべてのコマンドはインストールディレクトリ(/opt/kopens/plantpulse-studio-docker)から実行します。

bash bin/start.sh            # 시작(레지스트리에서 최신 이미지 pull 포함)
bash bin/stop.sh             # 중지 — 데이터는 그대로 보존, 세션 컨테이너도 정리
bash bin/restart.sh          # 재기동(.env 변경 반영)
bash bin/status.sh           # 상태 요약
bash bin/logs.sh             # 서버 로그 팔로우(기본 studio-server)
bash bin/logs.sh studio-web  # 특정 서비스 로그

セッションコンテナだけを別途確認するには、

docker ps --filter label=plantpulse-studio=1

9. アップデート​

bin/start.sh はレジストリから イメージを再度取得して更新します。インストールスクリプトを再実行すると、 運用スクリプトも一緒に更新されます(.env・バックアップは保存)。

=== "イメージのみ更新"

cd /opt/kopens/plantpulse-studio-docker
bash bin/start.sh

=== "パッケージまで更新"

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

バージョン固定​

バージョン表記は YYYY.MM 形式です(例: 2026.08)。自動更新を望まない運用環境では、 .env にタグを固定してください。

TAG=2026.08
更新前にはバックアップを実施

bash bin/backup.sh を先に実行してください。手順はバックアップと復旧に記載されています。

イメージ署名検証(オプション)​

配布されたイメージが KOPENS によって署名されたものかを検証できます。cosign がインストールされている必要があります。

cd /opt/kopens/plantpulse-studio-docker
bash bin/verify-images.sh
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-server:2026.08
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-web:2026.08
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-runtime:2026.08

次のステップ​