Next.js を Sevalla にデプロイする
Sevalla は Kinsta が提供する PaaS で、Next.js 向けに 2 つのホスティング製品があります。
- Application Hosting: 実際の Node.js サーバーを実行します。SSR、ルートハンドラ (API ルート)、プロキシ (旧ミドルウェア)、ISR (
revalidate)、サーバーアクション、WebSocket に必要です。 - Static Site Hosting: 静的エクスポート (
output: 'export') の出力を配信します。サーバーサイドコードは一切不要です。1 社あたり最大 100 の静的サイトに制限されています。
この判断を最初に正しく行ってください。これによって以下のすべてが決まります。
ステップ 0: 使用するホスティング製品を決定する
何よりも先にリポジトリを確認します。
next.config.js/next.config.ts/next.config.mjsを読み、output: 'export'またはoutput: 'standalone'を確認します。- コードベースから以下を検索します:
app/api/、pages/api/、proxy.tsまたはproxy.js(Next.js 16)、middleware.tsまたはmiddleware.js(Next.js 15 以前)、"use server"、getServerSideProps、revalidate(ISR)、NextResponse、またはサーバーサイドで使用されるデータベース/認証クライアント。 - 判断します:
- 上記のいずれかが存在する場合: Application Hosting (サーバーが必要)。ステップ 1 に進みます。
- 何も存在せず、純粋に静的なコンテンツ、マーケティング、ブログの場合: Static Site Hosting の方がシンプルで低コストです。
references/static-hosting.mdを参照してください。 - 判断に迷う場合、または後で動的機能が必要になる可能性がある場合: デフォルトで Application Hosting を使用します。Static Hosting でできることはすべて実現できます。
本当に曖昧な場合は、ユーザーに「このアプリにはライブサーバー (API ルート、ISR、認証、データベース呼び出し) が必要ですか、それとも完全に静的なコンテンツですか？」と 1 つ質問してください。推測で判断してはいけません。間違った選択をするとデプロイ全体を作り直すことになるからです。
また、リポジトリ内にデータベースクライアント (Prisma、Drizzle、pg、mysql2、Mongoose、redis、ioredis) やファイルアップロードがないか確認してください。見つかった場合は、ステップ 3 の前に references/data-services.md を読んでください。
ステップ 1: ビルド戦略を選択する (Application Hosting)
Sevalla は Git ベースのアプリケーションを 4 つの戦略のいずれかでビルドします:
- Nixpacks: デフォルト。標準的な Next.js アプリでは設定不要です。理由がない限りこれを使用します。
- Railpack: Nixpacks の後継。こちらも設定不要です。新しいアプリには良い選択です。API フィールド
build_type: "railpack"で設定します。 - Dockerfile: 小さく再現可能なイメージが必要な場合、自動検出ビルダーが苦手とするモノレポの場合、またはユーザーが Docker を希望する場合に使用します。
- Buildpacks (
pack): Next.js ではほとんど必要ありません。
設定を書く前に references/app-hosting.md を読んでください。正確な package.json スクリプト、推奨 Dockerfile、nixpacks.toml オーバーライド、モノレポの Build path 設定が記載されています。一般的な Next.js の知識だけで Dockerfile や nixpacks.toml を手書きしないでください。Sevalla には一般的なガイドでは触れられていない固有の制約 (以下参照) があります。
ステップ 2: リポジトリを準備する (Sevalla の制約)
これらはほとんどの初回デプロイで問題になります。デプロイ前にすべて確認してください:
$PORTからポートを読み取り、0.0.0.0にバインドします。 デフォルトの Web プロセスポートは 8080 で、Sevalla はそれをPORTに渡します。インターネットに対してはポート 80 と 443 のみが開放され、Sevalla はそれらを$PORTにルーティングします。Nixpacks または Railpack の場合、起動スクリプトはnext start -p ${PORT:-8080} -H 0.0.0.0でなければなりません。単純なnext startはポート 3000 で待機します。NEXT_PUBLIC_*変数はビルド時にインライン化されます。 ビルドを実行する前に、ビルド時変数 (is_buildtime: true) として作成してください。後から追加した変数は、再起動ではなく新しいデプロイが必要です。- ファイルシステムは ephermeral です。 アプリが実行時にディスクに書き込むもの (アップロード、生成ファイル、オンディスクキャッシュ) は、再デプロイまたは再起動のたびに失われます。オブジェクトストレージを使用するか、アプリがローカルディスクへの書き込みを本当に必要とする場合 (SQLite やセルフホスト CMS など) は永続ディスクを使用してください。
references/data-services.mdを参照してください。 output: 'standalone'は Dockerfile のみで使用します。next startはスタンドアロンバンドルを使用せず、Next.js は"next start" does not work with "output: standalone" configurationと警告します。したがって、Nixpacks または Railpack の場合はoutputを設定しないでください。Dockerfile の場合はoutput: 'standalone'を設定します。node_modulesや.nextをコミットしないでください。 コミットされたnode_modulesフォルダは、Sevalla でビルドが失敗する原因として文書化されています。- Node.js のバージョンを固定します。 Nixpacks はデフォルトで Node 18 を使用し、Next.js 16 には Node 20.9 以降が必要です。
package.jsonに"engines": { "node": "22.x" }を設定するか、ビルド時変数NIXPACKS_NODE_VERSION=22を設定します。 - モノレポ: Build path (API フィールド
build_path) を Next.js アプリのフォルダ (例:apps/web) に設定します。Dockerfile の場合は、docker_contextとdockerfile_pathも設定します。 package.jsonの name: パッケージ名に"node"や"js"を使用しないでください。Sevalla のビルドが壊れることが文書化されています。- 変数値内の二重引用符 は
\"としてエスケープする必要があります。エスケープされていない引用符は削除されるか、ロールアウトを失敗させます。 - シークレット (データベース URL、API キー) は Sevalla の環境変数に格納します。実際のシークレットが入った
.envファイルをコミットしないでください。
ステップ 3: デプロイする
利用可能な最初のオプションを、以下の順序で使用します:
- Sevalla MCP サーバー (
https://mcp.sevalla.com/mcp)。search(仕様内の API エンドポイントを検索) とexecute(sevalla.request({ method, path, body })を呼び出す JavaScript を実行) の 2 つのツールがあります。以下の表の API パスを使用します。 sevallaCLI。すべてのコマンドで--jsonを使用して ID を読み取れるようにします。npm install -g @sevalla/cli(Node 22+) またはbrew install sevalla-hosting/tap/sevallaでインストールします。sevalla login(ブラウザでのデバイス認可) またはSEVALLA_API_TOKENの設定でログインします。- REST API。ベアラー API キーを使用して
https://api.sevalla.com/v3にアクセスします。
どれも利用できない場合は、MCP サーバーの追加方法をユーザーに伝えるか (https://docs.sevalla.com/quick-starts/coding-agents/overview のコーディングエージェントクイックスタートを参照)、references/dashboard.md のダッシュボード手順を提供してください。最初のログインだけはユーザー自身が必要です。
Application Hosting
| # | アクション | API (MCP execute または REST) | CLI |
|---|---|---|---|
| 1 | ロケーションを選択 | GET /resources/clusters | sevalla resources clusters --json |
| 2 | アプリを作成 | POST /applications に display_name、cluster_id、source (privateGit は接続済みの GitHub/GitLab/Bitbucket リポ、publicGit は公開 URL)、git_type、repo_url、default_branch を指定 | sevalla apps create --name <name> --cluster <cluster-id> --source privateGit --git-type github --repository https://github.com/<owner>/<repo> --branch <branch> --json |
| 3 | ビルド戦略とビルドパスを設定 (デフォルトと異なる場合) | PATCH /applications/{id} に build_type (nixpacks、railpack、dockerfile、pack) と build_path を指定 | sevalla apps update <app-id> --build-type railpack --json。CLI にはビルドパスフラグはありません: sevalla apps update <app-id> --data '{"build_path":"apps/web"}' --json |
| 4 | 環境変数を追加 | POST /applications/{id}/env-vars に key と value を指定。is_runtime と is_buildtime はデフォルトで両方 true になり、NEXT_PUBLIC_* に適しています。 | sevalla apps env-vars create <app-id> --key <KEY> --value "<value>" (ビルド時と実行時の両方で利用可能) |
| 5 | データベースがあれば接続 | references/data-services.md を参照 | |
| 6 | デプロイ | POST /applications/{id}/deployments。アプリを作成してもデプロイは開始されません。 | sevalla apps deployments trigger <app-id> --branch <branch> --json |
privateGit リポジトリでステップ 2 が HTTP 500 で失敗する場合、最も可能性の高い原因は Sevalla の GitHub アプリがリポジトリを認識できないことです。API はそのことを通知しません。sevalla git providers --json で確認してください: settings_url で GitHub アプリのインストールページが開きます。ユーザー (または GitHub 組織のオーナー) がアプリにリポジトリへのアクセス権を付与する必要があります。ユーザーが所有していない組織内のリポジトリは、オーナーが追加する必要があります。その後、ステップ 2 を再試行してください。
新しいアプリでは自動デプロイはオフになっています。ユーザーがプッシュのたびにデプロイを希望する場合は、PATCH /applications/{id} で auto_deploy: true を設定します (privateGit のみ機能します)。
Static Site Hosting の場合は、代わりに references/static-hosting.md に従ってください。静的サイトを作成すると、最初のデプロイが自動的に開始されます。
ステップ 4: 確認する
開始されたデプロイが動作するデプロイであるとは限りません。完了したとユーザーに伝える前に、以下のすべてを実行してください:
- ビルドを待ちます。
GET /applications/{id}/deployments/{deployment_id}(CLI:sevalla apps deployments get <deployment-id> --app-id <app-id> --json) を 15 秒から 30 秒ごとにポーリングし、statusがsuccessまたはfailedになるのを確認します。その他の値はwaiting、inProgress、cancelled、skippedです。 - 失敗した場合、ビルドログを読みます。
GET /applications/{id}/deployments/{deployment_id}/logs(CLI:sevalla apps deployments logs ...)。エラーをreferences/app-hosting.mdのトラブルシューティング表と照合し、原因を修正して再度デプロイします。ログを読まずに推測で 2 回試してはいけません。成功はデプロイのstatusで判断し、ログの重大度では判断しません: 通常のビルド出力が stderr に書き込まれると、成功したビルドでも"severity": "error"として表示されます。 - ライブ URL を見つけます。
GET /applications/{id}/domains(CLI:sevalla apps domains list --app-id <app-id> --json)。すべてのアプリは、最初の成功したデプロイ後に無料の*.sevalla.appドメインを取得します。 - URL をリクエストします。
/と (アプリにある場合) 1 つのルートハンドラで HTTP 200 を期待します。502 またはタイムアウトは通常、サーバーが$PORTと0.0.0.0でリッスンしていないことを意味します。 - アプリがエラーで応答する場合、ランタイムログを読みます。
GET /applications/{id}/runtime-logs(CLI:sevalla apps logs runtime <app-id>)。
その後、ユーザーにライブ URL、設定した内容、およびユーザー自身が行う必要があること (カスタムドメインの DNS レコード追加など) を伝えます。
ステップ 5: オプションの次のステップ
- カスタムドメイン:
sevalla apps domains add <app-id> --name example.com。ユーザーは Sevalla が返す DNS レコードを追加する必要があります。SSL は含まれています。 - スケーリング:
sevalla apps processes update <process-id> --app-id <app-id> --instances <n>。複数のインスタンスがある場合は、共有状態に永続ディスクを使用しないでください。オブジェクトストレージまたはデータベースを使用します。 - ロールバック:
sevalla apps deployments rollback <app-id> --deployment-id <id>。
リファレンスファイル
references/app-hosting.md:package.jsonスクリプト、Nixpacks と Railpack の注意点、推奨 Dockerfile、モノレポ設定、トラブルシューティング表。references/static-hosting.md: Static Site Hosting の静的エクスポート設定とデプロイ。references/data-services.md: データベース、オブジェクトストレージ、永続ディスク、およびそれらの接続詳細がアプリに到達する方法。references/dashboard.md: 人間向けの Sevalla ダッシュボードでの同じ手順。