Prepare your existing Magento EE system

This topic discusses tasks you must perform in your existing Magento EE installation to prepare it to be imported into a Magento Commerce (Cloud) project.

Before you continue, push all pending changes to Git.

You must do the following:

  • Add Cloud-specific files and directories to Magento EE. Without these files and directories, your Magento EE code can’t be imported to Cloud.
  • Modify your existing composer.json to specify Cloud-specific dependencies.
  • Add composer.lock to Git because Cloud reads it, and not composer.json, during the build and deploy process.
  • Transfer media files to Cloud.
  • Add your Magento EE authentication credentials to auth.json if you haven’t done so already.
  • Dump your Magento EE database.

Prepare Magento EE files

For your Magento EE code to import to a Magento Commerce (Cloud) project, you must have a directory and some files required by Cloud. Following is the list of those files:

Add required configuration files

To add required files to your Magento EE code:

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

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

    Switch to your current EE branch

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

  3. Log in to your Magento EE 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 EE system using the contents of the files in the Magento Commerce (Cloud) GitHub:

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

    For example, to create <Magento EE 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 EE project, open a text editor in the Magento EE 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:

Add or update auth.json

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

In some cases, you might already have auth.json so check to see if it exists and has your authentication credentials before you create a new one. It’s located in your Magento root directory.

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 EE 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, you must change your composer.json so it meets Cloud requirements.

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, or switch to, 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. In other words, if your current EE version is 2.1.3, your magento-cloud-metapackage version must also be 2.1.3.

  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. Run composer update to update composer.lock:

    composer update
  7. Wait while dependencies are updated.
  8. When you’re done, 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

This section discusses how to use the 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 EE install dir>/bin/magento setup:backup --media

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

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

    rsync <Magento EE 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. Each environment (Integration, Staging, and Production) has an env.php of 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 (it’s 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.

Prepare the Magento EE database

Create a dump of the database you want to import using mysqldump.

Create a database dump

The following example shows how to compress the dump so it doesn’t significantly interfere with traffic from in live site.

In the example, the dump file is named db.sql.gz. It’s a good idea 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.

Command syntax follows:

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

Example if your database is on localhost with the default port (3306), database user name is magento, and database name is also magento:

mysqldump -p -u magento magento --single-transaction --no-autocommit --quick | gzip > ~/db.sql.tgz

Transfer the database dump from Magento EE to Cloud

Use the rsync command as follows to transfer the database dump from your Magento EE system to the Magento Commerce (Cloud) environment.

Now that you have created the dump, move it to 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 EE into Magento Commerce (Cloud)