Move from another Deplo

Beta

Move a team from one Deplo to another, data included, without installing anything on the old one.

Beta

This feature is currently beta/experimental and subject to change. It is not recommended for production. Try it out and share your feedback on our GitHub.

A wizard reads one team from another Deplo and recreates it here, data included. The old Deplo hands everything over itself: nothing is installed on its machines, and the wizard goes from Connect straight to Review.

Use it to bring a team into a Deplo that already runs other teams. To copy a whole Deplo onto a fresh machine, use Move Deplo to another machine instead.

Before you start

Update both Deplos

The old Deplo needs 0.5.0 or newer, and both should run the same version. An older one says That Deplo is too old to hand itself over, or sends less and the report names what it left out. Update under Settings -> Deplo -> Updates.

Create a token on the old Deplo

In Settings -> API tokens, press New token:

  • Access: the team you are moving, as a whole. A token limited to projects or apps is refused.
  • Template: Root access. The minimum is Reveal secret values, Start & stop apps and Start & stop databases; without the rest, roles and member access (Manage members), git tokens, registry passwords and bucket keys stay behind and the report says so.
  • Expires: a short span, for example In 30 days.

A custom certificate's private key only travels when the token belongs to an instance admin.

This token can read every secret of the team

Every read writes Read this team, secrets included, to move it to another Deplo to the old Deplo's Activity. Revoke the token when the migration is done.

A token reads one team. For each extra team, create another and press Add. The new Deplo only needs the old one's panel address, for example https://deplo.example.com: no SSH, no agent port.

Run the migration

Open Settings -> System -> Migrations on the new Deplo, then Between Deplo -> Another Deplo to this Deplo -> Only some teams.

Connect. Enter the old Deplo's Panel address and paste the token. Add one token per team.

Review and start. Tick what comes over and pick where each app runs and is built. Every ticked service is stopped on the old Deplo when its data copy starts. Press Start migration; you can close the tab.

People, then Done. See Members below.

Point your domains here and deploy. Update each domain's DNS, open each app, check it, and press Deploy.

Keep the old one running

In Review, Advanced -> Keep everything running on the old Deplo makes a copy for testing or staging: nothing is stopped on the old Deplo, databases come over as a snapshot, files are copied while the apps keep writing, and crons, backups and deploy on push arrive switched off. You choose when to switch.

What lands as what

On the old DeploHere
Projects and environmentsThe same, with colour, kind and branch
Apps outside any projectThe same folder tree, or the top level
App from a git repositoryThe same repository, branch, watch paths and build settings, with its git connection
App from a Docker imageThe same image. One that is in no registry is copied from the old server
App from an uploaded archiveThe same archive
Compose stackThe same compose file, files and compose flags
DatabaseThe same engine, version, user and password, with its data
Volumes and the app's own filesCopied across
Variables, preview settings and preview variablesThe same values. A secret stays a secret
Shared variablesThe same level (team, project, environment), linked to the same apps
DomainsThe same hostnames, path, port, middlewares, CORS, security headers and www redirect
Basic auth, health check, resources, rollback countThe same
Published host portsThe same, with the publish-ports permission
Cron jobs, on apps and databasesEvery setting and variable
RegistriesOnce per team, with their passwords
Backup destinations and schedulesBuckets keep their restore points. A server-disk destination starts empty on a server here

What changes on the way

  • An address the old Deplo generated gets a new one. The app's Domains shows which became which.
  • Connection strings are rewritten to the database's new host. Values an app stored itself are not.
  • A second service name in one Environment is renamed: the second db becomes <app>-db.
  • The deploy hook gets a new address. Give it to whatever called the old one.
  • Pushes: where the git provider allows it, Deplo adds its own webhook. The old one still deploys on the old Deplo; remove it there.
  • Apps in folders the token's owner cannot open are left out. The report gives their count, never their names.

Members

  • With Manage members on the token: someone who already has an account here gets their role and access back. Someone who registers through a link joins able to view only, and the report says what they had.
  • Without it: everyone joins as a plain member.

Access to a single environment cannot be rebuilt yet; the report names those people.

What is left behind

  • API tokens and notification channels. Create them again here.
  • Restore points on a server's disk. They stay with the old Deplo; restore from there.
  • A GitHub App link. Link one under the app's Source settings before deploying.

Backing out

  • Stop and undo, in any step, removes everything the run created here with its data, and starts again what it stopped on the old Deplo.
  • A run that fails on its own is not rolled back. A service whose data did not arrive refuses to deploy until you copy the data again or press Deploy anyway.
  • Nothing on the old Deplo is deleted. Remove the team there yourself once the new one works.

Troubleshooting

SymptomWhat to check
That address is this DeploUse the old Deplo's address.
That is a Deplo. Paste one of its API tokensThe key is not a Deplo token. Create one on the old Deplo.
That Deplo refused the tokenIt expired, was revoked, or comes from another Deplo.
This token cannot stop what it would moveAdd Start & stop apps and Start & stop databases.
You don't have permission to reveal secret valuesAdd Reveal secret values to the token.
is limited to specific projects and can't access a team exportSet the token's Access to the whole team.
That Deplo is too old to hand itself overUpdate the old Deplo.
That Deplo is newer than this oneUpdate this Deplo.
could not reach the server this service runs onThat server is offline on the old Deplo. Bring it back, then copy the data again.
The https certificate is not one this machine trustsUse an address with a valid certificate.

More in Migrations.

Next steps

Did this page help you?

On this page