Customer readiness checklist
Use this checklist to prepare for a data migration from an Adobe Commerce on Cloud or on-premises instance to Adobe Commerce as a Cloud Service using the bulk data migration tool.
The migration tool is distributed as part of the Commerce Deployed Engineering (CDE) engagement process. Access to the tool is gated on a signed CDE agreement, and it is not publicly available.
This checklist covers what you need to have in place before the tool is shared (Stage 1) and what you need ready to begin configuration and execution once you have the tool (Stage 2). Review this checklist with your Adobe team early, because some items require Adobe coordination.
Stage 1: before tool access
Complete or confirm the following before the migration tool and documentation are provided.
- CDE engagement — A signed Commerce Deployed Engineering agreement must be in place. Tool access is granted at the Deal Sign stage of the CDE lifecycle. Coordinate with your Adobe team.
- Scoping questionnaire completed — A scoping questionnaire is completed during CDE Discovery to validate that the migration is feasible with the current tool capabilities and to assess data footprint and complexity. Ensure this is completed with your Adobe team before you move forward.
- No HIPAA data confirmed — The source instance must not contain HIPAA-regulated data. Confirm this before you proceed.
- IP addresses provided — Provide your Adobe team with the list of static IP addresses the migration tool will run from. This is required for network access to be configured on the Adobe side.
- Target instance provisioned — The target Adobe Commerce as a Cloud Service instance must be provisioned before migration begins. Coordinate with your Adobe team to confirm the instance is ready.
Stage 2: before running the migration
After you have access to the tool, make the following items ready before you begin configuration and execution.
Migration machine
The migration tool runs on a machine you control, such as a dedicated jump box. This machine must meet the following requirements.
- Docker and Docker Compose installed — The tool is Docker-based. Both
dockeranddocker compose(or the legacydocker-compose) must be installed and working on the migration machine. - Docker execution permissions — The user running the migration must be permitted to execute Docker commands. On Linux, the user must be in the
dockergroup. On macOS and Windows, Docker Desktop must be running and accessible. - Writable working directory — The directory where the migration tool is extracted must be fully writable by the migration user. The tool writes logs, cache, Composer dependencies, and generated files during execution.
- Sufficient disk space — Ensure adequate free disk space for extracted data, Docker images, and log output. Space requirements vary depending on the size of the source database.
- On-premises sources: direct database connectivity from the migration machine — For on-premises source instances, the migration machine must have direct network access to the source database. The tool does not establish on-premises database connectivity automatically. Confirm that the host, port, and credentials are reachable from the migration machine before you run any migration command.
- Cloud CLI installed and SSH key registered — For Adobe Commerce on Cloud source instances, the Cloud CLI must be installed on the migration machine. Your SSH public key must also be registered in your account. See the Secure connections guide for instructions.
Source instance
- Source store APIs accessible — The source store’s REST and GraphQL APIs must be accessible from the migration machine. Ensure that no HTTP Basic Auth or network restriction blocks API traffic to the source URL.
- Source OAuth credentials — The migration tool uses OAuth to authenticate with the source store. Create or confirm an integration in the source Admin (System > Extensions > Integrations) and have the consumer key, consumer secret, access token, and access token secret ready.
- PaaS sources: Magento Cloud API token — Generate a Cloud API token from your Cloud account settings under Account Settings > API Tokens. Required only when the source is an Adobe Commerce on Cloud instance.
- Source database credentials — (On-premises only) Have the source MySQL database connection details ready for configuration:
host,port,user,password, anddatabasename. - Ability to pause cron — You must be able to stop cron on the source instance for the duration of data extraction to prevent concurrent writes.
- Ability to pause integrations and background jobs — Any third-party integrations (ERP, OMS, PIM), scheduled jobs, or background processes that write to the source database must be paused for the extraction window.
- Ability to enable and disable maintenance mode — (Phased migration only) If you run a phased migration with a maintenance window, you must be able to enable and disable maintenance mode on the source instance.
Target instance
- Tenant ID and organization ID confirmed — Obtain your
TARGET_TENANT_IDandTARGET_ORG_IDfrom your Adobe team before configuration. - IMS OAuth Server-to-Server credentials — Required for the migration tool to authenticate with the target. Generated through the Adobe Developer Console. You need Developer or Admin access to your Adobe organization, because basic user access is not sufficient to create credentials. Coordinate with your Adobe team for the correct product profile to select, and have the client ID (
ADOBE_IMS_CLIENT_ID) and client secret (ADOBE_IMS_CLIENT_SECRET) ready. - CDMS endpoint URL — Provided by your Adobe team. Do not attempt to infer this value. You need both the pre-production endpoint for sandbox and test migrations and the production endpoint for live cutover migrations.
- Core configuration aligned between source and target — Core configuration data, such as store settings and system configuration, is not migrated by the tool. Set it up manually on the target to match the source before migration.
- B2B stores: B2B features consistently configured — If the source is a B2B-enabled store, ensure that the relevant B2B Admin settings are consistently configured on both source and target before migration. Refer to the migration guide for the specific settings required.
Migration planning
-
Migration approach decided — Determine which approach fits your use case before you start.
- Single-phase migration - No maintenance mode required. Suits dry runs, dev or sandbox environments, or any migration where the source can remain live during extraction.
- Multi-phase migration - Maintenance mode is required. A multi-phase migration is required for production migrations where the source must be frozen during extraction to ensure data consistency.
-
Maintenance window planned — Applies to multi-phase migrations only. Plan and communicate the maintenance window in advance. The source instance is unavailable to end users for the duration of the extraction and loading phases.
-
Store view code confirmed — Identify the store view code (
STORE_CODE) on the source instance. It defaults todefaultbut must match the actual code in Admin > Stores > All Stores. An incorrect store code can affect data operations during migration.
After you confirm all items, you are ready to verify service access with the migration service access guide, and then begin the configuration and execution steps in the migration guide.