Skip to Content
Task guides

Migrate from Railway or Vercel

Connect a platform, review its services and data, and import through Openship's normal deployment workflow.

View Markdown

Open New project → Import existing project and choose Railway or Vercel. Railway imports the complete selected environment into one Openship project containing its services. Importing another source project creates a separate project. Repository access, deployments, private service connections, data transfer and destination selection use the same workflows as other projects.

Connect the source

An organization administrator can add a connection in the import flow or in Settings → Connections. Choose an existing connection, authorize a provider account when OAuth is configured, or enter an API token. Tokens remain encrypted on the server.

Test & connect saves and verifies a new token connection. For a saved connection, use Test connection to check it again. The source step also checks project access and shows how many projects are available; an empty account and a failed access check are shown separately.

  • Railway: choose the token's account, workspace or project scope. Workspace tokens also require the workspace ID. Project tokens are limited to their project and environment.
  • Vercel: enter the team ID when using a team-scoped token. Choose the project and its production or preview environment. Openship reads the latest ready deployment in that environment.

Railway imports require permission to stop and deploy services, update their configuration, register a temporary SSH key and read the attached storage. A metadata-only token is insufficient.

Discover and review

Select the source project and environment. Railway keeps all services in the import so their writers, dependencies and storage move together. Name the destination project once. Open Configure to inspect each service's repository or image, service name, variables, storage and domains. Missing secrets open automatically. Private repositories also need GitHub access in Openship.

GitHub applications import the deployed commit. Automatic deployment on push stays off until you enable it. Image services use the normal registry pull flow; add a registry connection when an image is private. Openship pins the running image digest when Railway supplies it; otherwise review warns that the image tag may have changed. Custom Dockerfile paths, HTTP health checks and restart policies are preserved when they can be represented in Openship.

Exportable variables stay on the server. Railway sealed values and Vercel Secret/Sensitive values need to be entered again. Optional variables can be excluded. Railway private addresses resolve through service names on the project's private network, preserving the original protocol, credentials, database name and URL options. Unresolved provider references are shown as blockers instead of being silently copied.

Choose a destination using the normal server picker. Its permissions, subscription and capacity checks still apply. Choose Check import to check the configuration before deployment. Blocked services stay in the editor with the issue shown. A successful check opens a separate review listing the import's data choices. Changing a selection or destination requires a new check.

Choose what happens to data

  • Railway persistent volumes: Openship stops the complete source project, temporarily runs export-only containers on its existing mounts, and streams every selected volume into new destination volumes. Databases, queues, SQLite and arbitrary file stores use the same copy path. Files, database directories, persisted accounts, ownership, permissions and symlinks travel together. All volumes finish copying before any destination application starts. Existing destination data is never overwritten. This requires compatible application images and storage formats; it is not a database version upgrade or a copy of ephemeral container files.
  • External PostgreSQL: keep the existing connection, or copy its configured database. Copying requires its major version and a direct public connection URL with TLS. After entering a missing PostgreSQL URL, review adds the database to the same selection list.
  • Empty storage: explicitly starts the destination without copying source data.

Allow downtime for the Railway project and pause external deployment automation or jobs that could restart or modify it. Openship stops the selected environment's services automatically. It restores their original configuration after copying and leaves them stopped for cutover. For an external PostgreSQL copy, pause writers yourself and keep them paused through cutover.

Review platform-specific dependencies

This is not an export of every provider feature. Vercel Blob, Edge Config, provider-specific functions and external storage other than supported PostgreSQL copies need separate handling. Cron services, multiple replicas, Railway pre-deploy commands, multiple public ports, non-GitHub repositories, unsupported build settings and unresolved connections block review. Source-built services must share one repository and deployed revision; project-wide release commands require review. Sleeping services run continuously after import. Dependency cycles require review; variables containing several private service addresses are preserved with their new service names. External PostgreSQL logical copies do not include other databases or server-wide roles; a Railway volume copy preserves the whole persisted directory.

Import, verify and finish

Start the reviewed import. The configuration is checked again, one destination project and its services are created, and the source lifecycle and storage copy are recorded in a recovery checkpoint. The saved migration page shows progress, deployment logs and a link to the imported project and survives a browser refresh. Dependencies deploy before their consumers, and imported containers must pass runtime verification.

Move domains and traffic

Importing does not change DNS or move public traffic. Domains & DNS in the review and saved migration page lists each discovered hostname alongside its service and the required action:

  • Update DNS: a custom domain you can keep, such as app.example.com.
  • Replace URL: a provider-owned address, such as my-app.up.railway.app or my-app.vercel.app. These addresses cannot be transferred to OpenShip. Choose a new address and update application URLs, OAuth callback URLs, webhook destinations and other clients that use the old address.

After the import reaches Verify apps and move traffic:

  1. Choose Review domains & DNS to open the imported project's Domains & Routes. Custom domains and aliases are already assigned to their matching services using the same routing flow as server/Docker migration. They start unverified; importing never marks them verified on your behalf. Add a test domain if needed and verify the app and its copied data.
  2. Open the DNS settings for each imported custom domain. OpenShip shows the exact DNS records for that destination, including any ownership verification records. Apply those records at your DNS provider, replacing the old routing records for that hostname. Keep unrelated records, including email records. If you have a supported DNS connection, you can review and apply the changes through Auto-configure DNS in the same flow.
  3. Use OpenShip's domain verification, wait for DNS propagation and HTTPS readiness, and test the public URLs. Only then choose Confirm cutover complete on the migration page.

The destination can be OpenShip Cloud or your server; use the records shown for that destination instead of copying the old Railway or Vercel target. See the custom-domain guide for DNS setup and verification. Keep databases and other internal services private unless they explicitly need public access. Confirmation records your review; it does not change DNS or automatically prove that traffic has moved.

Source services, domains and data remain at the provider. Retire them there after verification. A failed Railway import retains copied data and configuration, stops the destination workloads started by that import, then restores the original source deployments. Process-restart recovery uses the same checkpoint. Operator changes or an unreachable destination can require manual review before the source resumes. Temporary SSH grants are revoked after completion or recovery. Review retained destination projects before retrying; partial volumes are not overwritten.

Configure OAuth on your installation

API tokens work without a registered OAuth application. To offer account authorization, configure these variables on the Openship API server:

ProviderVariables
RailwayOPENSHIP_CONNECTION_RAILWAY_CLIENT_ID, OPENSHIP_CONNECTION_RAILWAY_CLIENT_SECRET
VercelOPENSHIP_CONNECTION_VERCEL_CLIENT_ID, OPENSHIP_CONNECTION_VERCEL_CLIENT_SECRET, OPENSHIP_CONNECTION_VERCEL_INTEGRATION_SLUG

Register the exact callback <canonical-dashboard-url>/connections/callback. For Vercel, use an API integration with an external installation flow and access to projects, deployments, domains and environment variables. For Railway, use an OAuth application supporting Authorization Code with PKCE and the requested workspace scope. Keep client secrets out of public dashboard variables.

Help improve this page Edit on GitHubReport an issue

On this page