Migration and takeover

A migration reads a Dokploy or Coolify panel through its API and recreates what it finds here: environments, apps, compose stacks, databases, variables, domains, config files, volumes, limits, basic-auth users and crons. Nothing is deployed by an import, the source is still answering those hostnames.

The source's API key rides every call in MigrationSourceInput and is stored only for the length of a run started with startMigration. Everything is gated on create_projects and refused to a narrowed principal, since an import writes across the whole team.

Reading a source

identifyMigrationSource

Needs create_projects, or instance admin. Returns MigrationSourceTeam.

WHICH team a token reads, without reading it all. A token covers one team of the panel, so bringing several over takes one token each, and this is what lets the wizard collect them without paying for a full scan per token. Refuses a token that cannot read values, exactly as the scan does. Writes nothing.

mutation {
  identifyMigrationSource(
    input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }
  ) {
    platform
    teamName
    otherTeams
  }
}

scanMigrationSource

Needs create_projects, or instance admin. Returns MigrationPlan.

Read a source panel and describe what an import would do. Works out which product it is when kind is omitted. Writes NOTHING, here or there. The per-service detail calls happen now, not at import time, so the preview can already say which hostname belongs to another team, which compose file needs a grant you do not hold, and what has no equivalent here. Answers about the request's team, which needs create_projects there - or, with newTeam, about a team not made yet, which an instance admin may ask from any team of theirs.

mutation {
  scanMigrationSource(input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }) {
    platform
    orgName
    projects {
      name
      sourceId
      exists
      environments { name services { name kind status } }
    }
    servers { name ipAddress deploServerName }
  }
}

Running an import

startMigration hands the whole run to the control plane. The older per-project calls (beginMigration, importMigrationProject, finishMigration) drive the same import one step at a time.

startMigration

Needs create_projects. Returns String.

Start a migration and hand it to the control plane. Returns the run id as soon as the plan is DURABLE, not when the migration is done: the loop lives here now, under the identity of whoever started it, so the tab can be closed, reloaded or replaced and the run does not notice. The panel's token is stored encrypted for the length of the run and wiped the moment it leaves running - a deliberate reversal of never storing it, made because the alternative is a migration that cannot survive a page reload.

mutation {
  startMigration(
    input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }
    targets: [
      { projectId: "<project id from the scan>", projectName: "shop", serviceId: "<service id from the scan>", serverId: "srv_9f1c2ab7d3e4f5a6" }
    ]
  )
}

beginMigration

Needs create_projects. Returns String.

Open an import run and return its id. Any run this team left open (a closed tab) is closed as failed first, so the history never shows two live imports.

mutation {
  beginMigration(url: "https://panel.example.com")
}

importMigrationProject

Needs create_projects. Returns MigrationProjectResult.

Import ONE project from the source panel into the active team: its environments, apps, compose stacks, databases, variables, domains, config files, volumes, resource limits, basic-auth users and crons. Nothing is deployed - the source instance is still answering those hostnames. Anything already here is skipped by name, so running it again resumes an interrupted import instead of duplicating it. One object failing never stops the rest: it becomes a line in the report.

mutation {
  importMigrationProject(
    input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }
    runId: "run_9f1c2ab7d3e4f5a6"
    projectId: "<project id from the scan>"
    placements: [{ serviceId: "<service id from the scan>", serverId: "srv_9f1c2ab7d3e4f5a6" }]
  ) {
    projectName
    created
    skipped
    failed
    items { sourceName outcome message }
  }
}

importMigrationMembers

Instance admin only. Returns [MigrationInvite!].

Bring the source team's people over. Someone who already has a Deplo account is added to this team; everyone else gets a single-use registration link to send them. Passwords cannot travel in either direction, and everyone arrives as a plain member whatever they were over there - the report says who was an owner or admin so it can be granted on purpose.

mutation {
  importMigrationMembers(
    input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }
    runId: "brun_9f1c2ab7d3e4f5a6"
  ) {
    name
    email
    outcome
    link
  }
}

finishMigration

Needs create_projects. Returns Boolean.

Close the run and settle its totals. Idempotent - a finished run is left alone.

mutation {
  finishMigration(runId: "brun_9f1c2ab7d3e4f5a6")
}

stopMigration

Needs create_projects. Returns Boolean.

Close a run somebody stopped part-way, WITHOUT finishing it - the migration sources keep their agents, because re-running is how a stopped migration is resumed.

mutation {
  stopMigration(runId: "brun_9f1c2ab7d3e4f5a6")
}

abandonMigration

Needs create_projects, or instance admin. Returns Int.

Leaving the wizard behind: take Deplo's agent back off the machines it registered to read, exactly the way finishing does. No-op while a run is in flight (it owns those agents) and after one whose volume copy failed (the bytes are still over there). Returns how many sources it is removing.

mutation {
  abandonMigration
}

revertMigration

Needs create_projects. Returns MigrationRevertResult.

Remove everything this run CREATED in Deplo - apps, databases, and the projects it made. Anything it merely reused is left alone, and the source is not restarted. Each delete keeps its own capability gate, so what the actor may not remove comes back in failed.

mutation {
  revertMigration(runId: "brun_9f1c2ab7d3e4f5a6") {
    apps
    databases
    projects
    failed
  }
}

dismissMigrationReport

Needs create_projects. Returns Boolean.

"I am done looking at this run": the migration wizard stops opening on it and shows an empty connect form again. Pressing Finish on the report is what sends it.

mutation {
  dismissMigrationReport(runId: "brun_9f1c2ab7d3e4f5a6")
}

History

migrationRuns

Needs create_projects. Returns [MigrationRun!].

This team's import history, newest first. Without the per-run report - read one run for that.

query {
  migrationRuns {
    id
    status
    phase
    created
    failed
  }
}

migrationRun

Needs create_projects. Returns MigrationRun.

One import with its full report.

query {
  migrationRun(id: "brun_9f1c2ab7d3e4f5a6") {
    id
    status
    phase
    created
    failed
  }
}

activeMigration

Any signed-in principal. Returns MigrationRun.

Emits the migration this team currently has in flight - or, once it is done, the finished run until somebody closes its report - or null. Fires once immediately, then whenever a run starts, moves on or ends - it is what the header chip and the wizard's panel read. Deliberately NOT gated on create_projects: "somebody is moving a platform into this team right now" is a warning every member needs.

subscription {
  activeMigration {
    id
    status
    phase
    created
    failed
  }
}

Moving data

planMigrationDataMove

Needs create_projects. Returns [MigrationDataService!].

The services THIS RUN imported whose DATA can still be moved, with each volume paired to the Deplo one that would receive it (paired by container path, the only identity the two platforms share). Reads both sides and writes nothing. Scoped to the run because the copy WIPES its target before writing: what a service became is a fact the run recorded, never a name that happens to match.

mutation {
  planMigrationDataMove(
    input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }
    runId: "brun_9f1c2ab7d3e4f5a6"
  ) {
    sourceName
    targetName
    sourceReachable
    volumes {
      mountPath
    }
  }
}

moveMigrationServiceData

Needs create_projects. Returns MigrationDataMoveResult.

Cut ONE service's data over: STOP it on the panel (and leave it stopped - a volume read while its container writes cannot be trusted), then copy every paired volume into the app or database imported from it. A database is started again afterwards and checked, so the report says the engine reads the copied data rather than only that bytes moved. Additionally gated on restore_backups on the target, which is what overwriting a resource's data already requires. NEITHER side is taken from the caller: the volumes are derived from the service and the app, and the host the data is read from is derived from that machine's address - naming either would be an instruction to copy any volume on any host over any other one.

mutation {
  moveMigrationServiceData(
    input: { url: "https://dokploy.example.com", apiKey: "<source panel api key>" }
    runId: "run_9f1c2ab7d3e4f5a6"
    sourceKind: "postgres"
    sourceId: "<service id from the scan>"
  ) {
    moved
    failed
    notes
  }
}

dataRecopySource

Needs restore_backups. Returns MigrationRecopySource.

Where a workload whose data did not come across was imported from, so the copy can be run again from its own page. Null when nothing here came from a migration.

query {
  dataRecopySource(kind: "database", id: "db_9f1c2ab7d3e4f5a6") {
    platform
    sourceUrl
    sourceName
    runId
  }
}

deployWithoutMigratedData

Needs deploy_apps. Returns App.

Accept that the data a migration could not copy is not coming, and let this app deploy again: clears dataCopyError. The way out for an app whose source machine has since been turned off, which is how a migration normally ends. Recorded in Activity.

mutation {
  deployWithoutMigratedData(id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

startWithoutMigratedData

Needs control_databases. Returns Database.

Accept that the data a migration could not copy is not coming, and let this database start again: clears dataCopyError. The engine will initialise an EMPTY database on the volume, which is exactly what the refusal exists to stop - so this is a decision, not a retry. Recorded in Activity.

mutation {
  startWithoutMigratedData(id: "db_9f1c2ab7d3e4f5a6") {
    id
    name
    type
    version
    status
    host
    port
  }
}

Source machines

The agent an import needs on the source machine is registered as a migration source: addServer(input: { importOnly: true }) on Servers. These two point a run at where such a machine really is, and hand the machines to another team.

setMigrationMachineAddress

Instance admin only. Returns String.

Point Deplo at where a machine of this panel really is, and remember it for the next attempt. The address is PROVED first - the agent must answer there, over the same pinned certificate - and only then written down, because a remembered address is used automatically and an unproven one would turn a single bad guess into a permanent one. Returns a warning to surface, or null. The source server row is removed at the end of every migration, which is why this is remembered against the SOURCE rather than against that row.

mutation {
  setMigrationMachineAddress(
    url: "https://dokploy.example.com"
    sourceId: ""
    serverId: "srv_9f1c2ab7d3e4f5a6"
    address: "203.0.113.20"
  )
}

handOverMigrationSources

Needs create_projects. Returns Int.

Point a migration at another team: the machines Deplo installed its agent on to READ the panel are granted to the team it now lands in. Called right after switching, since every lookup that reads a source is team-scoped. Refused while a run is in flight in the team being left. Returns how many machines moved.

mutation {
  handOverMigrationSources(fromTeamId: "team_9f1c2ab7d3e4f5a6")
}

Takeover

A takeover runs after a migration finished on the same machine: the installer stops the other platform, inherits its certificates, moves the proxy onto 80/443 and removes the other platform. The installer's own endpoint is REST, see REST endpoints.

takeover

Instance admin only. Returns Takeover.

The takeover in progress, or null. The screen that replaces the dashboard reads its own state server-side; this is the poll behind the buttons, and only an instance admin has any.

query {
  takeover {
    state
    platform
    dataLoss
    error
  }
}

takeoverPreflight

Instance admin only. Returns TakeoverPreflight.

Null when this panel's own machine is not a server Deplo knows about, which is the one case where none of it can be measured.

query {
  takeoverPreflight {
    agentReady
    diskTight
    diskFreeBytes
  }
}

requestTakeover

Instance admin only. Returns Takeover.

Hand the machine to Deplo. The installer is waiting for this: it stops the other platform, inherits its certificates, moves Traefik onto 80/443 and the dashboard onto 3000, and then takes the other platform off the disk for good.

mutation {
  requestTakeover(runId: "run_9f1c2ab7d3e4f5a6") {
    state
    platform
    dataLoss
  }
}

cancelTakeover

Instance admin only. Returns TakeoverCancelResult.

Back out. Starts again everything the migration stopped on the other platform, undoes what it created here, and tells the installer to uninstall Deplo. The panel's API token is wiped when a run ends, so one has to be handed over again.

mutation {
  cancelTakeover {
    restarted
    left
  }
}

See also