Skip to main content
If you run a plain compose stack on a VM, there are two routes. Import the compose file to get one app per service and managed databases for the database images, or deploy the whole file as one compose app. Read the migration overview first for the flow and the downtime table.

​
Prerequisites

  • Levelrail installed on the new server and the CLI signed in (levelrail-cli auth login).
  • The compose file, and for volumes and databases, shell access to the host that runs it.

​
Pick a route

​
What imports automatically (import the file)

​
What needs a manual step

  • Services with only a build: block are unsupported. Build and push an image, or create the app from its git repository.
  • Database and volume contents, by the copy steps below.
  • Networks, depends_on, restart policy and command overrides are not mapped. Set what matters on each app.
  • Hostnames between services. Apps reach managed databases by connection variable, not by the compose service name. Rewrite them with the mapping table in the plan.

​
What cannot be migrated

  • Services without an image (build only).
  • The compose network model: services do not share one bridge network by default.
  • Anything the file does not say: running data, certificates and host proxy config.

​
Steps

1

Plan

Dashboard: Settings, Import from another platform, the Compose file tab. The content stays in memory for the session and secret values stay masked.
2

Stage

Apps are created stopped and not routed, and the session id is printed. Add --only NAME for a subset.
3

Copy database data

The compose database must publish its port to the new server (restrict it by firewall), or run the dump yourself and use the restore tools.
4

Copy volumes

Run the printed rsync commands as root on the node that hosts the app.
5

Verify and switch

Roll back with levelrail-cli import cutover rollback --session ID --app NAME.

​
Databases and the downtime window

Full dump and restore with row counts compared, repeatable, source read-only. No incremental sync. Stop the writers (docker compose stop web), run the final copy, start the app here, switch DNS. The window is the final copy time plus a restart. Stateless services with no volumes need no pause. See the downtime table.

​
Domains and TLS

A plain compose stack usually sits behind your own reverse proxy. Point DNS at the new server or install Levelrail in coexist mode. Lower the TTL to 300 seconds a day ahead and run levelrail-cli migrate cutover for a go or no-go per domain. See Domains and ingress.

​
Common problems and fixes

​
Choose to stay if

One VM and one compose file already do the job, and you do not need TLS automation, backups or rollback beyond what you built. A compose file is a fine deployment. Move when you want those things managed. See the comparison.
Last modified on October 20, 2026