セットアップ

制御プレーン1ホスト + ワーカー1ホスト以上、という構成を想定しています。小規模であれば同一ホストで両方動かしても構いません。

必要要件

インストール (制御プレーン)

git clone https://github.com/paps-jp/pipeline
cd pipeline

# venv作成
python3.12 -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate

# パッケージインストール (editable)
pip install -e .

これで pipeline コマンドが venv の中に入ります。

初回起動

まずは単一プロセス mode が最短です。SQLite DB は初回起動時に自動作成されます。

pipeline run --dev
# → http://localhost:8000 (SQLite: ./pipeline.db、ワンタイム管理者PWが表示されます)

本番寄りに DB とポートを明示するなら:

pipeline run \
  --host 0.0.0.0 \
  --port 8000 \
  --db-url sqlite:///./pipeline.db \
  --log-level info

ブラウザで http://localhost:8000 を開き、ダッシュボードが表示されれば OK です。

Web UI ビルド

repo にビルド済バンドルは含まれないため、初回はビルドが必要です。

cd web
npm install
npm run build
# → FastAPI が配信する静的ファイルが出力される

その後 pipeline run … を再起動すると新 UI を配信します。開発時 (ホットリロード) は npm run dev を使います。localhost:5173 が立ち上がり、/api は制御プレーンへ proxy されます。

最初のワークロード

repo に examples/plugins/echo_sample/ が同梱されています。これで動作確認できます。

1. Web UI → ワークロード → 新規作成
2. 基本情報: slug echo-test / 表示名 Echoテスト
3. 実行モード: python_module を選択
4. プラグイン: echo-sample / モジュール: main
5. 設定: prefix [echo] / sleep_secs 0 / fail_pk_substr 空文字
6. 作成 すると一覧に echo-test が追加されます。
7. その行の 📨 投入 で pk に hello を入れて投入します。
8. 同じ行の 履歴 で、run が緑色 (success) で表示されます。

1件実行できれば制御プレーンは正常です。次はワーカーを別ホストに追加します。

ワーカーをホストに追加

方法1: 手動

ワーカーを動かすホストで同じ手順で venv + pip install を行い、起動します。worker は pull 型なので、起動するだけで自動 join します。

pipeline worker \
  --control-url http://<control-host>:8000 \
  --worker-id worker-host-a \
  --log-level info

制御プレーンの Web UI → ワーカー でこのホストが active と表示されます。特定 workload をそのホストに限定したいときは、workload の host_affinity にホスト名を入れます (設定リファレンス)。

方法2: Deploy タブから配信

1. Web UI → Hosts で SSH 接続先を登録し、公開鍵をホストの authorized_keys に追記します。
2. Web UI → Deploy で「配信パス」(何をどこへ + setup/service コマンド) を登録します。
3. Deploy now で一括 rsync + restart。詳細は Web UI ガイドの Deploy を参照。

systemd 常駐化

制御プレーン

# /etc/systemd/system/pipeline-control.service
[Unit]
Description=Pipeline control plane
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/opt/pipeline
ExecStart=/opt/pipeline/.venv/bin/pipeline run \
    --host 0.0.0.0 --port 8000 \
    --db-url sqlite:////opt/pipeline/data/pipeline.db \
    --log-level info
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

ワーカー

# /etc/systemd/system/pipeline-worker.service
[Unit]
Description=Pipeline worker
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/opt/pipeline
ExecStart=/opt/pipeline/.venv/bin/pipeline worker \
    --control-url http://<control-host>:8000 \
    --worker-id %H \
    --log-level info
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now pipeline-control     # 制御プレーン側
sudo systemctl enable --now pipeline-worker      # 各ワーカー側

動作確認

curl で API を叩いて状態を確認できます。

curl http://localhost:8000/api/v1/status
# → {"version":"...","mode":"control","db_url":"sqlite:///./pipeline.db","now":"..."}

curl http://localhost:8000/api/v1/workers
# → {"workers":[{"id":"worker-host-a","host":"...","state":"active",...}],"total":1}

curl http://localhost:8000/api/v1/dashboard/overview
# → {"running":[...],"recent_failures":[...],"queue_depths":[...]}

続いて詳しい使い方は Web UI ガイドや プラグインSDK をご覧ください。