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 from your local workstation to your remote Magento Commerce Cloud repository. When you push, the build and deploy scripts run to update code, static content, and environment services.

The import preparation steps include the following:

• Prepare and add required files
• Add Magento authentication keys
• Modify your existing composer.json
• Transfer media files to Cloud
• Add your Magento Commerce encryption key
• Migrate your Magento Commerce data

Prepare and add required files

To import Magento Commerce code to a Magento Commerce Cloud project, you must add 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

Add these files to your Magento Commerce code:

1. In the Magento Commerce Cloud GitHub repository, select the branch corresponding to the Magento Commerce version you currently have.

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

   

2. Log in to your Magento Commerce system as, or switch to, the Magento file system owner.

3. Change to the Magento installation directory and create a .magento directory.

   1
   cd <Magento installation dir>
   

   1
   mkdir .magento
   

4. One at a time, create the following files in your Magento Commerce system using the contents of the files in the Magento Commerce Cloud repository:

   • <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.3.3 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. Save the file using the name: .magento.app.yaml

6. Repeat these tasks for the other files.

   • Create magento-vars.php in the Magento root directory.
   • Create routes.yaml and services.yaml in the .magento subdirectory.

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 Magento authentication keys

You must have an authentication key to access the Magento Commerce repository and to enable install and update commands for your Magento Commerce Cloud project. There are two methods for specifying Composer authorization credentials.

• authentication file—You must have an auth.json file that contains your Magento Commerce authorization credentials in your Magento Commerce Cloud root directory.
• environment variable—Alternatively, you can use an environment variable to set up authentication keys in your Magento Commerce Cloud project to prevent accidental exposure.

To create a new auth.json file:

1. If you do not have an auth.json file in your Magento root directory, create one.

   • Using a text editor, create an auth.json file in your Magento root directory.
   • Copy the contents of the sample auth.json into the new auth.json file.

2. Replace <public-key> and <private-key> with your Magento Commerce authentication credentials.

   1
   2
   3
   4
   5
   6
   7
   8
   {
       "http-basic": {
           "repo.magento.com": {
               "username": "<public-key>",
               "password": "<private-key>"
           }
       }
   }
   

3. Save your changes and exit the text editor.

The following method is best to prevent accidental exposure of credentials, such as pushing an auth.json file to a public repository.

To add authentication keys using an environment variable:

1. In the Project Web Interface, click the configuration icon in the upper left corner.

2. In the Configure Project view, click the Variables tab.

3. Click Add Variable.

4. In the Name field, enter env:COMPOSER_AUTH.

5. In the Value field, add the following and replace <public-key> and <private-key> with your Magento Commerce authentication credentials:

   1
   2
   3
   4
   5
   6
   7
   8
   {
       "http-basic": {
           "repo.magento.com": {
               "username": "<public-key>",
               "password": "<private-key>"
           }
       }
   }
   

6. Select Visible during build and deselect Visible at run.

7. Click Add Variable.

8. Remove the auth.json file from each environment.

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. Go to the Magento installation directory that contains the code that you downloaded from GitHub 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:

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

   with

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

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

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

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   "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:

   1
   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:

   1
   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:

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

   For example,

   1
   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 decrypt the encrypted data from your imported database, copy your encryption key from your existing env.php file. Every environment in Integration, 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 example compresses the dump so that it does not significantly interfere with traffic from a 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.

   1
   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:

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

2. 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:

   1
   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