Prepare your existing Magento Commerce install

You need to prepare your existing Magento Commerce implementation to import it into a new Magento Commerce Cloud project. This includes updating and adding files, transferring media files, and migrating data.

Before preparing your project and importing code, push all pending changes to Git. Your remote Magento Commerce Cloud branch should be fully updated. When you push, build and deploy scripts run to update code, static content, and environment services.

These import preparation steps include the following:

Prepare and add required files

To import Magento Commerce code to a Magento Commerce Cloud project, you need to add a directory and the following files to your existing code.

  • manages applications, service relationships, mounts for writable directories, and cron jobs
  • .magento/services.yaml for service configurations including MySQL, PHP, Redis, Solr (2.0.X only), ElasticSearch (2.1.X and later)
  • .magento/routes.yaml for handling routes including redirections, caching, and server-side includes
  • magento-vars.php for multiple websites and stores

You need to add these files to your Magento Commerce code:

  1. Go to the Magento Commerce Cloud GitHub.
  2. Select the branch corresponding to the Magento Commerce version you currently have.

    The following figure shows an example of selecting the 2.1.4 branch.

    Switch to your current Magento Commerce branch

    In the procedure that follows, you’ll copy the contents of some of these files to your Magento Commerce system.

  3. Log in to your Magento Commerce system as, or switch to, the Magento file system owner.
  4. Enter the following commands in the order shown:

    cd <Magento installation dir>
    mkdir .magento
  5. One at a time, create the following files in your Magento Commerce system using the contents of the files in the Magento Commerce Cloud GitHub:

    • <Magento Commerce install dir>/
    • <Magento Commerce install dir>/magento-vars.php
    • <Magento Commerce install dir>/.magento/services.yaml
    • <Magento Commerce install dir>/.magento/routes.yaml

    For example, to create <Magento Commerce install dir>/ from the 2.1.4 branch:

    1. In the Magento Commerce Cloud GitHub, click
    2. In the upper right, click Raw, as the following figure shows.

      View the raw version of the file

    3. In your Magento Commerce project, open a text editor in the Magento Commerce installation directory (for example, /var/www/html/magento2).
    4. Paste the raw contents of from GitHub into the text editor.
    5. Make sure the file is named when you save the file.
    6. Repeat these tasks for the other files.

      • Make sure to create magento-vars.php in the Magento root directory.
      • Make sure to create routes.yaml and services.yaml in the .magento subdirectory.

Modify these files as necessary as discussed in the following topics:

When you push your code, all services are configured into the associated environment per active branch of code. These files affect all Starter environments and all Pro Integration environments. To update these settings in Pro Staging and Production, you need to enter a ticket.

Add or update auth.json with Magento Authentication keys

To enable install and update commands for Magento Commerce Cloud, you must have an auth.json file in your project’s root directory. auth.json contains your Magento Commerce authorization credentials for Magento Commerce Cloud.

In some cases, you might already have auth.json. Verify if you have the file and add your authentication credentials before you create a new one. It’s located in your Magento root directory. You can also get a sample auth.json.

To create a new auth.json in the event you don’t have one:

  1. Use a text editor to create a file named auth.json in your Magento root directory.
  2. Replace <public-key> and <private-key> with your Magento Commerce authentication credentials.

    See the following example:

       "http-basic": {
          "": {
          "username": "<public-key>",
          "password": "<private-key>"
  3. Save your changes to auth.json and exit the text editor.

Edit composer.json

Before you push code to the Magento Commerce Cloud Git repository, modify your composer.json for Cloud. You can also view a sample composer.json.

To edit composer.json:

  1. If you haven’t done so already, log in to your Magento Commerce Cloud server as the Magento file system owner.
  2. In a text editor, open composer.json in the project root directory.
  3. Substitute the following value in the require section:

    "magento/product-enterprise-edition": "<version>",


    "magento/magento-cloud-metapackage": "<version>",

    Both <version> values must be the same. For example, if your current Magento Commerce version is 2.1.9, your magento-cloud-metapackage version must also be 2.1.9.

  4. Update the "files" directive in the autoload section to refer to app/etc/NonComposerComponentRegistration.php as follows:

    "autoload": {
      "psr-4": {
          "Magento\\Framework\\": "lib/internal/Magento/Framework/",
          "Magento\\Setup\\": "setup/src/Magento/Setup/",
          "Magento\\": "app/code/Magento/"
      "psr-0": {
          "": "app/code/"
      "files": [
  5. Save your changes to composer.json and exit the text editor.
  6. In the terminal application, run composer update to update composer.lock. Wait while dependencies are updated.
  7. Commit the changes to GitHub:

    git add -A && git commit -m "Add Cloud files" && git push origin <branch name>

Back up and transfer media files

Use the command magento setup:backup --media to back up media files:

  1. Get the integration system’s SSH URL.
  2. To back up media files, enter the following command:

    php <Magento Commerce install dir>/bin/magento setup:backup --media

    The backup is stored in the <Magento Commerce install dir>/var/backups directory.

  3. Transfer the media file to your Magento Commerce Cloud system:

    rsync <Magento Commerce install dir>/var/backups/<backup file name> <cloud ssh url>:var/media.tgz

    For example,

    rsync /var/www/html/magento2/var/backups/1487962699_filesystem_media.tgz

Copy the encryption key

To be able to decrypt encrypted data from your imported database, copy your encryption from your existing env.php file. Every environment inIntegration, Staging, and Production has an env.php of sensitive data and environment variables. The file contains a nested PHP array storing configuration data.

  1. Open <Magento install dir>/app/etc/env.php in a text editor.
  2. Search for the value of key in the crypt array.
  3. Copy the value to the clipboard and save it.

You must paste the encryption key into your Magento Commerce Cloud env.php file in each environment in a later step.

Migrate Magento Commerce data

Create a database dump and transfer the data from an existing database. You will import this data to your Magento Commerce Cloud database.

The following command example compresses the dump so it doesn’t significantly interfere with traffic from in live site. The dump file is named db.sql.gz. You may want to include the date in the file name if you do multiple dumps over time. Because the database dump can be large, we recommend you create it in a directory not tracked by Git.

  1. In your existing environment, create a database dump.

     mysqldump -h <db-host> -P <db-port> -p -u <db-user> <db-name> --single-transaction --no-autocommit --quick | gzip > ~/db.sql.tgz

For example, if your database is on localhost with the default port (3306), database username is magento, and database name is also magento:

    mysqldump -p -u magento magento --single-transaction --no-autocommit --quick | gzip > ~/db.sql.tgz
  1. Use the rsync command to transfer the database dump to the Magento Commerce Cloud environment in the var directory of the application you are importing into:

     rsync <db dump file name> <cloud SSH URL>:var/db.sql.gz

To find <cloud SSH URL>, see Find the information you need for your import.

Next step

Import Magento Commerce into Magento Commerce Cloud