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, transfering 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:
• [Add Cloud-specific files and directories ]to Magento Commerce. Without these files and directories, your Magento Commerce code can’t be imported to Cloud.
• Add Authentication Keys to auth.json.
• Modify your existing composer.json to specify Cloud-specific dependencies. Make sure to include all modules. Cloud uses this file for composer install commands. Add composer.lock to Git. Cloud uses this file for composer update commands and during the build and deploy process.
• Transfer media files to Cloud.
• Add your Magento Commerce authentication credentials to auth.json if you haven’t done so already.
• Migrate your Magento Commerce data.

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.

• .magento.app.yaml 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.

   

   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.app.yaml
   • <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>/.magento.app.yaml from the 2.1.4 branch:

   1. In the Magento Commerce (Cloud) GitHub, click .magento.app.yaml.

   2. In the upper right, click Raw, as the following figure shows.

      

   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 .magento.app.yaml from GitHub into the text editor.
   5. Make sure the file is named .magento.app.yaml 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:

• .magento/routes.yaml
• .magento/services.yaml
• .magento.app.yaml

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": {
         "repo.magento.com": {
         "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>",
   

   with

   "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": [
         "app/etc/NonComposerComponentRegistration.php"
         ]
     }
   

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 43bkopvkhelhy-master-l8uv4kp@ssh.us.magentosite.cloud:var/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 user name 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)