コンテンツにスキップ
SpantailSpantail docs

Cloudflare へデプロイ

Spantail は、あなた自身の Cloudflare アカウントへのデプロイを前提に設計されています。推奨経路は フォークを Cloudflare Workers Builds に 連携する方法です。一度設定すれば、push も GitHub の Sync fork ボタンも、先にマイグレーションを 実行してから自動でデプロイします。インスタンス固有の ID をコミットしないため、upstream への追従で 衝突することもありません。

自分のマシンからデプロイしたい場合は、Wrangler による手動デプロイを 下に残しています。

まずローカルで試す

Section titled “まずローカルで試す”

デプロイ前に手元で動かす場合 — ローカルの D1 エミュレーションを使い、Cloudflare リソースは不要です。

git clone https://github.com/spantail/spantail.git
cd spantail
pnpm install

# ローカル用の環境変数を作成し、BETTER_AUTH_SECRET（32 文字以上）を設定
cp apps/web/.dev.vars.example apps/web/.dev.vars

pnpm db:migrate:local   # ローカル D1 エミュレーターにマイグレーションを適用
pnpm dev                # SPA + Worker を http://localhost:5173 で起動

.dev.vars の各値については設定を参照してください。推奨経路は デプロイ自体にはローカルの Node・pnpm・Wrangler は不要で、GitHub アカウントと Cloudflare アカウント だけで完結します(アップグレード時のデータベースバックアップにはローカルの Wrangler を使います)。

Workers Builds でデプロイ（推奨）

Section titled “Workers Builds でデプロイ（推奨）”

  1. GitHub でリポジトリをフォークします(Fork → 自分のアカウントまたは Organization)。公開リポジトリ のフォークはそれ自体も公開になりますが、ここでは問題ありません — シークレットやインスタンス固有の ID を コミットしないためです(いずれも Cloudflare 側にあります)。プライベートなリポジトリが必要な場合は、代わりに プライベートなミラーを push し、アップグレードは upstream からマージして行います。Sync fork ボタンは 実際のフォークにのみ効きますが、Workers Builds 自体はプライベートリポジトリに対応しています。

  2. Cloudflare アカウントに D1 データベースと R2 バケットを作成します。ダッシュボード (Storage & Databases → D1 と R2)か Wrangler を使います。

    wrangler d1 create spantail-db
wrangler r2 bucket create spantail-uploads

    出力から D1 の database_id を控えます。これが次で渡す唯一のインスタンス固有値です。

  3. フォークから Worker を作成します。ダッシュボードで Workers & Pages → 作成 → Connect GitHub を開き、フォークに Cloudflare の GitHub アプリをインストールして選択し、 次を設定します。

    • プロジェクト名: spantail — apps/web/wrangler.jsonc の name と一致させます。異なると Cloudflare が名前を揃えるための Pull Request をフォークに作成し、Sync fork と衝突します。
    • ビルド コマンド: 値が入っていたら空にします。
    • デプロイ コマンド: 初期値を pnpm run deploy:ci に書き換えます。
    • 詳細設定 → パス: apps/web
    • 詳細設定 → 変数を追加する: D1_DATABASE_ID = 手順 2 の database_id

    deploy:ci はビルド・リモートデータベースへのマイグレーション適用・デプロイを 1 コマンドで行います。 D1_DATABASE_ID はビルド時に注入されるため、インスタンス固有の値をフォークにコミットする必要は ありません。

  4. セッション署名用シークレットを設定します。BETTER_AUTH_SECRET(32 文字以上)を Worker の シークレットとして追加します。Worker の 設定 → 変数とシークレット、または Worker 作成後に Wrangler で設定します。

    wrangler secret put BETTER_AUTH_SECRET --name spantail   # 例: `openssl rand -base64 32` を貼り付け

  5. デプロイ。 設定を保存すると初回ビルドが走り、全マイグレーションを適用して Worker を *.workers.dev の URL にデプロイします。BETTER_AUTH_URL は未設定のままで構いません — Spantail は リクエストからオリジンを導出します(カスタムドメインを固定する場合は 設定を参照)。

アップグレード

Section titled “アップグレード”

フォークのページで Sync fork をクリックし、upstream の最新リリースを取り込みます。Workers Builds が その push を検知し、deploy:ci(マイグレーション → デプロイ)を自動実行します。フォークにインスタンス 固有の ID をコミットしていないため、Sync fork が衝突することはありません。

大きなアップグレードの前にはデータベースをバックアップし(wrangler d1 export spantail-db --remote)、 Cloudflare の D1 Time Travel で特定時点へ 復元することもできます。

Wrangler による手動デプロイ

Section titled “Wrangler による手動デプロイ”

自分のマシンからデプロイしたい場合は、リソースを用意して直接デプロイします。ローカルの 要件(Node・pnpm・Wrangler)が必要です。

  1. クローンしてインストール。

    git clone https://github.com/spantail/spantail.git
cd spantail
pnpm install

  2. リソースを作成し、生成された D1 の ID を apps/web/wrangler.jsonc にコピーします。

    wrangler d1 create spantail-db
wrangler r2 bucket create spantail-uploads

    返ってきた database_id を apps/web/wrangler.jsonc の d1_databases ブロックに設定します (プレースホルダー ID で出荷されています)。

  3. セッション署名用シークレットを設定します。32 文字以上の値を生成してください。

    pnpm --filter web exec wrangler secret put BETTER_AUTH_SECRET   # 例: `openssl rand -base64 32` を貼り付け

  4. マイグレーションを適用してからデプロイします。順序が重要です — デプロイの前にマイグレーション。

    pnpm db:migrate:remote
pnpm run deploy

    pnpm deploy(pnpm の組み込みコマンド)ではなく pnpm run deploy を使ってください。

デプロイ後

Section titled “デプロイ後”

既定ではアプリがリクエストごとにオリジンを導出するため、*.workers.dev の URL でもリンクや OAuth コールバックは追加設定なしで動作します。正規のオリジンを固定したい場合 — カスタムドメインや、ホストを 書き換えるプロキシの背後 — は BETTER_AUTH_URL を設定します。これと、任意のソーシャルログイン・ メール用シークレットは設定で扱います。

インスタンスの前段のプロキシにパススコープ付きのルールを置く場合 — たとえば /api と /mcp を SSO から除外する Cloudflare Access ポリシー — は、パスマッチャが二重スラッシュ(//api/…)を 許容するか、それを含むプレフィックスでマッチするようにしてください。末尾スラッシュ付きのベース URL を 設定されたクライアントはそうしたパスを生成することがあり(プラグインの MCP エンドポイント URL は クライアント側では正規化できません)、Worker による二重スラッシュの正規化はリクエストが Worker に 届いて初めて働きます。

Workers の URL で読み込まれたインスタンスのサインアップ画面。

Worker が稼働したら、最初にサインアップした人がインスタンス管理者になります。 初回セットアップウィザードへ進んでください。