genesis-railway

genesis-railway

Railway MCP ツールを使用して、genesis モノレポを Railway にデプロイします。想定される構成は、services/<app>-server（Dockerfile と /health を備えた Go API）、services/<app>-web（nginx で配信される Dockerfile 付きの React アプリ）、および Postgres です。

Railway project: <app>
├── Postgres        # Railway Postgres template
├── <app>-server    # builds services/<app>-server/Dockerfile
└── <app>-web       # builds services/<app>-web/Dockerfile, gets the public domain
        web ──▶ server ──▶ Postgres   (private networking)

前提条件

Railway MCP サーバー（mcp__railway__* ツール）。利用できない場合は、作業を中止してユーザーに伝えてください。CLI コマンドを推測して代用してはいけません。

Railway CLI（npm i -g @railway/cli または brew install railway）。railway login、railway init、railway add、railway link、および解決済みの変数の読み取りにのみ使用します。

ルール

1. Railway の変更にはすべて MCP ツールを使用します。 設定、変数、ボリューム、ソース、ドメインには mcp__railway__* を使用します。CLI の用途は、ログイン、リンク、および railway add --database postgres のみです。

2. railway.json / railway.toml は追加しないでください。 Config-as-code は非推奨で、2026-12-01 に機能しなくなります。また、それらを書き込む MCP ツールもありません。ビルドとデプロイの設定はすべて、update-service（ステップ 3）を使ってサービスに設定します。後継の .railway/railway.ts（railway config pull/plan/apply、CLI ≥ 5）は対象外です。

3. 依存関係の順序に従ってサービスを作成します。 参照先のサービスが作成されるまで、${{Service.VAR}} の参照は空になります。Postgres、次に server、最後に web の順です。

4. 作成を始める前に、必須変数を確認します。 cmd/<app>/main.go を grep し、os.Exit を実行する設定チェックを探します。それぞれに変数が必要です。設定キーは、. を _ に置き換えて環境変数に対応させます（http.port → HTTP_PORT）。

5. Railway Postgres テンプレートを使用します。 ボリューム、Database タブ、バックアップ、DATABASE_URL / PG* 変数が付属しています。マイグレーションで CREATE EXTENSION vector を実行する場合に限り、代わりに pgvector/pgvector イメージのサービスを使用します（pgvector の例外を参照）。テンプレートのイメージにはこれが含まれていません。

6. 最初にプロジェクト ID と環境 ID を特定します。 リポジトリのルートがリンクされている場合は、~/.railway/config.json（.projects["<abs repo path>"].project）を読み取ります。それ以外の場合は、list-projects を使用するか、リポジトリのルートから railway init --name <app> を実行します。list-services を使って対象環境を特定し、設定と検証には明示的なプロジェクト ID、環境 ID、サービス ID を使用します。

手順

1. サービスを作成します — リンク済みリポジトリのルートから railway add --database postgres を実行します（リモート MCP にはテンプレートツールがなく、CLI はサービス名を Postgres にします）。続いて create-service で <app>-server、次に <app>-web を作成します（イメージは指定しません）。
2. skipDeploys: true を指定した set-variables で変数を設定します。
   • Server：PORT=8080、HTTP_PORT=${{PORT}}（両方とも設定します。server は HTTP_PORT を読み取るため、設定しないとヘルスチェックが誤ったポートを確認します）、DB_URL=${{Postgres.DATABASE_URL}}?sslmode=disable、LOG_LEVEL=info、およびルール 4 で見つかった変数を設定します（シークレットを生成し、ユーザーに報告してください）。
   • Web：BACKEND_URL=http://${{<app>-server.RAILWAY_PRIVATE_DOMAIN}}:8080
3. server と web に対して update-service で設定します。 rootDirectory: services/<app>-{server,web}、dockerfilePath: Dockerfile、watchPatterns: ["services/<app>-{server,web}/**"]（リポジトリルートからの相対パス）、restartPolicyType: ON_FAILURE、restartPolicyMaxRetries: 1 を設定します。Server にはさらに、healthcheckPath: /health、healthcheckTimeout: 60 を設定します（起動時のみ。増やす場合は理由を示してください）。
4. 読み戻し — get-service-config で両サービスの稼働中の config を取得し、ステップ 3 の設定と、list-variables による server の PORT=HTTP_PORT=8080 を確認します。値が非表示の場合は、シークレットを公開せずに railway variables --json --project <project-id> --environment <environment-id> --service <server-id> を使用します。不一致があれば修正して再確認し、検証できない場合は中止します。
5. ソース — ステップ 2〜4 の完了後、まず server、次に web に対して connect-service-source を実行します。repo: <owner>/<repo>、branch: main を指定します。これによりビルドと GitHub の自動デプロイが開始されます。レスポンスまたはスコープを絞った list-deployments から、トリガーされたデプロイ ID を記録します。ソースとトリガー時刻を照合し、特定できない場合は推測せず、その旨を報告します。
6. ドメイン — web に対して generate-domain を実行します。
7. サブディレクトリをリンクして、そのディレクトリ内から CLI を使用できるようにします（cd には絶対パスを使用します）。

   cd <abs>/services/<app>-server && railway link -p <app> -e production -s <app>-server
   cd <abs>/services/<app>-web    && railway link -p <app> -e production -s <app>-web
   

追加のインフラ

docker-compose.yml に Postgres 以外のインフラ（Redis、MinIO など）がある場合は、単なるイメージではなく、公式 Railway テンプレートからそれぞれ作成してください。変数を参照できるよう、サーバーより先に作成します。テンプレートがない場合に限り、image: を指定した create-service を使用します。

pgvector の例外

ステップ 1 の Postgres を置き換え、テンプレートで提供されるはずの設定を追加します。

• create-service で、image: pgvector/pgvector:<tag from docker-compose.yml> を指定して Postgres を作成します。
• set-variables（skipDeploys: true）：POSTGRES_DB=<app_underscore>、POSTGRES_USER=postgres、POSTGRES_PASSWORD=<openssl rand -hex 24>、PGDATA=/var/lib/postgresql/data/pgdata（ボリュームのルートが空ではありません）、PGHOST=${{RAILWAY_PRIVATE_DOMAIN}}、PGPORT=5432、PGUSER=${{POSTGRES_USER}}、PGPASSWORD=${{POSTGRES_PASSWORD}}、PGDATABASE=${{POSTGRES_DB}}（PG* の設定によってダッシュボードの Database タブが有効になります）、DATABASE_URL=postgres://${{POSTGRES_USER}}:${{POSTGRES_PASSWORD}}@${{RAILWAY_PRIVATE_DOMAIN}}:5432/${{POSTGRES_DB}}。
• Postgres に create-volume を実行し、mountPath: /var/lib/postgresql/data を設定します。
• ダッシュボードに Database タブはありません。テンプレートを使用した場合にのみ表示されます。

検証手順

1. 記録した各 ID について、対象を絞った list-deployments をポーリングし、SUCCESS になるまで確認します。別のデプロイに置き換えてはいけません。FAILED／CRASHED の場合は、types: ["build", "deploy"] を指定してそのデプロイの get-logs を取得し、原因を報告します。ブロックされた場合、またはポーリングが停止した場合は、ID、状態、次のアクションを未検証として報告します。environment-status で Postgres を確認します。
2. curl --fail --max-time 10 https://<web domain>/health が、期待されるバックエンドのヘルスレスポンスを返す必要があります。HTTP エラーや予期しない本文が返された場合、検証は失敗です。
3. プロキシで問題が発生した場合は、MCP または対象を絞った CLI を使って解決後の BACKEND_URL を確認します。http://:8080 の場合は、web を redeploy し、新しいデプロイ ID で検証を繰り返します。

よくある間違い

• PORT だけを設定する。 サーバーが読み取るのは HTTP_PORT です。設定しないと、ヘルスチェックが誤ったポートを確認し、すべてのデプロイが失敗します。
• pgvector イメージのサービスで PGDATA を省略する。 ボリュームのルートが空ではないため、サブディレクトリを指定しないと Postgres は初期化を拒否します。
• 変数や設定を行う前にソースを接続する。 最初のビルドがすぐに開始され、設定が不足した状態で実行されます。
• テンプレートが使えるのに、単なるイメージのサービスを使用する。 Database タブやバックアップを理由なく失うことになります。
• watchPatterns やサービス名にプレースホルダーの project-00 を使用する。 ${{project-00-server.RAILWAY_PRIVATE_DOMAIN}} のような参照は空に解決されます。