AppReadyLab
Ask a questionCheck my setup
DecisionsGuidesTested setupsLabMethodologyAsk a questionNewsletterCheck my setup
Operating guides/G01

Migration playbook

Move a business app without losing the way back.

Who this is for

Small teams and service providers moving a customer-facing or internal business application between builders, hosts, or managed stacks.

Definition of done

A verified target setup, a written cutover decision, and a rollback path that stays available until acceptance is complete.

Before you start

Protect the current working path.

  • Name one migration owner and one business approver.
  • Freeze unrelated feature work during the migration window.
  • Keep the current service and billing active until the acceptance checks pass.
  • Use synthetic records for rehearsals; handle production exports under the applicable privacy and retention rules.
01

Step 01

Inventory the running system

A code repository is not the whole application. Record every component that must continue working.

  • Domain and DNS
  • Source code and build settings
  • Database and authentication
  • Uploaded files and object storage
  • Email, scheduled jobs, webhooks, secrets, and external connectors
Stop condition

Stop if a production component has no known owner, export path, or replacement decision.

02

Step 02

Capture a recoverable source state

Create independent copies before changing schemas, credentials, or routing.

  • Export data in a documented usable format
  • Copy uploaded files with counts or checksums
  • Tag the deployed code version
  • Record environment variables without placing secrets in the guide
  • Test at least one restore away from production
03

Step 03

Build the target in parallel

Keep the current service available while the new setup proves it can run the complete workload.

  • Use client-owned production accounts where possible
  • Match required regions and data handling
  • Recreate identity, email, jobs, and callbacks
  • Document differences rather than silently accepting missing capability
04

Step 04

Rehearse data and file movement

Measure the real transfer time, transformation work, and data-loss window before cutover.

  • Record start and end timestamps
  • Compare record and file counts
  • Verify permissions with at least two synthetic tenants
  • Repeat or script any manual transformation that could be missed
Stop condition

Do not schedule cutover while reconciliation has unexplained missing or duplicate records.

05

Step 05

Run acceptance and recovery checks

A fast homepage is not proof that the business workflow or rollback works.

  • Sign in and sign out
  • Read and change an authorised record
  • Upload and download a file
  • Send a transactional email
  • Run a scheduled or background task
  • Restore code, data, and files through the target path
06

Step 06

Cut over with a written rollback trigger

Decide in advance which failures justify returning traffic to the old service.

  • Lower DNS TTL early when applicable
  • Choose a final data-sync method
  • Record who can change routing
  • Define the maximum acceptable outage and data-loss window
  • Keep a timestamped cutover log
07

Step 07

Observe, accept, then retire

Cancellation is the final step after the new setup has handled real work and ownership is clear.

  • Monitor the critical paths during the agreed window
  • Confirm billing and alerts
  • Obtain business-owner acceptance
  • Archive required exports and evidence
  • Cancel the old service only after rollback is no longer required

Acceptance record

Do not close the old path until these statements are true.

  • The target passed the same critical paths used to accept the old service.
  • Code, records, files, configuration, and ownership each have a recovery or replacement path.
  • The old service remains available until the named approver accepts the new one.
  • Unresolved dependencies and expected recurring work are written down.

Help improve this decision

Did this answer your question?