Skip to content

Move a Subscription to Another Server

This tutorial walks through migrating a running subscription from one server to another — a Portainer environment on Docker, or a DBFilter server on DBFilter — without changing the customer's domain.

When You Need This

  • The current server is running out of capacity (containers, disk, RAM)
  • You are retiring or replacing a host
  • A customer must be moved to a different region or a different PostgreSQL cluster
  • You are consolidating several small environments into one

There is downtime

The data is copied with a backup / restore cycle. Everything written to the instance after the backup starts and before traffic is switched is lost. Announce a maintenance window and, ideally, stop the customer from working during the copy.

Before You Start

Sadeem refuses to start the migration unless all of these are true:

  • The subscription state is Running
  • The subscription has no active stages — cancel them first, they can be recreated afterwards
  • The subscription is registered on a backup server (Backup Server + Backup UUID are filled)
  • No other migration is already in flight for this subscription
  • Docker only — the target environment already hosts the subscription's Docker image, has free container capacity, and the subscription has no code server (remove it first)
  • DBFilter only — the target server is Confirmed, has free capacity, and runs the same Odoo version

Take a manual backup anyway

The pipeline creates its own backup, but an extra manual backup before you start costs nothing and gives you a second restore point.

Step 1: Open the Migration Wizard

  1. Open the subscription form.
  2. Click Migrate Server in the header. The button appears only for running subscriptions with no migration in progress, and only for SaaS administrators.

The wizard shows the current server, the domain and the Odoo version so you can confirm you picked the right record.

Step 2: Choose the Target and the Grace Period

Field What to set
Target Environment (Docker) / Target DBFilter Server (DBFilter) The destination. The current server is excluded from the list.
Cleanup Grace Period (days) How long the old instance is kept after success. Default 7. Rollback stays possible for this whole period. 0 destroys the source immediately.

Keep the grace period

The grace period is your undo button. Set it to 0 only when you are certain and disk space on the old server is urgently needed.

Click Migrate. The migration record opens and the job starts in the background.

Step 3: Watch the Pipeline

The migration moves through these states:

Queued → Backing Up → Provisioning Target → Restoring → Switching Traffic → Verifying → Done
  • Backing Up and Restoring are handed off to the backup server. The migration parks in that state with an explanatory chatter message and resumes automatically — a couple of minutes here is normal, not a hang.
  • Switching Traffic is the moment the domain starts pointing at the new server.
  • Every step is logged in the migration's chatter, and the subscription gets a chatter entry when the migration is queued, completed, rolled back or manually finished.

While a migration is active the subscription form shows an orange banner. Do not start, stop or cancel the subscription until it finishes.

Step 4: Verify

Once the state is Done:

  1. Open the customer URL and log in.
  2. Check that recent data is present — the last records the customer created before the maintenance window.
  3. Confirm the backup registration: on Docker the subscription now uses the target environment's default backup server, on DBFilter the target server's.
  4. Docker with custom addons: if the source and target root servers differ, the migration posts "Action required: custom addons … must be copied manually". Copy that directory to the new root server before the customer restarts the instance.
  5. Recreate anything that had to be removed first — code server, stages.

Step 5: Let the Cleanup Happen (or Force It)

Nothing else is required: an hourly cron destroys the old instance once the grace period expires — the old Docker stack (plus its volumes and addons directory when the old root server is a different machine), or the old database on the source DBFilter server.

To reclaim the space earlier, open the migration and click Clean Up Now.

Cleanup ends the rollback window

After cleanup, Rollback is no longer available. Verify the instance properly before forcing it.

If Something Goes Wrong

Situation What to do
A step failed (state Failed) Read the failure message, fix the cause, then Retry — it resumes at the failed step
The target is in a bad state Start Over — removes everything created on the target and restarts from the backup step
You want the customer back on the old server Rollback — available while the source has not been cleaned up
The job died (server restart, worker kill) and the record is stuck Mark Failed, then Retry or Rollback
The instance actually works but verification could not see it Mark Done after checking it by hand

Details and error-by-error guidance: Migration Issues.