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:- 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. - Domains and redirects, from Project Settings, Domains, with the DNS record values you point at today.
- The git repository and branch the project deploys from. Confirm the latest commit is pushed, and keep
vercel.jsonandnext.config.js. - The cron list from the Cron Jobs tab, and the
CRON_SECRETvalue. - Storage. Dump each Vercel Postgres database, and export any KV or Blob content you need. Managed storage does not move with the app.
- Build settings from Project Settings, General: framework preset, build and output directory, install command, Node version and root directory.
- The id and URL of the last deployment you trust, for reference during rollback.
- 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 declaresARG NAME; addARG NEXT_PUBLIC_XandENV NEXT_PUBLIC_X=$NEXT_PUBLIC_Xbeforenext build. Explicitbuild.argswin. This also applies to push deploys.- The build log has a
build envline 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.productionstill works as a fallback. Changing a value needs a new build: a restart does not change the bundle.
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
-
Connect the git provider in the dashboard, then confirm it from the CLI with
git-providers. -
Create the app from git, as in Deploying apps, or commit an
app.yaml:Create it withapps 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--secrethere; the CLI refuses to create the app without it. Without a Dockerfile use--build-type railpack, and pass the same--build-typeto every laterapps builds trigger, which does not remember it.apps deploys wait <app>follows the build. Leave outdomains:for now, so nothing competes with Vercel for the real hostname. IfAPP_PUBLIC_HOSTis 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 runapps networkagain after one. -
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-secretsor--all-plainto override, orapps secrets set <app> --env-file secrets.envfor a secrets-only file. Copy from the Production column in Vercel, not Preview. SetNEXT_PUBLIC_*values here too, before the first deploy; see the build-time section above. Runapps apply <app>afterwards. -
Add a readiness path. Add a cheap route such as
/api/healththat does not depend on external services, and set it withhealth.readinessinapp.yamlorapps 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 checkapps status <app>after each deploy. - Deploy, then verify on the zero-config URL: pages, API routes, auth callbacks, image requests, and streaming responses.
- 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.
-
Recreate cron jobs as scheduled tasks, and run each once with
apps scheduled-tasks run. -
Enable previews with
apps previews enable <app>if you rely on PR preview URLs.
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:
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.
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
- 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.
- Add the real domains to the app, including
wwwif you redirect it:apps domains add <app> app.example.com www.example.com, ordomains:inapp.yamland 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. - 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.
- Test with a host override before changing DNS, for example
curl --resolve app.example.com:443:<server-ip> https://app.example.com/(add-kwhile the certificate is self-signed). Check the redirect the same way onwww.example.com. - Cut over. Change the A and AAAA records for the apex and
wwwfrom Vercel to the Levelrail server’s public IP. Do not remove the domain from Vercel until the shadow run is done. - Watch. Run
dig +short app.example.comfrom outside your network, then check the Metrics tab andapps logs <app>. - 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. - 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
wwwredirect, 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_statusandconsecutive_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).