migrate-to-railcode

Railcode への移行

移行は書き換えではなく移植です。プロジェクトはすでにどこかで動作しており、目的はユーザー向けの機能を維持しながら、以前のホストが提供していたもの（認証、データベース、環境変数、cron、ファイルストレージ）を Railcode が提供するものに置き換えることです。

ほとんどの社内ツールは移行できます。通常、直接対応するものがない要素は1つか2つですが、そのほぼすべては、ユーザーには気づかれない別の方法で再構築できます。詳しくは別の方法を見つけるをご覧ください。現時点でホストできないものは、短いリストにまとめています。詳しくはRailcode では現時点でホストできないものをご覧ください。何かを約束する前に、両方のリストを確認してください。

移行元プロジェクト別のガイド：

移行元プロジェクト	ガイド	ステータス
Next.js（App Router）	references/nextjs.md	"type": "next" としてサポートされ、@railcode/next によってビルドされます。実際のアプリで実証済みですが、ガイドに記載された制約があります
コンテナー：任意の言語でサーバーを実行する Dockerfile または docker-compose スタック	references/containers.md	プラットフォームの文書化された動作に基づいて手法とマッピングを作成していますが、記録された移行事例による裏付けはまだありません

それ以外の移行元の場合は、以下の方法に従い、create-railcode-app でアプリをビルドしてください。

Railcode 独自の db は、高速でシンプルな用途向けです。大量のデータや複雑なクエリには制限があります（結合、集計、トランザクションには非対応で、読み取りはページ単位です）。そのため、これらが必要なプロジェクトでは、既存のデータベースを維持してください。references/databases.mdでは、これらの制限、データソースとしてのデータベース接続、シークレットを使った直接接続、Railcode にコネクターがないデータベース、スキーマ移行の実行場所、railcode agent-feedback を通じてマネージド Postgres への関心を登録する方法について説明しています。

まず更新する

railcode コマンドを実行する前に、スキルと CLI を更新し、公開済みの内容を確認してください。

npx skills add Railcode-HQ/railcode-skills
npm install -g railcode@latest
railcode --version
npm view railcode version

npm に接続できない場合はその旨を伝え、このガイダンスが最新だと主張しないでください。このバージョンは、CLI 0.3.8、@railcode/sdk 0.4.0、@railcode/next 0.1.0 に基づいて作成されています。

このスキルでは、SDK、マニフェスト、デプロイの手順を再説明しません。それらは create-railcode-app（references/worker-sdk.md、references/cli-workflow.md、references/deployment.md、references/app-patterns.md）に記載されています。以下の手順で SDK の機能に言及している箇所では、該当する内容を読んでください。

別のホストから移行する人向けの Railcode の概要

すべての移行の前提となる4つの事実があります。まず、プロジェクトがこれらに適合するか確認してください。

• 閲覧者は全員、組織にサインイン済みのメンバーです。 匿名の訪問者も、セルフサインアップもありません。Railcode は社内ツールをホストします。
• バックエンドは Workers ランタイム（nodejs_compat）上の単一のワーカーモジュールであり、Node サーバーでもコンテナーでもありません。 リクエストごとに一度実行され、リクエスト間でメモリ上の状態を保持しません。ファイルシステム、子プロセス、ネイティブアドオン、raw TCP は利用できません。
• ワーカーが実行されるのは、サインイン済みメンバーのブラウザーから呼び出されたときか、アプリ独自の cron による場合だけです。 パブリックインターネット上からワーカーを呼び出すことはできません。
• 認証は暗黙的に行われます。 アプリのコードが実行される前にプラットフォームがユーザーをサインインさせ、検証済みの ctx.user をワーカーに渡します。プロジェクト独自のログイン機能は不要になり、通常、移行で最も大きく削除される部分です。

その代わりに、アプリでは設定不要で、サインイン、ストア（db）、ファイルストレージ（files）、LLM ゲートウェイ（llm）、メール送信、アプリごとのシークレット、cron、組織のデータベースおよび SaaS アカウントへのコネクター、マネージドエージェント、デプロイ履歴、ログを利用できます。

手順

以下の順序で進めてください。コードに触れる前に棚卸しを行ってください。移行に失敗するケースのほとんどは、先に UI を移植し、2日目になってデータレイヤーに相当するものがないと気づくためです。

1. 棚卸し

プロジェクトを読み、ファイルパスとともに以下を書き出します。

項目	確認する場所
認証	NextAuth/Auth.js、Clerk、Supabase auth、Passport、セッション Cookie、/login ルート
データ	ORM（Prisma、Drizzle、SQLAlchemy、ActiveRecord）、データベース URL、ホスト型 KV または Blob ストア
シークレットと設定	.env*、process.env.*、Dockerfile 内の ENV 行、旧ホストのダッシュボード
スケジュール処理とバックグラウンド処理	vercel.json の cron、キューとそのワーカー、サーバー内の setInterval、cron コンテナ
外部への呼び出し	サーバーコードが fetch するすべてのホスト
外部からの呼び出し	Webhook、公開 API ルート、OAuth コールバック、アプリ独自のフロントエンドから呼び出されないもの
ファイル	アップロード、生成ドキュメント、S3 クライアント、マウントされたボリューム
プロセスとバイナリ	docker-compose 内のすべてのサービス、すべての apt-get install、コードがシェルから呼び出すすべてのバイナリ
ホスト固有のパッケージ	@vercel/*、プラットフォーム SDK、エッジ専用 API

2. 各項目の対応付け

プロジェクトにあるもの	Railcode での対応
独自のログインとセッション	認証機構を削除します。ctx.user（id、email、name、is_admin、roles）を読み取ります。appUsers には組織のメンバーが一覧表示されます
ユーザーテーブル	アプリケーションデータにあたるもの（プロフィール、設定、アプリレベルのロール）は残し、db に移します。Railcode のユーザー ID は旧 ID とは異なるため、ユーザーをキーにしたデータをインポートする前にステップ 4 を確認してください
独自のデータベースにあるユーザーごとの行	db コレクションを使います。アプリごとにフラットなストアが 1 つあるため、ユーザー ID をキー（<userId>:<id>）に含め、サーバーコードでアクセスを制御します。小規模でシンプルなデータに適しています。大規模なテーブルや複雑なクエリには、データベースをそのまま使ってください
読み取り対象のデータベース（Postgres、BigQuery、Turso）	データソースとして接続します。組織の管理者が設定するデータコネクタを使います。読み取り専用です。 保存済みクエリ（query(name, params)）を優先してください。直接 SQL を実行する場合は data(name).runSQL(...) を使い、マニフェストに adhoc_sql: を設定します
読み取りと書き込みの両方を行うデータベース	そのまま維持して直接使います。接続認証情報を railcode secrets に設定し、ホストを egress: に記載して、HTTPS に対応したクライアントを使います（生の TCP は使えません）。または、アプリ独自のテーブルを db に移します。references/databases.md を参照してください
Railcode にコネクタがないデータベース（MySQL、MongoDB、DynamoDB、Redis など）	同様に、認証情報をシークレットとして設定し、ホストを許可して、従来どおり HTTPS API 経由で使います
スキーママイグレーション（Prisma、Drizzle、Alembic、Rails）	ビルドスクリプトまたはデプロイスクリプト内で、実行するマシン上で実行します。ワーカー内では実行しません。references/databases.md を参照してください
process.env.SECRET	railcode secrets set NAME で設定し、secrets.NAME として読み取ります
cron ジョブ	manifest.yaml の crons: に設定し、それぞれがアプリ独自のルートのいずれかを POST で呼び出します
外部への fetch	各ホストを egress: に記載します
ファイルのアップロード、マウントされたボリューム	files
LLM プロバイダーのキーとクライアント	llm を使い、マニフェストに llm: true を設定します
トランザクションメール	email を使い、マニフェストに email: true を設定します
独自の OAuth フローまたは API キーで呼び出す SaaS API	管理者またはユーザーが連携するコネクタを connector(name) で呼び出します。または、シークレットと egress: ホストを使います
キュー、WebSocket、Webhook 受信エンドポイント、ネイティブバイナリ、検索インデックス	直接対応するものはありません。別の方法を探すに進みます

直接対応するものがない項目については、移行前にユーザーへ伝えます。現在のプロジェクトで何をしているか、どのように再構築する提案なのか、ユーザーにどのような変更があるのか（たとえば「新しい支払いは即時ではなく、1 分以内に反映されます」）を説明し、項目ごとに同意を得てください。ユーザーが同意した別の実装は適切な移行ですが、後になってユーザーが気づくような近似的な代替策はバグです。

3. 移植

1. Railcode のファイル（railcode.json、manifest.yaml）を追加し、railcode dev で変更なしのページが表示されるようにします。
2. 認証を置き換えます。
3. データレイヤーをエンティティごとに置き換えます。
4. シークレット、cron、外部通信をマニフェストと railcode secrets に移します。
5. 別の方法を探すにある機能を再構築します。
6. 古いホストのパッケージと設定を削除します。

各手順で実行できる状態を保ってください。6つすべてを終えたときにしか動かない移行は、デバッグできません。

railcode dev では、db と files はローカルの一時ストレージを使いますが、SQL、コネクター、メール、llm、エージェントは実際のインスタンスに転送されます。メールを送信するルートをテストすると、実際にメールが送信されます。

4. 元のアプリと並行してデプロイする

新しいアプリのスラッグにデプロイし、元のアプリは稼働させたままにします。初回のデプロイで何かが破壊されることはなく、ユーザーは2つを比較できます。新しいアプリを確認してから、データを移行し、ユーザーを切り替えてください。

既存のデータは自動では移行されません。データが重要な場合は、旧ストアを読み取り、一時的な管理者専用ルート経由で書き込むスクリプト、または CLI の railcode app kv を使った、一度限りのインポートを作成して一度実行し、その後削除してください。

ユーザーが所有するレコードでは、所有者を対応付ける必要があります。旧アプリのユーザー ID は Railcode では意味を持たないため、行を旧 ID のままインポートするとアクセスできなくなります。まず対応付けを作成します。旧 ID → メールアドレス → そのメールアドレスを持つ Railcode メンバー（appUsers）の順に対応させます。一致しなかったユーザーを表示してからインポートし、各レコードを Railcode の ID で書き込みます。

5. 確認してから報告する

実際のユーザーとしてデプロイ済みアプリにアクセスし、移行した各機能を試してください。デプロイが成功しても、バンドルがアップロードされたことしかわかりません。railcode logs app --app <slug> ではすべての呼び出しが一覧表示され、railcode logs app <invocation-id> ではコンソール出力とエラーを確認できます。

次の順序で報告してください。動作する機能とその確認方法、異なる方法で再構築したものとユーザーへの変更点、対象外にしたものとその理由、ユーザーに残された作業（設定するシークレット、接続するコネクター、インポートするデータ）。

別の方法を探す

プロジェクトの一部に直接対応するものがない場合でも、そこで止めたり、その機能を取り除いたりしないでください。その機能が何で作られているかではなく、何のためにあるのかを考えてください。キューは、ユーザーを待たせずに時間のかかる処理を完了させるためにあります。Webhook は、支払いについてアプリに知らせるためにあります。WebSocket は、一覧を最新の状態に見せるためにあります。これらの目的は通常、cron、ストア、ポーリングを行うフロントエンドで実現できます。

利用できる構成要素は次のとおりです。

• 最短で1分おきに実行できる cron。 db、files、llm、email、secrets、外部通信、SQL、組織のコネクターを利用できます。
• キュー、キャッシュ、ロック、カーソルとして使えるストア。
• 必要な頻度でワーカーを呼び出せるフロントエンド。 ブラウザーのタブにはサブリクエストの予算がなく、開いたままにできるため、一度に1ステップずつ長時間の処理を進められます。
• 長時間かかる処理、コード実行を必要とする処理、AI でファイルを読み取る処理に対応したマネージドエージェント。
• 組織がすでに利用しているデータベースや SaaS アカウントへのコネクター。
• 宣言した任意のホストへのアウトバウンド HTTP。 ホスト型 API を使えば、ローカルバイナリで行っていた処理を実現できます。

実現できるパターンは次のとおりです。

プロジェクトの処理	次のように構築します	ユーザーにとっての変化
何かが起きたこと（支払い、新しい課題、フォームへの入力など）を知らせるウェブフックを受信します	cron でプロバイダーの一覧 API またはイベント API をポーリングします。最後に確認した ID またはタイムスタンプをカーソルとして db に保持し、処理を冪等にします	最大で 1 分の遅延が発生します
ジョブキュー（BullMQ、Celery、Sidekiq）を実行します	jobs コレクションを使います。ルートは status: "queued" を持つ行を挿入し、cron ルートは少量のバッチを取得して処理し、各行を完了としてマークします。cron の実行は少なくとも 1 回行われ、重複する可能性があるため、取得した行に ctx.invocationId を記録し、副作用が繰り返されても安全な状態にします	ジョブは即時ではなく、1 分以内に開始します
1 回のリクエストで長時間のタスク（大規模なインポートや数千行にわたるレポートなど）を実行します	db にカーソルを保持して、タスクをステップに分割します。フロントエンドはステップ用ルートをループで呼び出して進捗を表示するか、cron で処理を進めます。各ステップは約 100 件のサブリクエスト上限を大幅に下回るようにします	スピナーではなく、進捗バーが表示されます
WebSocket または SSE でリアルタイムの更新をプッシュします	タブが表示されている間だけ、数秒ごとに軽量なルートをフロントエンドからポーリングします。updated_at を返すことで、変更がない場合の応答をわずかなデータ量に抑えます	ポーリング間隔以内に更新が届きます
ブラウザーにテキストをストリーミングします	ストリーミングする Response を返します。SDK の toNdjson() がフレーミングを行います	変化はありません
独自のデータベースで SQL を使って結合やフィルタリングを行います	画面で行う読み取りに合わせてキーを設計し（<userId>:<id>、prefix()）、少量のデータを重複して保存し、query().where() でフィルタリングして、短いページが返るまでページネーションします。データを他のシステムと共有する場合は、そのデータベースに残し、データコネクター経由で読み取ります	キーが画面に合っていれば、変化はありません
リレーショナルデータベースへの書き込みが必要で、その形式を維持しなければなりません（トランザクション、制約、他のシステムからの読み取りなど）	データベースはそのまま維持し、シークレットと HTTPS ドライバーを使ってワーカーから直接利用します（references/databases.md）。データコネクターは読み取り専用なので、読み取りにのみ使用できます。データベースに HTTPS インターフェイスがない場合は、手前にインターフェイスを設置するか、古いホストに小規模な書き込みサービスを残します	HTTPS ドライバーがあれば、変化はありません
Redis またはプロセスメモリーにキャッシュします	expires_at フィールドを持つ db コレクションを使い、読み取り時に有効期限を確認します。インメモリーキャッシュはリクエスト間で保持されません	変化はありません
Redis でレート制限やロックを行います	キーごとに、カウンターとウィンドウの開始時刻を保持する db 行を使います。アトミックではないため、金銭に関わる用途ではなく、公平性を保つ用途に使用します	変化はありません
独自のレコードを対象に全文検索を行います	数千件程度なら、ワーカーまたはブラウザーに読み込んでフィルタリングします。それを超える場合は、コネクター経由でソースデータベースにクエリを発行するか、egress: 経由でホスト型検索 API を呼び出します	変化はありません
バイナリ（ffmpeg、ImageMagick、Chromium、pandoc）をシェルから実行します	まず、ワーカーのバンドルに収まる純粋な JavaScript ライブラリを探します。PDF やスプレッドシートの生成では、通常これで対応できます。それ以外の場合は、egress: 経由でホスト型 API を呼び出すか、コードを実行できるマネージドエージェントにジョブを引き渡します	結果が遅くなる、または非同期になる可能性があります
Google、Slack、GitHub などに対して独自の OAuth フローを実行します	コネクターを使います。管理者が組織アカウントを連携するか、各ユーザーが自分のアカウントを連携します。ワーカーは connector(name) を呼び出し、トークンを参照することはありません	アプリ内ではなく、Railcode でアカウントを一度連携します
メールを受信する、または実在する個人やチームのアドレスから送信する必要があります	そのアカウント用の Gmail コネクターを使います。組織所有のアカウントの場合は、保存したカーソルを使って cron でポーリングします。個人の受信トレイの場合は、個人用マネージドエージェントがスケジュールに従って読み取ります	受信メールに最大 1 分の遅延が発生します
llm ゲートウェイでは利用できない埋め込み、ビジョン、その他のモデル機能が必要です	プロバイダーを直接呼び出します。キーは secrets に、ホストは egress: に設定します	変化はありません
プッシュ通知またはチャット通知を送信します	email、またはチャンネルに投稿する Slack コネクターを使います	通知はメールまたは Slack に届きます
多数の内部ページの中に、公開ページが 1 つあります（公開フォームやステータスページなど）	分割します。公開ページは古いホストに残してそのデータベースに書き込み、Railcode アプリはデータコネクター経由でそのデータベースを読み取ります	デプロイが 1 つではなく 2 つになります
テンプレート（Jinja、ERB、EJS）を使ってサーバー側で HTML をレンダリングします	/api/* ルートから JSON を取得する静的フロントエンドを使います	変化はありません
docker-compose で複数のサービスを実行します	複数のルートグループを持つ 1 つのワーカーを使います。2 つの部分で対象ユーザーが異なる場合は、アプリを 2 つにします	変化はありません
うまく進めるためのルール：

• 何が変わるかを伝えます。 すべての行には、通常はレイテンシーに関するトレードオフがあります。一文で説明し、実装に取りかかる前に合意を得ます。
• 最もシンプルな仕組みを優先します。 フロントエンドでのポーリングは cron より優れており、cron はエージェントより優れています。
• cron を前提に設計する前に、制限を確認します：最短間隔は 1 分、アプリごとにスケジュールは 5 つまで、呼び出し元がなく（ctx.user は null）、管理対象のエージェント実行を開始したり読み取ったりできません。スケジュールが 5 つでは足りない場合、1 つの cron ルートで複数種類の作業を振り分けられます。
• 保証できないことを保証したように見せてはいけません。 元の処理がトランザクション、厳密に 1 回の配信、またはサードパーティへの即時応答に依存していた場合、ポーリング版ではそれらを提供できません。その点は次のセクションで扱います。

ユーザーがこの表にないものを必要としている場合は、基本要素を使って設計し、新しいパターンであることを伝え、追加できるよう報告してください（フィードバックを参照）。

Railcode が現在ホストできないもの

アプリにインターネットからアクセスする必要がある場合、プロセスを稼働し続ける必要がある場合、またはプラットフォームが提供していないランタイムが必要な場合は、回避策がありません。移植後ではなく、棚卸しの段階でこれらを見極めてください。

プロジェクトで必要なもの	適合しない理由
応答が必須のインバウンド Webhook — Slack のスラッシュコマンドやインタラクティブボタン、Twilio の音声または SMS への返信、確認応答を受け取るまで再試行し、ポーリング用 API を提供していないプロバイダー	組織外からワーカーを呼び出すことはできません。単に通知するだけの Webhook はポーリングに置き換えられます（上記参照）。アプリからの応答を必要とするものは置き換えられません
顧客、パートナー、モバイルアプリ、その他のサーバー向けの公開 API または公開エンドポイント	同じ理由です。リクエスト元は、サインイン済みメンバーのブラウザーまたは Railcode 自身のエージェントに限られ、外部システムからはアクセスできません
公開ページまたは顧客向けページ：マーケティングサイト、ストアフロント、セルフサインアップ、検索エンジン向けのコンテンツなど	閲覧者は全員、サインイン済みの組織メンバーです
独自の ID システム：組織メンバー以外のユーザーのログイン、サードパーティ向けの独自 API キーまたはトークンの発行	ID は組織のメンバーシップによって管理されます
真のリアルタイム処理：共同編集、プレゼンス、マルチプレイヤー、WebSocket サーバー	プッシュの仕組みはありません。ポーリングで実現できるのは「最新に見える」状態までで、「キーストロークごと」の更新ではありません
長時間稼働するプロセス：デーモン、ソケットを開いたままにするボット、ストリームコンシューマー（Kafka、Postgres の LISTEN）、1 分に 1 回より頻繁に実行する必要がある処理	ワーカーはリクエストごとに実行され、その後停止します
HTTP 以外のプロトコル：TCP 経由のデータベースドライバー（pg、mysql2、ioredis）、SMTP サーバー、gRPC	生の TCP での送受信はできません。データベースには、データコネクター（読み取り）またはシークレットを使う HTTPS ドライバー（読み取りと書き込み）経由でアクセスします。references/databases.mdを参照してください。ソケットインターフェイスしかなく、その前段に何もないデータベースにはアクセスできません
コンテナー自体：Python、Go、Ruby、Java、PHP サーバーのそのままの実行、システムパッケージ、ネイティブアドオン、GPU、ローカルモデル	バックエンドは 1 つの JavaScript モジュールです。他の言語はホストされるのではなく移植されます。コンテナーガイドを参照してください
大規模または複数ファイルからなるバックエンドバンドル：.wasm モジュール、サイズ上限を超えるワーカー（10 MB。worker_routes のないサーバーでは 5 MB）	ワーカーは単一の ESM モジュールです
カスタムドメイン、ネイティブモバイルアプリ、ブラウザープッシュ通知	アプリは <app>.<parent> にある Web アプリです
独自のメールドメイン：インバウンドメールサーバー、アプリが所有するアドレス、またはカスタム送信元からの email.send()	email はプラットフォームの送信元から送信する機能のみです。誰かが所有する Gmail アカウント経由のメール送信はサポートされています。別の方法を探すを参照してください

プロジェクトでこれらのいずれかが必要な場合：

1. すぐに、率直にユーザーへ伝えてください。 機能名を挙げ、現在の Railcode では実行できない理由を一文で説明してください。応答が必要な機能を、ポーリングで模倣したものが同等であるかのように提示してはいけません。

2. それでも可能なことを提案してください。 通常はプロジェクトの残りの部分を移行し、その機能だけを現在の場所に残して、Railcode がコネクター経由で読み取る共有データベースを使用します。欠けている機能がプロジェクトの中核（公開ストアフロント、Slack ボットなど）である場合は、当面プロジェクトを現在のホストに残すべきだと伝えてください。

3. CLI でリクエストを送信してください。 Railcode チームは、これらの報告を参考に次に開発する内容を決めます。プロジェクトの一部を移行した場合も含め、異なる機能が不足しているごとに 1 件送信してください。

   railcode agent-feedback --category suggestion \
     --message "Migration blocked on inbound webhooks. The project receives POST /webhooks/slack for slash commands and must reply within 3 seconds; there is no API to poll instead. Request: a way for an app to expose a public, signature-verified endpoint." \
     --context "Source: Express + Postgres in a container, about 40 routes. Everything else mapped to db, secrets and crons. The Slack routes stayed on the old host; the rest was migrated." \
     --agent "<your assistant name>" --model "<your model>"
   

   プロジェクトを見たことがない人にも必要性がわかるように記述してください。プロジェクトの概要（スタックとおおよその規模）、必要だった機能、代わりに行ったこと、移行を実施したかどうかを具体的に説明してください。認証情報、顧客データ、ソースコード、ユーザーの顧客を特定できる情報は含めないでください。このコマンドを実行するには、既存のログインが必要です。また、Feedback accepted. と表示されます。すべてのオプションは create-railcode-app の「Report Railcode feedback」にあります。失敗した場合は、報告が送信されなかったことをユーザーに伝え、そのまま作業を続けてください。

4. 送信したことと、その内容をユーザーに伝えてください。

プラットフォームに別の方法がすでにある機能については、リクエストを送信しないでください。まず 別の方法を探す と create-railcode-app を確認してください。

マシンの安全性

フレームワークのビルドは負荷が高く、移行ではその多くを実行します。

• ビルドまたは開発サーバーは一度に 1 つだけ実行し、作業を終える前に起動したすべてのプロセスを停止してください。思い込みで判断せず、ps で確認してください。
• package.json の build スクリプトでフレームワークのアダプターを呼び出すようにしてはいけません。そのアダプター自体が npm run build を実行する場合、ビルドが際限なく連鎖します。具体的なルールは Next.js ガイドを参照してください。
• ユーザーから依頼されない限り、仕組みを確認する目的でプロジェクトの docker-compose スタックを起動しないでください。コードを読んでください。

フィードバック

移行のたびに、具体的な問題点を railcode agent-feedback で報告してください（使い方は上記および create-railcode-app にあります）。問題点ごとに 1 件報告してください。元のプロジェクトで何を使っていたか、何に相当するものがなかったか、どのような再構築パターンを使ったか、ガイドの予測と異なって何が壊れたかを記載してください。機能の不足には --category suggestion を指定し、このスキルの手順が誤っている、または不明瞭な場合は --category friction を指定します。こうした報告が次のガイドの作成に役立ちます。