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 over the API; the data is read by a Deplo agent installed on each Dokploy machine and relayed through the control plane. Pick the tab that matches where Deplo is going: onto the machine Dokploy already runs on, or onto a machine of your own.

Before you start

Mint the API key

In Dokploy: Settings, Profile, API/CLI. Mint it from that dialog rather than through Dokploy's API - a key created over the API without rate-limit settings is born at 10 requests a day, and an import reads the panel hundreds of times. It stops part-way, and Dokploy answers 401 for it exactly as it would for a wrong key. Raise or disable the limit in the same place.

One run per source organization

A Dokploy key is minted for one organization and reads only that one. If your Dokploy has three, mint a key 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.

A single walk of the wizard is one run per organization, queued by the control plane and taken one after another. The list belongs to the server, not to the browser tab: close the page, reload it, come back tomorrow.

On every source machine

• One shell command, as root, on each machine behind the panel. It installs the Deplo agent, which is what reads the disks. Installing is outbound, so it works behind any firewall.
• Inbound TCP 9443 on each of them. Reading a volume is Deplo dialing that machine back, which its call home never does. A machine that went green can still be out of reach.
• A snapshot of every machine, taken first. It is one click at every provider, and it covers what nothing in the wizard can put back.
• Room on the destination disk. A copy writes a second copy of everything before the old one goes. Deplo warns under 10% free or under 5 GiB.

What the run stops

Every service you tick is stopped on Dokploy when its data copy starts, and on a run that finishes it is never started again. That stop is the cutover. What you leave unticked is not touched at all.

Run the migration

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

What comes across

What lands as what

What changes on the way

• Throwaway hostnames are re-hosted. A name on traefik.me, sslip.io, nip.io or localhost has the old server's IP baked into it, so Deplo mints a generated nip.io address with the same route and the app's Domains section says which became which. Real domains you own come across as they are, and you repoint DNS when you are ready. In a takeover the app lands on the same machine, so the generated name keeps working and stays as it is.
• Connection strings are rewritten. A database keeps its data but not its hostname - it answers as db-<name> here - and every variable that named the old one is updated. What Deplo cannot reach is what an app stores about itself: a saved trusted_domains or siteurl still holds the old address, and the report tells you to fix it 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 republished; a domain is usually the answer.
• A network you created yourself does not come across. It exists only on that machine, and left in place the stack would not start here at all. An Environment owns one network and every app in it shares that one, so two stacks that talked over a network of your own keep talking as long as they land in the same Environment.
• A service name another stack already answers to is renamed. Two stacks in one Environment both calling their database db cannot both have the name; the second arrives as <app>-db, and its depends_on, its variables and its domain follow.
• A bind comes across with what is in it, a single file included. A bind that names a file rather than a directory copies that file alone, never 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, not as a second copy. When the names differ a link cannot express it, so the resolved value arrives instead and the report says so.
• Every variable arrives plain. Dokploy has no notion of a secret variable, and Deplo never types one on its own: a secret is write-only and cannot be turned back, so guessing from the name would lock away a value nobody can check. 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 needing a permission you do not hold lands in the report instead, naming what asked for it and who turns it on. Authored compose is treated as hostile here exactly as it is everywhere else: host bind mounts, privileged, published ports and foreign networks or volumes each need their grant.

What is left behind

• LibSQL. There is no engine for it here, and Dokploy cannot even stop one for a copy.
• Deploy keys and connected-source credentials. A public repository clones here with nothing; attach a git connection for a private one.
• Private registry passwords. Dokploy never exposes them. Add the registry under Registries before the deploy fails on it.
• A compose file kept in a git repository. Dokploy will not resolve it over the API, so the app is created and the report tells you to paste the file in.
• A Traefik middleware written into an app's own file. Dokploy's forms never produce one. 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 the like belong to the host. The destination already has its own.

Backing out

Before the data step. Stop and undo removes everything the run created here and takes the agent back off the source. Dokploy keeps all of its data.

During or after the data step. Nothing is rolled back. Everything already created here stays as it is, every service whose data did not arrive is marked and refuses to deploy, and what this run stopped on Dokploy is started again. The agents stay where they are 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 with the restart policy each had, removes everything Deplo created here with its volumes and networks, and uninstalls Deplo. It asks for the API key again, because the run's own copy is wiped when the run ends.

A takeover, after the ports move. The snapshot is the only way back. If the port move itself fails, the unit puts the ports back and starts Dokploy again on its own, and the step offers Try again with the reason - usually a container of yours that grabbed 80 while the proxy was down.

Running the whole thing again is safe: everything already here is kept, its data is copied across again when you tick it, and Install shows the line to paste once more.

Troubleshooting

More in Servers and agents.

Next steps