Skip to main content
Vercel
This is a runbook for moving one Vercel-hosted Next.js app onto a Levelrail instance you run yourself. It maps only to features that exist in this repository today. Where something is unverified or has no equivalent, it says so.
Some areas are still beta (see feature status), and real public ACME has one recorded live run but no renewal or wildcard verification yet (see the ACME verification runbook). Run the new deployment in parallel with Vercel, and keep Vercel as the rollback path until the shadow run in section 6 is clean.
Two helpers exist. levelrail-cli import platform vercel --dry-run is the platform importer described in Migrate to Levelrail. It reads projects, env var keys, plain env values and domains through the Vercel API, read-only, and prints what it would create. Drop --dry-run to create the apps. Databases and volumes are created empty, and encrypted or sensitive values come back as names only. Pending run against a real Vercel account. levelrail-cli import config is the offline path: it reads vercel.json (and a Procfile or app.json if present) from a directory and prints a proposed app.yaml plus findings for what has no equivalent, each with a fix. It needs no token and changes nothing. Review the output of either helper before using it. Everything else below is manual.

1. Inventory what Vercel holds

Collect this before touching Levelrail. Vercel keeps configuration in its dashboard that is not in your repo.

Export checklist before a plan change or shutdown

This page does not state Vercel plan terms or dates. Check Vercel’s current terms for your plan. Export these while the project still answers, and keep the files out of git:
  1. Env vars for each Vercel environment. Pull Production with the steps in Environment variables from vercel env pull, and record the Preview and Development key names.
  2. Domains and redirects, from Project Settings, Domains, with the DNS record values you point at today.
  3. The git repository and branch the project deploys from. Confirm the latest commit is pushed, and keep vercel.json and next.config.js.
  4. The cron list from the Cron Jobs tab, and the CRON_SECRET value.
  5. Storage. Dump each Vercel Postgres database, and export any KV or Blob content you need. Managed storage does not move with the app.
  6. Build settings from Project Settings, General: framework preset, build and output directory, install command, Node version and root directory.
  7. The id and URL of the last deployment you trust, for reference during rollback.
  8. Third-party webhooks and OAuth callback URLs that point at the Vercel domain. You update each one at its provider.

2. Map Vercel concepts to Levelrail

Build-time versus runtime env

NEXT_PUBLIC_* values are compiled into the JavaScript bundle during next build, so they must exist before the first deploy. Levelrail passes every literal, non-secret app env var whose name starts with a public prefix (NEXT_PUBLIC_, VITE_, PUBLIC_, REACT_APP_, NUXT_PUBLIC_, GATSBY_, EXPO_PUBLIC_) to the build:
  • build.type: railpack: set the values as plain app env (apps env import), then deploy. Nothing needs to be committed. Secrets, references and vault values are never passed to a build.
  • build.type: dockerfile: the same values are passed as build args when the Dockerfile declares ARG NAME; add ARG NEXT_PUBLIC_X and ENV NEXT_PUBLIC_X=$NEXT_PUBLIC_X before next build. Explicit build.args win. This also applies to push deploys.
  • The build log has a build env line listing the key names passed (never values). If a variable is missing from the bundle, check that line first, then that the name has a public prefix and is not marked secret.
  • A committed .env.production still works as a fallback. Changing a value needs a new build: a restart does not change the bundle.
Railpack starts the app with npm run start, so next start serves it. With output: "standalone" Next.js logs a warning that next start does not use the standalone output; the app still serves normally. The standalone output only matters for your own Dockerfile. import config reads next.config.* as text (it never runs it) and suggests output: "standalone" only when the file does not already set it.

Environment variables from vercel env pull

The Vercel CLI writes one environment to a dotenv file. Levelrail keeps one env set per app, so pull Production only. Pending run against a real Vercel project.
The dotenv file holds plaintext values. Delete it after the import and do not commit it. Server-only variables are set as normal app env or secrets and read when the container is created. Changing them shows an “Environment changes pending restart” banner until you apply them (apps apply <app>).

3. Procedure

  1. Connect the git provider in the dashboard, then confirm it from the CLI with git-providers.
  2. Create the app from git, as in Deploying apps, or commit an app.yaml:
    Create it with apps create --file app.yaml --repo URL --ref main --image-repo NAME --secret DATABASE_URL=.... The first build starts as soon as the app exists, so a { secret: true, required: true } variable must be given with --secret here; the CLI refuses to create the app without it. Without a Dockerfile use --build-type railpack, and pass the same --build-type to every later apps builds trigger, which does not remember it. apps deploys wait <app> follows the build. Leave out domains: for now, so nothing competes with Vercel for the real hostname. If APP_PUBLIC_HOST is set to a public IP, apps network <app> shows a zero-config sslip.io URL to test on. The host port behind it changes on every restart, so run apps network again after one.
  3. Load env vars with apps env import <app> --file prod.env --dry-run, then again without --dry-run. Keys that look sensitive go to the secret store and the rest to plain env, and the output lists key names only. Use --all-secrets or --all-plain to override, or apps secrets set <app> --env-file secrets.env for a secrets-only file. Copy from the Production column in Vercel, not Preview. Set NEXT_PUBLIC_* values here too, before the first deploy; see the build-time section above. Run apps apply <app> afterwards.
  4. Add a readiness path. Add a cheap route such as /api/health that does not depend on external services, and set it with health.readiness in app.yaml or apps health set <app> --probe readiness --path /api/health. A deploy that fails readiness does not take over traffic: the ingress keeps routing to the previous release and the attempt is recorded as failed. Still check apps status <app> after each deploy.
  5. Deploy, then verify on the zero-config URL: pages, API routes, auth callbacks, image requests, and streaming responses.
  6. Move data if the app uses Vercel Postgres or KV: create a managed database here, restore a dump into it, and rehearse the restore before cutover.
  7. Recreate cron jobs as scheduled tasks, and run each once with apps scheduled-tasks run.
  8. Enable previews with apps previews enable <app> if you rely on PR preview URLs.
To review the move in a pull request instead of creating things directly, run levelrail-cli import platform vercel --emit stack --out DIR (or import config --emit stack --out DIR on a checkout with a vercel.json). It writes App, Database and Domain documents plus a SECRETS.md of env variable names (never values) and a MIGRATION.md for cron jobs, rewrites and anything else the documents cannot hold. See Stacks and GitOps.

Cron recipe with a bearer header

levelrail-cli import config turns a vercel.json cron such as this one into a scheduled task:
The task calls the route over loopback on the app port and sends Authorization: Bearer $CRON_SECRET when CRON_SECRET is set in the container. The variable is read at run time, so the secret never appears in the job definition. The task tries curl, then wget, then node, and fails with exit code 127 if none exists in the image. To write the same task by hand, set CRON_SECRET as an app secret, then create the task. The single quotes keep $CRON_SECRET unexpanded on the host. Pending run.
Replace 3000 with the port the app listens on, and /api/cron/daily with your route. Check the task with apps scheduled-tasks list my-site after the first run.

4. What has no equivalent

Plan for these before you commit to moving.

5. DNS cutover and rollback plan

  1. Lower TTLs first. At least one full old-TTL period before cutover (often 24 hours), set the TTL on the relevant A, AAAA, and CNAME records to 60 to 300 seconds.
  2. Add the real domains to the app, including www if you redirect it: apps domains add <app> app.example.com www.example.com, or domains: in app.yaml and a redeploy. Then set the redirect, domains redirect set <app> www.example.com --target https://app.example.com. Check certificate state on the Domains tab.
  3. Get a certificate ready before traffic arrives. With ACME enabled, issuance needs the domain to already point at the server, so expect a short window. To avoid it, upload a bring-your-own certificate for the domain first, or rehearse ACME on a spare hostname using the runbook.
  4. Test with a host override before changing DNS, for example curl --resolve app.example.com:443:<server-ip> https://app.example.com/ (add -k while the certificate is self-signed). Check the redirect the same way on www.example.com.
  5. Cut over. Change the A and AAAA records for the apex and www from Vercel to the Levelrail server’s public IP. Do not remove the domain from Vercel until the shadow run is done.
  6. Watch. Run dig +short app.example.com from outside your network, then check the Metrics tab and apps logs <app>.
  7. Rollback plan. Write down the old record values before changing them, and keep the Vercel project and its domain configuration untouched. To roll back, restore the old records. With the low TTL, most clients return within minutes. A bad Levelrail release is a separate case: use apps deploys rollback-to <app> <deploy-id> or the dashboard button.
  8. Raise TTLs again only after the shadow run is clean.

6. Shadow-run checklist

Run both platforms side by side long enough for boring problems to appear. Suggested minimum: one full business cycle, including any weekly or monthly cron.
  • Readiness probe passes, and a deliberately broken deploy is rejected while the old container keeps serving.
  • Plain http:// links to your domain redirect to HTTPS (the ingress does this when it can bind port 80, see Domains and ingress).
  • The www redirect, basic auth, WAF, and uploaded certificates are still set after an env change and a redeploy.
  • A rollback to the previous image works, from both the CLI and the dashboard.
  • Every env var key present in Vercel Production exists here.
  • Build-time NEXT_PUBLIC_* values are correct in the deployed bundle.
  • Auth flows work: OAuth callback URLs updated at each provider, cookies set for the right domain.
  • Third-party webhooks (payments and similar) point at the new URL, and a test event succeeds.
  • Each scheduled task ran on schedule (check last_run_status and consecutive_failures).
  • The certificate was issued and is not stuck in renewal, and certificate expiry alerting is configured.
  • Alert rules and a notification channel exist for crashloops, disk space, and certificate expiry.
  • A database backup ran, and a restore was actually rehearsed.
  • Image optimization, ISR, and file uploads behave acceptably under real traffic.
  • Response time and error rate compare acceptably against Vercel, using the app’s request metrics.
  • Preview environments open, update, and tear down on a test pull request.
  • A control plane backup exists (see Control plane backup).
Decommission Vercel only after this passes and you have decided what to do about each gap in section 4.

See also

Last modified on November 2, 2026