クイックスタート
Core で顧客アプリと永続 worker をローカル起動し、必要になったら管理コンソールと Content Studio を追加します。
コミット
e632762で確認済みです。
まず Core から始めます。顧客アプリ、永続 worker、PostgreSQL、Redis、非公開のローカルオブジェクトストレージが含まれます。最初の目標は、ログイン、デモクレジットの確認、模擬画像ジョブの実行、非公開の結果と台帳の確認までをローカルで完了することです。このローカル体験には Stripe、メール、AI プロバイダーのアカウントは不要です。
開始する構成を選ぶ
| プロファイル | 起動するもの | 選ぶ場面 |
|---|---|---|
| Core — 最初におすすめ | 顧客アプリ + 永続 worker | スターターの評価や製品開発を始めるとき。 |
| Operations | Core + 管理コンソール | 請求、ジョブ、顧客サポートを運用するとき。 |
| Publishing | Operations + Content Studio | 独立したコンテンツ編集アプリも必要なとき。 |
他のアプリは後から追加できます。プロファイルはローカルツールとビルド対象を選ぶもので、製品プラン、権限、利用可能な API ルートは変更しません。
1. 環境を準備する
- Git
- Node.js
>=24.22.1 <25（.nvmrcが検証済みバージョンを指定） - pnpm
10.22.0 - ローカルで起動した Docker と Compose
2. Core を起動する
ターミナルで次のコマンドを実行します。確認済みのソースコミットからブランチを作り、コードと手順を揃えます。
git clone https://github.com/PansaLegrand/sushi-saas-template.git
cd sushi-saas-template
git switch -c my-saas e63276252e4b64566229cb87225afc72da6991de
export SAAS_STARTER_PROFILE=core
pnpm starter core install
pnpm starter core setup
pnpm starter core doctor
pnpm starter core demodemo は最初に読み取り専用の doctor を実行し、成功後だけアカウントを準備して、模擬画像が有効な Core を起動します。模擬失敗回数はゼロ、ローカル captcha は無効です。このプロセスのメール・Slack・Stripe は無効になり、環境ファイルは変更しません。商用 AI プロバイダーには接続しません。bash/zsh または WSL を使ってください。通常の pnpm starter core dev は従来の開発用で、このデモモードを自動では有効にしません。
ターミナルを起動したまま、localhost:3000/ja/login を開きます。
Setup は不足している Git 管理対象外の環境ファイルを作り、PostgreSQL、Redis、Garage を起動します。ローカルのアプリ・テスト・復元訓練用 DB を作成し、Drizzle マイグレーションを適用して非公開の sushi-dev bucket を準備します。Core は Content Studio のインストール、環境ファイル、DB 作成、マイグレーションを省略します。Setup は再実行でき、既存の環境ファイルを上書きしません。
Setup は環境ファイルを書き込む前に、Docker の稼働、Docker Compose、ポート 5432/6379 のサービスがこのプロジェクトに属するかを確認します。ツール不足、Docker 停止、別サービスとの競合があればエラーで終了します。指摘された前提条件を解決してから再実行してください。
doctor はツール、環境境界、インフラ、マイグレーション、ストレージ、ポートを読み取り専用で検査し、秘密値は表示しません。Demo は seed 前に doctor を実行し、その後は同じ確認を繰り返さず web と worker を起動します。Ctrl-C で両方を停止します。
フィルター付きインストール後、通常の pnpm lint やコミットに使う各ターミナルで SAAS_STARTER_PROFILE=core を export し、同じ構成で検査します。ここでの export は POSIX shell 用です。PowerShell では $env:SAAS_STARTER_PROFILE="core" を使います。
3. 最初の動作画面を確認する
- 新規アカウントは
demo@example.testとDemoPass123!、または作成時に使ったDEV_SEED_PASSWORDでログインします。既存アカウントは元のパスワードを保持し、demo の出力も変更していないことを示します。 - アカウント → クレジットを開きます。一度だけ付与される 1,000 デモクレジットを確認します。Worker が別の新規登録ボーナス 10 クレジットも処理すると、新規環境の残高は 1,010 になります。デモ付与額は、総残高が常に 1,000 であるという意味ではありません。
- アカウント → プロフィールとセキュリティで設定を確認します。ワークスペースとセッションは実際のローカルアプリで動作しています。
この認証情報はローカル開発専用です。Seed は予約済みドメインの検証済みアカウントを作り、同じクレジット付与を重複させずに不足データを修復します。メール送信は不要です。既存のデモ操作により表示残高が変わることがあります。
4. 最初の画像タスクを完了する
- 起動時のクレジット付与が終わったら、アカウント → クレジットを再読み込みして残高を控えます。この手順では同じワークスペースを使い続けてください。
- ローカルの画像タスクを開き、アプリが URL に追加する
orgパラメーターを保持します。プロンプトに初めての Sushi SaaS 画像タスクと入力し、画像を生成を一度押します。 - ワーカーの処理待ち…、**画像を生成して保存中…**が短く表示される場合があります。画像の準備ができましたまで待ちます。期待する結果は Image generation mock とプロンプトが入った青紫の SVG です。模擬応答であり、AI が描いたイラストではありません。
- 同じタスク URL を再読み込みします。同じタスク ID と画像が復元され、追加課金は発生しません。別の画像を生成は新規タスクを作成する操作で、さらに 5 クレジット消費します。
- 同じワークスペースの アカウント → クレジットで、画像生成の −5 記録が一つあることを確認します。他の台帳処理がなければ、残高は控えた値から 5 減ります。1,000 → 995、登録ボーナス反映後なら 1,010 → 1,005 です。アカウント → ファイルには
generated-<タスク ID>.svgが表示されます。
結果はローカルの非公開 Garage bucket に保存されます。画面は 15 分間有効な署名 URL で画像を表示し、保存したタスク URL を開き直すと新しい URL を取得します。署名 URL の所持者は一時的にファイルへアクセスできるため、恒久的な公開 URL ではありません。
**確認できた流れ：**ログイン → ワークスペース認可 → 一度だけの 5 クレジット消費 → 永続 worker → 非公開の結果 → 復元できるタスク画面。Free プランで利用できる画像サンプルなので、契約や --paid-examples の seed は不要です。
初回実行で止まったら
| 状況 | 確認すること |
|---|---|
| Setup が終わってもローカルサービスがない | pnpm starter core setup または pnpm run setup を使います。setup は pnpm 自身のコマンド名でもあるため、プロジェクトスクリプトを直接呼ぶ場合は run が必要です。 |
| 画像ページが 404 | pnpm starter core demo で再起動します。通常の dev は模擬画像を有効にせず、このデモは本番でも利用できない設計です。 |
| タスクが待機したまま | Core のターミナルを開いたまま、[worker] ログを確認します。pnpm dev 単独では worker は起動しません。 |
| ログインできない | 新規アカウントは DEV_SEED_PASSWORD 未設定なら demo@example.test / DemoPass123! です。既存アカウントのパスワードは再 seed でも変わりません。 |
| 残高がちょうど 995 ではない | このタスクの −5 記録が一つか確認します。登録付与、以前のデモ、別の操作は別々に記録されます。 |
| 画像やストレージが失敗 | pnpm starter core doctor と worker のエラーを確認し、画像フローのトラブルシューティングへ進みます。新規送信せず既存タスクを再読み込みします。 |
ローカル環境を検証する
別のターミナルでサービスを確認します。
curl http://localhost:3000/api/health
curl http://localhost:3000/api/ready
pnpm test:fast開発と本番ビルドは .next を共有するため、ビルド前に Ctrl-C で開発プロセスを停止します。
pnpm starter core buildビルドはルートのテストを維持し、worker ランタイムもまとめます。実際のローカルストレージとモックプロバイダーのジョブを使うブラウザ検証は、使い捨て環境向けのテストと CIを参照してください。
5. 自分の製品にする
pnpm customize で製品情報、外観、言語を設定します。製品のカスタマイズとアーキテクチャとエラー契約へ進んでください。外部サービスは該当機能を使う段階で設定します。環境設定を参照してください。
必要なアプリを追加する
プロファイル変更前に現在の開発プロセスを停止します。http://localhost:3001 の管理コンソールを追加するには：
export SAAS_STARTER_PROFILE=operations
pnpm starter operations install
pnpm starter operations setup
pnpm starter operations dev運用者権限と MFA は管理コンソール設定に従ってください。デモ顧客は自動的に管理者にはなりません。
http://localhost:3002/admin の Content Studio も追加するには：
export SAAS_STARTER_PROFILE=publishing
pnpm starter publishing install
pnpm starter publishing setup
pnpm starter publishing devPublishing は独立した Payload DB とマイグレーションを準備します。認証と DB は SaaS と分離してください。Content Studio とマーケティングで説明しています。
全プロファイルで doctor、lint、build、--dry-run を利用できます。プロファイル未選択なら、pnpm run setup、pnpm dev:all、pnpm build は全アプリ構成を維持します。対話型の全体セットアップには、SAAS_STARTER_PROFILE を設定していない shell で ./scripts/setup.sh development を使います。
ローカルデータのリセットは確認して行う
pnpm dev:reset -- --dry-run
pnpm dev:reset先に対象を確認します。Reset は外部サービスを拒否し、明示的な確認を求め、この Compose プロジェクトのローカルデータだけを再作成します。マイグレーションと、指定がなければ seed を再実行します。環境ファイルは保持します。通常の再起動には不要です。