Move from Dokploy

A wizard reads your Dokploy installation over its API and recreates it here: projects, apps, domains, variables, volumes and databases, with the data copied across. The configuration comes from the API. The data is read by a Deplo agent installed on each Dokploy machine.

Pick the tab that matches where Deplo will run: on the machine Dokploy already runs on, or on a machine of your own.

Before you startCopy Anchor Link

Create the API keyCopy Anchor Link

In Dokploy: Settings, Profile, API/CLI. Create the key from that dialog, not through Dokploy's API. A key created over the API has a limit of 10 requests a day, and an import needs hundreds. It would stop part-way with a 401 error. Raise or disable the limit in the same place.

One run per source organizationCopy Anchor Link

A Dokploy key only reads one organization. If your Dokploy has three, create a key for each. Paste the next one, press Add, and it joins the Teams to bring over list with the Deplo team it lands in. Two organizations may land in the same team, or each in its own.

Each organization is one run. The runs are queued on the server and done one after another, so you can close the page and come back later.

On every source machineCopy Anchor Link

• One shell command, as root, on each machine. It installs the Deplo agent that reads the disks. It works behind any firewall.
• Inbound TCP 9443 on each machine. Deplo connects back to read the volumes.
• A snapshot of every machine, taken first. It is the only way back.
• Free space on the destination disk. Deplo warns under 10% free or under 5 GiB.

What the run stopsCopy Anchor Link

Every service you tick is stopped on Dokploy when its data copy starts. After a finished run it is not started again. Anything you leave unticked is not touched.

Run the migrationCopy Anchor Link

curl -fsSL https://deplo.build/install.sh | bash

What comes acrossCopy Anchor Link

What lands as whatCopy Anchor Link

What changes on the wayCopy Anchor Link

• Temporary hostnames get a new address. A name on traefik.me, sslip.io, deplo.site or localhost contains the old server's IP, so Deplo generates a new deplo.site address. The app's Domains section shows which became which. Domains you own come across as they are.
• Connection strings are rewritten. A database answers as db-<name> here, and every variable that used the old hostname is updated. Values an app stores by itself (a saved trusted_domains or siteurl) are not changed. Fix them from the app's Console.
• A published host port comes across and needs the publish-ports permission. Without it the app still arrives, and the report names the ports it left behind. A port under 1024 cannot be published again; use a domain instead.
• A middleware label in a compose file comes across when its kind is supported. Router labels never do. See Middlewares in a compose file.
• Security headers stay off on a moved app's domains. The app answered without them before, so nothing that embeds it breaks. Turn them on under Security.
• A network you created yourself does not come across. Apps in the same Environment share one network, so put stacks that talk to each other in the same Environment.
• A service name already used by another stack is renamed. The second db in one Environment arrives as <app>-db, and its depends_on, variables and domain follow.
• A bind mount comes across with its contents, single files included. A bind that names a file copies that file alone, not the directory around it.
• A ${{project.KEY}} reference becomes a real link. A value that is exactly one reference to a project or environment variable of the same name arrives linked to that shared variable. When the names differ, the resolved value arrives instead and the report says so.
• Every variable arrives plain. Dokploy has no secret variables, and Deplo never guesses from the name, because a secret is write-only and cannot be read back. Mark what you want Secret under Variables afterwards.
• Imported basic-auth credentials are flagged. They never went through Deplo's password policy or the breach check.
• Anything that needs a permission you do not hold goes in the report, with who can turn it on. For security reasons host bind mounts, privileged, published ports and foreign networks or volumes each need their own permission.

What is left behindCopy Anchor Link

• LibSQL. There is no engine for it here.
• Deploy keys and connected-source credentials. Attach a git connection for a private repository.
• Private registry passwords. Dokploy never exposes them. Add the registry under Registries before you deploy.
• A compose file kept in a git repository. Dokploy does not return it over the API. The app is created and the report tells you to paste the file in.
• A Traefik middleware written into an app's own file. The report names it with its kind. Define it in the proxy's configuration here, then add it to the domain.
• The machine's own files. /etc/localtime, /etc/hosts, /etc/resolv.conf and similar belong to the host. The destination already has its own.

Backing outCopy Anchor Link

• While the run is going, in any step. Stop and undo removes everything the run created here with its data, starts again what it stopped on Dokploy, and removes the agent from the source. Dokploy keeps all of its data.
• A run that fails on its own during the data step. Nothing is rolled back. A service whose data did not arrive refuses to deploy. The agents stay, so the copy can run again.
• A takeover, before the ports move. Cancel and remove Deplo starts every service the migration stopped, starts Dokploy's own containers again, removes everything Deplo created here, and uninstalls Deplo. It asks for the API key again.
• A takeover, after the ports move. The snapshot is the only way back. If the port move itself fails, Deplo puts the ports back, starts Dokploy again and offers Try again with the reason.

Running the migration again is safe. What is already here is kept, and its data is copied again when you tick it.

TroubleshootingCopy Anchor Link

More in Servers and agents.

Next stepsCopy Anchor Link