moai-platform-deployment

デプロイプラットフォームの専門ガイド

Vercel（エッジ優先）、Railway（コンテナ優先）、Convex（リアルタイムバックエンド）を網羅したデプロイプラットフォームガイドです。

---

プラットフォームのクイック選択

各プラットフォームの用途

Vercel - エッジ優先のデプロイ：

• SSR／SSG を使用する Next.js アプリケーション
• グローバルな CDN 配信が必要
• 50 ミリ秒未満のエッジレイテンシが重要
• チームでのコラボレーションに向けたプレビューデプロイ
• マネージドストレージのニーズ（KV、Blob、Postgres）

Railway - コンテナ優先のデプロイ：

• フルスタックのコンテナ化アプリケーション
• カスタムランタイム環境
• マルチサービスアーキテクチャ
• 永続ボリュームストレージ
• WebSocket／gRPC による長時間接続

Convex - リアルタイムバックエンド：

• リアルタイムの共同作業アプリケーション
• リアクティブなデータ同期
• TypeScript 優先のバックエンドニーズ
• 楽観的 UI 更新
• ドキュメント指向のデータモデル

---

選択ガイド

アプリケーションの種類別

Web アプリケーション（フロントエンド＋API）：

• Next.js → Vercel（最適な統合）
• カスタム API を使用する React／Vue → Railway（柔軟）
• リアルタイム共同作業 → Convex + Vercel

モバイルバックエンド：

• REST／GraphQL → Railway（安定した接続）
• リアルタイム同期 → Convex（リアクティブクエリ）
• エッジ API → Vercel（グローバルな低レイテンシ）

フルスタックモノリス：

• コンテナ化 → Railway（Docker 対応）
• サーバーレス → Vercel（Next.js API ルート）
• リアルタイム → Convex（リアクティビティを標準搭載）

インフラストラクチャのニーズ別

コンピューティング要件：

• エッジコンピューティング → Vercel（30 以上のエッジロケーション）
• カスタムランタイム → Railway（Docker の柔軟性）
• サーバーレス TypeScript → Convex（マネージドランタイム）

ストレージ要件：

• Redis／KV → Vercel KV または Railway
• PostgreSQL → Vercel Postgres または Railway
• ファイルストレージ → Vercel Blob または Railway ボリューム
• ドキュメント DB → Convex（標準搭載）

ネットワーク要件：

• CDN 配信 → Vercel（標準搭載）
• プライベートネットワーキング → Railway（サービスメッシュ）
• リアルタイム WebSocket → Convex（標準搭載）または Railway

---

一般的なデプロイパターン

パターン 1：データベースを使用する Next.js

スタック：Vercel + Vercel Postgres／KV

セットアップ：

1. Next.js アプリを Vercel にデプロイします
2. データベース用に Vercel Postgres をプロビジョニングします
3. セッション／キャッシュに Vercel KV を使用します
4. 環境変数を設定します
5. 動的コンテンツ向けに ISR を有効にします

最適な用途：標準的なデータベースニーズを持つ Web アプリ、e コマース、コンテンツサイト

パターン 2：コンテナ化されたマルチサービス

スタック：Railway + Docker

セットアップ：

1. マルチステージ Dockerfile を作成します
2. サービス用に railway.toml を設定します
3. プライベートネットワーキングをセットアップします
4. 永続ボリュームを設定します
5. オートスケーリングを有効にします

最適な用途：マイクロサービス、複雑なバックエンド、カスタム技術スタック

パターン 3：リアルタイム共同作業アプリ

スタック：Convex + Vercel／Railway（フロントエンド）

セットアップ：

1. Convex バックエンドを初期化します
2. スキーマとサーバー関数を定義します
3. フロントエンドを Vercel／Railway にデプロイします
4. Convex プロバイダーを設定します
5. 楽観的更新を実装します

最適な用途：共同作業ツール、ライブダッシュボード、チャットアプリケーション

パターン 4：エッジ＋コンテナのハイブリッド

スタック：Vercel（フロントエンド／エッジ）+ Railway（バックエンドサービス）

セットアップ：

1. Next.js フロントエンドを Vercel にデプロイします
2. バックエンドサービスを Railway にデプロイします
3. CORS と API エンドポイントを設定します
4. ルーティング用にエッジミドルウェアをセットアップします
5. Railway のプライベートネットワーキングを使用します

最適な用途：高性能アプリ、複雑なバックエンドを備えたグローバル配信

パターン 5：サーバーレスのフルスタック

スタック：Vercel（フロントエンド＋API ルート）+ Convex（バックエンド）

セットアップ：

1. API ルートを含む Next.js アプリを構築します
2. データレイヤーとして Convex を初期化します
3. 認証（Clerk／Auth0）を設定します
4. フロントエンドを Vercel にデプロイします
5. Convex クライアントを接続します

最適な用途：迅速なプロトタイピング、スタートアップ、リアルタイム Web アプリ

---

基本設定

Vercel クイックスタート

vercel.json：

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1", "fra1"],
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

エッジ関数：

export const runtime = "edge"
export const preferredRegion = ["iad1", "sfo1"]

export async function GET(request: Request) {
  const country = request.geo?.country || "Unknown"
  return Response.json({ country })
}

Railway クイックスタート

railway.toml：

[build]
builder = "DOCKERFILE"
dockerfilePath = "Dockerfile"

[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 100
restartPolicyType = "ON_FAILURE"
numReplicas = 2

[deploy.resources]
memory = "2GB"
cpu = "2.0"

マルチステージ Dockerfile：

# Builder stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runner stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && adduser -S appuser -u 1001
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER appuser
EXPOSE 3000
CMD ["node", "dist/main.js"]

Convex クイックスタート

convex/schema.ts:

import { defineSchema, defineTable } from "convex/server"
import { v } from "convex/values"

export default defineSchema({
  messages: defineTable({
    text: v.string(),
    userId: v.id("users"),
    timestamp: v.number(),
  })
    .index("by_timestamp", ["timestamp"])
    .searchIndex("search_text", {
      searchField: "text",
      filterFields: ["userId"],
    }),
})

React 統合:

import { useQuery, useMutation } from "convex/react"
import { api } from "../convex/_generated/api"

export function Messages() {
  const messages = useQuery(api.messages.list)
  const sendMessage = useMutation(api.messages.send)

  if (!messages) return <div>Loading...</div>

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg._id}>{msg.text}</div>
      ))}
    </div>
  )
}

---

CI/CD 統合

GitHub Actions - Vercel

name: Deploy to Vercel
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}

GitHub Actions - Railway

name: Deploy to Railway
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @railway/cli
      - run: railway up --detach
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

GitHub Actions - Convex

name: Deploy to Convex
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npx convex deploy
        env:
          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}

---

高度なパターン

Blue-Green デプロイ (Vercel)

新しいバージョンをデプロイし、プレビュー URL でテストしてから、Vercel SDK を使用して本番エイリアスを切り替えることで、ゼロダウンタイムのリリースを実現します。

マルチリージョン (Railway)

railway.toml でデプロイリージョンを構成します:

[deploy.regions]
name = "us-west"
replicas = 2

[[deploy.regions]]
name = "eu-central"
replicas = 1

楽観的更新 (Convex)

const sendMessage = useMutation(api.messages.send)

const handleSend = (text: string) => {
  sendMessage({ text })
    .then(() => console.log("Sent"))
    .catch(() => console.log("Failed, rolled back"))
}

---

プラットフォーム固有の詳細

プラットフォーム固有の詳細なパターン、構成オプション、高度なユースケースについては、以下を参照してください:

• reference/vercel.md - Edge Functions、ISR、Analytics、Storage
• reference/railway.md - Docker、マルチサービス、ボリューム、スケーリング
• reference/convex.md - リアクティブクエリ、サーバー関数、ファイルストレージ
• reference/comparison.md - 機能マトリクス、料金、移行ガイド

---

相性の良い組み合わせ

• バックエンドアーキテクチャパターンには moai-domain-backend
• フロントエンド統合には moai-domain-frontend
• TypeScript のベストプラクティスには .claude/rules/moai/languages/typescript.md (paths frontmatter により自動読み込み)
• Railway での Python デプロイには .claude/rules/moai/languages/python.md (paths frontmatter により自動読み込み)
• 認証統合には moai-platform-auth
• データベースパターンには moai-platform-database

---

Status: Production Ready Version: 2.0.0 Updated: 2026-02-09 Platforms: Vercel, Railway, Convex

よくある正当化

正当化	現実
「開発が完了してからデプロイプラットフォームを構成します」	デプロイ構成はビルド出力、環境変数、実行時の動作に影響します。早い段階で構成してください。
「プレビューデプロイは任意です」	プレビューデプロイは本番前にデプロイ固有のバグを検出します。コストはわずかで、多くのものを節約できます。
「環境変数はすべての環境で同じです」	本番、ステージング、開発では異なるデータベース URL、API キー、フィーチャーフラグが必要です。1 組の環境変数はセキュリティリスクです。
「サーバーレスのコールドスタートは無視できる程度です」	コールドスタートは最初のリクエストに 200～2000ms のレイテンシを追加します。ユーザー向け API では、これは重要です。測定して軽減してください。
「ロールバック戦略は必要ありません。再デプロイすればいいだけです」	再デプロイには数分かかります。ロールバックは数秒です。本番がダウンしているときは、数秒が重要です。

レッドフラグ

• 本番の環境変数がビルドログに表示される
• プルリクエストに対してプレビューデプロイが構成されていない
• ステージングと本番の両方で単一の環境が使用されている
• ロールバックの仕組みが文書化またはテストされていない
• ビルド成果物に開発依存関係やソースマップが含まれている

検証

• 環境変数が環境ごとに分離されている (dev、staging、production)
• プルリクエストに対してプレビューデプロイが構成されている (プラットフォーム構成を示す)
• ロールバック手順が文書化されテストされている (ロールバックコマンドまたはプロセスを示す)
• 本番ビルドに開発依存関係とソースマップが含まれていない
• クリーンな git チェックアウトからデプロイが成功する (ローカル状態への依存がない)
• サーバーレス関数のコールドスタート時間が測定されている (タイミングデータを示す)

リファクタリングノート

R4 監査判定 (2026-04-23): REFACTOR — トリプレットを Vercel のみのプライマリに縮小し、Railway/Convex はドキュメントのみとする SPEC: SPEC-V3R2-WF-001 §6.2 line 271 リファクタリング範囲 (将来のサブ SPEC に延期):

• Vercel を完全なガイダンスを備えたプライマリプラットフォームとして昇格させ、Railway と Convex をドキュメントのみの参照に格下げする
• Railway と Convex の詳細解説をレベル 3 モジュールに移動する
• CI/CD パイプラインパターンのセクションを追加する (GitHub Actions、Vercel CI 統合)

このスキルは v3.0 で維持されますが、その本体は後続の SPEC で再構築される予定です。