Docker Compose で動かす
個別に起動する代わりに、一式まとめて Docker Compose でビルドして起動することもできます(compose.yml)。
echo SYSTEM_DEFAULT_LLM_API_KEY=your_google_api_key_here > .env
docker compose up --build
http://localhost:3000 を開きます。データベースの中身は pgdata ボリュームに残るので、再起動しても消えません。
.env の APP_PORT を設定すると、アプリを別のホスト側ポートで公開します。アプリのベース URL も自動でそれに合わせられます。ホスト名など別のアドレスでアプリを開かせたいときは、代わりに .env の APP_BASE_URL にそのアドレス(例 http://a2flow.internal:3000)を設定します。アプリが公開されるのは引き続き APP_PORT なので、アドレスにポートを書くときは APP_PORT も同じ値にしてください。
起動するコンテナ
| コンテナ | 役割 |
|---|---|
| db | PostgreSQL 17。A2Flow が記録するものはすべてここに入ります |
| backend | エージェントと API |
| worker | バックエンドが積んだ通知メールを送ります |
| mcp-proxy | 登録した MCP サーバーを実行します。分けている理由は登録したサーバーが動く場所を参照してください |
| ingress | ブラウザが話す入口。画面のリクエストはフロントエンドへ、API のリクエストはバックエンドへ直接送ります |
| frontend | 実際に操作する画面 |
| caddy | compose.https.yml を使ったときだけ起動します。HTTPS で公開するを参照してください |
| openbao | --profile openbao を付けたときだけ起動します。OpenBao で Vault 型シークレットを試すを参照してください |
| keycloak | --profile keycloak を付けたときだけ起動します。Keycloak でシングルサインオンを試すを参照してください |
外から到達できるのは ingress(compose.https.yml を使うときは代わりに Caddy、プロファイル指定時は OpenBao の UI と Keycloak も)だけで、残りは Docker の内部ネットワークでやり取りします。
初回の起動は 2 回目以降より時間がかかります。イメージのビルド、データベースのスキーマ作成に加えて、MCP プロキシがバックエンドから必要な証明書を受け取るまで待ってから受付を始めるためです。
HTTPS で公開する
compose.https.yml を追加すると、ingress の前に Caddy が置かれます。Caddy がポート 80 と 443 で唯一の入口になり、APP_BASE_URL のアドレスの証明書を取得して、平文の HTTP を HTTPS にリダイレクトします。アドレスが https:// なら、サインインの Cookie も Secure になり、シングルサインオンの リダイレクト URI もこのアドレスから作られます。
echo APP_BASE_URL=https://a2flow.example.com >> .env
docker compose -f compose.yml -f compose.https.yml up --build
設定したアドレスを開きます。アドレスにポートは書けません。公開されるのは 80 と 443 だけで、ポート付きのアドレスでは Caddy が起動しません。その後の動きはホスト名によって変わります。
APP_BASE_URL | 証明書 | 始める前に |
|---|---|---|
公開されたホスト名(例 https://a2flow.example.com) | Let's Encrypt から取得し、自動で更新します | そのホスト名の DNS をこのホストに向け、ポート 80 と 443 にインターネットから到達できるようにします |
未設定(https://localhost) | Caddy が自分で作る認証局が発行します | 不要です。ただし、その認証局を信頼するまでブラウザが証明書の警告を出します(下記) |
ブラウザに https://localhost を信頼させるには、認証局のルート証明書を取り出して、OS かブラウザの信頼されたルート証明書に追加します。
docker compose -f compose.yml -f compose.https.yml cp caddy:/data/caddy/pki/authorities/local/root.crt .
証明書とローカルの認証局は caddy-data ボリュームに保存されます。このボリュームは消さないでください。消すと証明書が発行し直され、信頼済みのルート証明書とも合わなくなります。
OpenBao で Vault 型シークレットを試す
OpenBao はオープンソースの Vault フォークで、A2Flow からは HashiCorp Vault とまったく同じようにつなげます。この構成では A2Flow の隣で OpenBao を起動できるので、自前の Vault がなくても Vault 型シークレットを試せます。
docker compose --profile openbao up --build
OpenBao のデータは A2Flow と同じ PostgreSQL に保存されるので、再起動しても消えません。起動のたびに自動でアンシールもされます。アンシールに使う鍵は openbao-unseal ボリュームにあり、鍵がないとデータを読めないので、pgdata と一緒にバックアップしてください。この構成は連携を試すためのもので、本番向けではありません。
1. OpenBao を初期化する(初回のみ)
docker compose exec openbao bao operator init -recovery-shares=1 -recovery-threshold=1
表示される Initial Root Token を控えておきます。表示されるのはこの一度だけです。
2. A2Flow 用の AppRole を作る
AppRole のロールは UI からは作れないので、ここはコマンドラインで行います。<root-token> は手順 1 のトークンに置き換えてください。
docker compose exec -e BAO_TOKEN=<root-token> openbao sh -c '
bao secrets enable -path=secret kv-v2
bao auth enable approle
printf "path \"secret/data/a2flow/*\" { capabilities = [\"read\"] }" | bao policy write a2flow -
bao write auth/approle/role/a2flow token_policies=a2flow token_ttl=1h
bao read -field=role_id auth/approle/role/a2flow/role-id; echo
bao write -f -field=secret_id auth/approle/role/a2flow/secret-id; echo'
最後の 2 行で role id と secret id が表示されます。このポリシーで A2Flow が読めるのは a2flow/ 以下のパスだけです。
3. OpenBao の UI でシークレットを作る
- http://localhost:8200/ui を開き、Token 方式でルートトークンを使ってサインインします。ルートトークンでのサインインはページを再読み込みすると消えるので、URL を直接入力せず画面上のリンクをクリックして移動してください。
- secret/ エンジンを開き、Create secret を選びます。
- パスに
a2flow/demoを入れ、エントリusernameとpasswordを追加して保存します。
4. A2Flow からつなぐ
- A2Flow に
rootでログインし、システム設定のグローバル Vault のアドレスにhttp://openbao:8200を設定して保存します。 - テナントを開いて Default を選び、グローバル Vault へのログインにチェックを入れます。Vault の認証方式に AppRole を選び、手順 2 の role id と secret id を入力して保存します。
adminでログインし、シークレットで種類が HashiCorp Vault、Vault のマウントがsecret、Vault のパスがa2flow/demoのシークレットを作ります。
あとはほかのシークレットと同じように参照できます。たとえば MCP サーバーの環境変数に ${secret:<名前>/password} と書きます。シークレットを選ぶ画面では、そのキー username と password が一覧に出ます。これはその場で OpenBao から読んだものなので、表示されれば接続できています。
OpenBao の UI をホスト側の 8200 以外のポートで公開したい場合は、.env に OPENBAO_PORT を設定します。A2Flow 自身は常に内部ネットワーク上の http://openbao:8200 でアクセスします。
Keycloak でシングルサインオンを試す
Keycloak はオープンソースの IdP です。この構成では A2Flow 向けに設定済みの Keycloak を A2Flow の隣で起動できるので、自前の IdP がなくてもシングルサインオンを試せます。
docker compose --profile keycloak up --build
Keycloak は http://keycloak.localhost:8180 で公開され、管理コンソールには admin / admin でログインできます(パスワードは .env の KEYCLOAK_ADMIN_PASSWORD で変えられます)。Chrome、Edge、Firefox は keycloak.localhost を自動で見つけます。それ以外のブラウザでは、先に hosts ファイルへ 127.0.0.1 keycloak.localhost の行を追加してください。Keycloak はコンテナを作り直すと何も残さず、下の設定から始め直します。管理コンソールで加えた変更は失われます。
起動時点で、次の設定が済んでいます。
| 項目 | 値 |
|---|---|
| レルム | a2flow |
| 発行者 URL | http://keycloak.localhost:8180/realms/a2flow |
| クライアント ID | a2flow |
| クライアントシークレット | a2flow-dev-secret |
| リダイレクト URI | http://localhost:3000(または APP_BASE_URL)と https://localhost。それぞれに A2Flow のコールバックのパスが続きます |
| グループクレーム | groups |
| ユーザー | alice はグループ a2flow-admins、bob はグループ a2flow-users に所属します。どちらもパスワードは password です |
1. A2Flow からつなぐ
- A2Flow に
adminでログインし、管理サイドバーの管理者設定を開きます。 - シングルサインオンセクションで、上の表の値を発行者 URL、クライアント ID、クライアントシークレットに入力し、シングルサインオンを有効にするにチェックを入れて保存します。
- ユーザーグループを開き、付けたいロールを持つグループを開くか新しく作って、IdP グループに
a2flow-adminsを入力して保存します。
2. ログインする
- ログアウトします。ログイン画面のテナントに
defaultを入力し、SSO でログインを押します。 - Keycloak のログイン画面で
alice/passwordでログインします。手順 1 のグループのメンバーとして、Alice で A2Flow にログインした状態で戻ってきます。 bobも試してみてください。所属グループa2flow-usersはどのユーザーグループにも割り当てられていないので、ログインは拒否されます。どれかのユーザーグループに割り当てれば通るようになります。
Keycloak は SAML にも対応していますが、A2Flow のログインは OpenID Connect だけを使います。