メインコンテンツへスキップ

bex で Beancount.io をワンクリックでセルフホスト

Beancount.io を自分の bex ワークスペースにワンクリックでデプロイし、bea、MCP クライアント、Git、モバイルアプリを接続し、アカウントを追加して、バックアップします。

ワンクリックで、ウェブダッシュボード、API と MCP サーバー、台帳サービス、そして Git に裏打ちされた台帳を含む Beancount.io スタック全体を、自分が所有する bex ワークスペースにデプロイできます。このガイドでは、ボタンを押すところから実際に動く台帳までを解説します。さらに、ツールの接続、アカウントの追加、更新、バックアップ、スタックの削除についても取り上げます。

このスタックは MIT ライセンスで、プランの制限は一切なく、ホスティング費用は月額約 $33 で、請求はあなたのワークスペースに発生します。発表については、ワンクリックで自分だけのBeancount.ioを運用をお読みください。

スタックをデプロイする​

Deploy to bex.co

  1. 起動します。 Deploy to bex.co を押し、スタックを所有するワークスペースを選択し、プランを確認して適用します。プレビューを承認するまで何も作成されず、入力する項目もありません。すべてのシークレットはワークスペース内で生成されます。
  2. 最初のビルドを待ちます。 私たちの実行では 27〜30 分かかり、bex のビルドキューが混み合っているときはさらに長くかかりました。ロールアウトが失敗と表示されたサービスは再試行されません。そのサービスを bex ダッシュボードから再度デプロイしてください。
  3. インスタンスを確保します。 beancount-dashboard サービスの URL を開き、すぐにサインアップします。メール認証のステップはなく、最初のアカウントが作成されるとサインアップは閉じられます。
  4. 台帳を作成します。 スターターテンプレートから始めるか、サンプル台帳を読み込んで見て回ります。
警告

最初のアカウントが存在するまでは、ダッシュボードのアドレスを知った誰でもアカウントを作成できます。もし誰かがあなたより先にサインアップした場合は、スタックの管理者トークンでそのアカウントを削除してサインアップを再び開いてください。

新しいセルフホストデプロイでのサインアップ。フォームの横には、このコピーはその所有者によって運営されており、帳簿は Git 上のプレーンテキストであると書かれています。

セルフホストスタック上のすべてのアカウントは、最上位のティアを利用できます。台帳、ディレクティブ、コラボレーター、AI の利用量はすべて無制限です。

何が動作し、いくらかかるか​

Blueprint はワークスペース内に 6 つのリソースを作成します(価格は 2026-11-18 時点の bex のプランプレビューによるものです)。

bex リソース役割月額コスト (USD)
beancount-dashboardウェブアプリ、およびあなたが使用する唯一の公開アドレス4.90
beancount-apiGraphQL、REST、MCP サーバー、Git プロキシ4.90
beancount-ledger帳簿を検証・クエリする(プライベート、公開アドレスなし)4.90
beancount-gitea各台帳を 10 GB ディスク上の Git リポジトリとして保存する(プライベート)6.65
beancount-backend-dbアカウント、トークン、設定用の Postgres4.41
beancount-cacheサインインセッションとキャッシュ用の Key Value7.21
合計32.97

接続したモデルプロバイダー、メールサービス、S3 バケットは別途請求されます。

オプション機能を有効にする​

スタックは統合機能なしで起動します。統合が必要な機能は、どの設定が欠けているかを示します。追加するには、bex で beancount-api サービスを開き、その Environment タブで変数を追加し、サービスを再度デプロイします。そこで追加した変数は、後で Blueprint を同期しても保持されます。

変数有効になる機能
ANTHROPIC_API_KEY または OPENAI_API_KEYレシートのスキャン、分類、アシスタント。bea ask には OPENAI_API_KEY が必要です。
TEMP_ASSETS_AWS_S3_* と PERM_ASSETS_AWS_S3_* (BUCKET、ACCESS_KEY_ID、SECRET_ACCESS_KEY)レシートと添付ファイルのアップロード
SEND_GRID_API_KEYパスワードリセットリンクなどのメール
OIDC_ISSUER、OIDC_CLIENT_ID、OIDC_CLIENT_SECRET独自のアイデンティティプロバイダー経由のサインイン、およびより多くのアカウント(アカウントを追加するを参照)

ツールを接続する​

Git を除くすべての場面でダッシュボードのアドレスを使用します。Git は API のアドレスを使用します。

bea CLI​

bea を uv tool install beancount-io または brew install bex-co/tap/bea でインストールまたは更新し、ダッシュボードをポイントします。

export BEA_API_URL=https://<your dashboard address>
export BEA_DASHBOARD_URL=https://<your dashboard address>
bea cloud login            # signs in through your browser
bea cloud ledger list

どちらの変数もダッシュボードのアドレスを取ります。ダッシュボードが API トラフィックを転送するからです。その他の bea cloud コマンドはすべて Beancount CLI リファレンスに一覧されています。

MCP 経由のコーディングエージェント​

デプロイの MCP サーバーを Claude Code や任意の MCP クライアントに追加します。

claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp

Claude Code で /mcp を使ってサインインします。同意ページはあなた自身のインスタンスによって提供されます。クライアントが使用できる台帳を選択して承認してください。代わりにヘッダーを送信するクライアントの場合は、パーソナルアクセストークン(後述)を作成し、Authorization: Bearer <token> として送信します。

HTTPS 経由の Git​

すべての台帳は https://<your API address>/git/<owner>/<ledger>.git にある Git リポジトリです。正確なアドレスは台帳の Git Clone メニューからコピーしてください。bex は SSH をルーティングしないため、Git は HTTPS 経由で動作します。bea がインストールされたマシンでは、Git のサインインを任せられます。

bea cloud login            # once, if you haven't already
bea cloud git setup        # Git now signs in with your bea session
git clone https://<your API address>/git/<owner>/<ledger>.git

その後、そのホストへの git clone、git pull、git push は何も要求せず、bea cloud logout で Git のサインインも削除されます。bea cloud ledger clone は SSH 経由でクローンするため、このスタックでは上記のコマンドを表示します。

台帳の Git Clone メニュー: API の HTTPS アドレスと、パスワードとしてのパーソナルアクセストークン。

bea なしで Git を使う​

CI ランナーや bea のないマシンでは、パーソナルアクセストークンで Git にサインインします。

  1. トークンを作成します。 ダッシュボードで Settings → Personal access tokens → New token を開きます。実行される場所にちなんで名前を付け(laptop、nightly-backup)、クローンとプルには ledger.read を、プッシュする場合は ledger.write を追加します。無人スクリプトの場合、単一の台帳に制限し、有効期限を設定します。bcio_ トークンは今すぐコピーしてください。一度しか表示されません。
  2. クローンします。 Git がユーザー名とパスワードを要求します。空でない任意のユーザー名を入力し、パスワードとしてトークンを貼り付けます。macOS の Keychain と Windows の Git Credential Manager は次回のためにそれを保持します。Linux では、まず認証情報ヘルパーを有効にします。例えば git config --global credential.helper 'cache --timeout=86400'(1 日間メモリに保持)です。

設定、パーソナルアクセストークン: ledger.read と ledger.write を持つトークン、そのプレフィックス、作成日時と最終使用日時。

スクリプトでは、トークンをリモート URL(Git が .git/config に保存してしまう場所)やシェル履歴に入れないでください。一時的な認証情報ヘルパーを通じて Git に渡します。

read -rs BEANCOUNT_TOKEN; export BEANCOUNT_TOKEN
helper='!f() { echo username=token; echo "password=$BEANCOUNT_TOKEN"; }; f'
git -c credential.helper= -c credential.helper="$helper" \
  clone --mirror https://<your API address>/git/<owner>/<ledger>.git

空の -c credential.helper= は、保存済みのヘルパーがトークンを保存するのを防ぎます。スクリプト内の以降のすべての git fetch や git push にも両方の -c オプションを渡してください。

Git が古いパスワードや取り消されたトークンを提示し続ける場合は、クリアします。

printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject

モバイルアプリ​

iOS または Android アプリのウェルカム画面で設定を開き、サーバー URL をダッシュボードのアドレスに設定してサインインします。

既存の帳簿を持ち込む​

ダッシュボードで台帳を作成し、クローンし、ファイルや Git 履歴をマージしてプッシュします。スタックは main.bean を台帳のエントリーポイントとして開くため、ルートファイルを main.bean と命名するか、main.bean で既存のファイルを include してください。

アカウントを追加する​

最初のアカウントの後、サインアップは閉じたままです。他の人は、あなたが接続する OpenID Connect プロバイダーを通じて参加し、そのプロバイダーが二要素サインインも処理します。beancount-api サービスの Environment タブで次のように設定します。

  1. OIDC_ISSUER、OIDC_CLIENT_ID、OIDC_CLIENT_SECRET を設定し、https://<your dashboard address>/api-gateway/auth/oidc/callback をクライアントのリダイレクト URI として登録します。その後、サインインページに Sign in with に続いて OIDC_NAME(デフォルトは SSO)が表示されます。
  2. OIDC_ALLOWED_EMAILS に参加を許可する人をカンマ区切りで列挙します。アドレス([email protected])、ドメイン(@example.com)、またはそのサブドメイン(@*.example.com)です。列挙された、検証済みのアドレスは、初回サインイン時にアカウントとデフォルト台帳を取得します。リストがない場合、プロバイダーは既にリンク済みのアカウントにのみサインインします。

あなたが受け入れた全員が、プランの制限なしに、あなたのディスクとモデルキーを共有します。誰でも参加できるプロバイダーの場合は、@gmail.com のようなドメインではなく、アドレスを列挙してください。

忘れたパスワードをリセットする​

SEND_GRID_API_KEY がない場合、パスワードを忘れた場合のページは、サーバーがメールを送信できないことをユーザーに伝えます。代わりに管理者 API からワンタイムリセットリンクを発行します。beancount-api サービスの Environment タブから ADMIN_TOKEN をコピーし、ダッシュボードではなく、そのサービス自身の onbex.co アドレスを呼び出します。

read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<your API address>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

返された resetUrl を、信頼できるチャネルでユーザーに送信してください。1 回のみ有効で、1 時間後に失効します。

警告

管理者 API は、API のアドレスに到達できる誰からも到達可能で、ADMIN_TOKEN のみがそれを守っています。このトークンは任意のユーザーとしてサインインできるため、root パスワードと同様に扱ってください。シェル履歴やチャットに残さず、漏洩した可能性がある場合はローテーションしてください。

新しいリリースに更新する​

スタックは、更新するまでデプロイしたバージョンのままです。ボタンから作成された Blueprint にはプッシュ webhook がないため、更新には 2 つのステップが必要です。

  1. Blueprint を同期する と、設定への変更が適用されます(bex API: POST /v1/blueprints/<id>/sync)。
  2. 各サービスを新しいコミットでデプロイする と、コードの変更にはビルドが必要です(commitId を指定して POST /v1/services/<id>/deploys)。

bex は一度に 1 つのサービスをビルドし、API は最後にビルドするため、全体のロールアウトには 1 時間近くかかることがあります。データを保持するスタックに新しい Blueprint を同期する前に、すでに稼働中のスタックのアップグレードを読み、まずバックアップしてください。

バックアップと復元​

台帳は Gitea のディスク上の Git リポジトリです。アカウント、パーソナルアクセストークン、設定はマネージド Postgres にあります。それぞれを独自の方法でバックアップしてください。

台帳​

ミラークローンは、台帳のファイルと履歴の完全なバックアップです。

git clone --mirror https://<your API address>/git/<owner>/<ledger>.git

bea cloud git setup を実行したマシンで、または bea なしで Git を使うのトークンヘルパーを使って実行します。復元するには、台帳がまだ一覧に表示されている場合はダッシュボードで削除し、同じ名前で作成します。サーバーは台帳の main ブランチへの強制プッシュを拒否するため、bea を使わない場合は ledger.write を持つトークンを使って、新しい台帳の最初のコミットの上にバックアップをマージします。

git clone https://<your API address>/git/<owner>/<ledger>.git restore
cd restore
git fetch ../<ledger>.git main
git merge --allow-unrelated-histories -X theirs -m "Restore from backup" FETCH_HEAD
git push origin HEAD

データベース​

bex は beancount-backend-db を継続的にバックアップし、以前の時点の状態に復元できます。復元は新しいデータベースに対して行われ、その場では決して行われないため、そのデータベースをスタック自身のデータベースにコピーし直します。

  1. bex で beancount-backend-db を開き、Recovery を選択し、少なくとも 10 分前の時刻を選んで復元します。bex はその時点のデータを持つ新しいデータベースを作成します。

  2. 復元中に何も書き込まないよう、beancount-api と beancount-gitea を一時停止します。

  3. PostgreSQL 16 の pg_dump と pg_restore(postgres:16 Docker イメージには両方含まれています)でデータをコピーし直します。両端とも beancount-backend-db の外部接続文字列を使用し、コピー先にはホストだけをコピーのものに変更します。コピー用に bex が表示する接続情報は使用しないでください。それらは復元されたデータを読み取れないデータベースとユーザーを指しています。

    read -rs DB_URL; export DB_URL   # beancount-backend-db's external connection string
    COPY_URL="${DB_URL/@<database host>/@<copy host>}"
    pg_dump -Fc --no-owner --no-privileges "$COPY_URL" > backend.dump
    pg_restore --clean --if-exists --no-owner --no-privileges -d "$DB_URL" backend.dump

    pg_restore は vector と pg_stat_statements 拡張機能を削除できない可能性があると報告しますが、これらのエラーは想定内です。コピーの証明書がまだ発行中の場合、COPY_URL に ?sslmode=verify-full を追加し、コピー用に bex が表示する CA を ~/.postgresql/root.crt として保存してください。接続がタイムアウトする場合は、再試行してください。

  4. beancount-gitea と beancount-api を再開し、コピーを削除します。

ワークスペースから出るもの​

スタックは Beancount.io にアナリティクスやテレメトリを送信せず、ブラウザのアナリティクススクリプトはビルドから除外されています。私たちが知る限り、唯一の外向きリクエストは次のとおりです。

  • パスワード漏洩チェック: 新しいパスワードの SHA-1 ハッシュの最初の 5 文字を、k-匿名性によってチェックするため、パスワードもアカウントも明らかになりません。
  • アバター: ブラウザが、ユーザーのメールアドレスのハッシュによって Gravatar に画像を要求します。
  • フィード: Beancount.io のブログと変更履歴のフィードで、受け取るのは言語設定のみです。
  • 価格フィード: 台帳がマネージド価格 URL を含む場合にのみ、beancount.io へのリクエストが発生します。
  • あなたの統合機能: 接続したものすべて、例えばモデルプロバイダー、SendGrid、S3、Plaid、アイデンティティプロバイダーなど。

各リクエストがいつ発生するかは、PRFAQ006 のプライバシー表に記載されています。あなたのサービス、ディスク、データベースは bex のインフラストラクチャ上で、bex のプライバシーポリシーと利用規約の下で動作します。bex は Beancount.io を手がける Stargately, Inc. が構築しています。ホスト型の Beancount.io サービスはあなたのスタックとは別物で、そのシークレットを一切保持しません。

スタックを削除する​

警告

リソースを削除すると、請求が停止し、データも一緒に削除されます。まずすべての台帳をクローンしてください。

上記のとおりにバックアップした後、bex で 6 つのリソースを削除し、続いて Blueprint を削除します。スタックを保持したまま自分のアカウントだけを削除するには、ホスト型サービスと同様に Settings → General → Danger Zone で削除します。唯一のアカウントを削除すると、サインアップが再び開きます。

代わりに自分のサーバーで動かす​

Docker デプロイメントは、自分が管理する任意のサーバーで同じスタックを動かします。bex デプロイメントのノートでは、このガイドのすべての設定をより詳しく説明しています。

問題が発生しましたか? GitHub issue を開くか、Beancount Telegram チャットで質問してください。

出典: https://beancount.io/ja/docs/self-host-beancount-io