Prepare your existing system

You need to prepare your existing Adobe Commerce implementation to import it into a new Adobe Commerce on cloud infrastructure 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 Adobe Commerce on cloud infrastructure repository. When you push, the build and deploy scripts run to update code, static content, and environment services.

Prepare and add required files

To import Adobe Commerce code to a Adobe Commerce on cloud infrastructure 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 (MariaDB), PHP, OpenSearch or Elasticsearch
• .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 Adobe Commerce code:

1. In the Adobe Commerce on cloud infrastructure GitHub repository, select the branch corresponding to the Adobe Commerce version you currently have.

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

   

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

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

   1
   cd <Project installation dir>
   

   1
   mkdir .magento
   

4. One at a time, create the following files in your Adobe Commerce system using the contents of the files in the Adobe Commerce on cloud infrastructure repository:

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

For example, to create <Adobe Commerce install dir>/.magento.app.yaml from the 2.3.3 branch:

1. In the Adobe Commerce on cloud infrastructure GitHub, click .magento.app.yaml.

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

   

3. In your Adobe Commerce project, open a text editor in the Adobe 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 project 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 authentication keys

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

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

To create a new auth.json file:

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

   • Using a text editor, create an auth.json file in your project 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 Adobe 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 Adobe 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 Adobe Commerce on cloud infrastructure Git repository, modify your composer.json for Cloud. You can also view a sample composer.json.

To edit composer.json:

1. Go to the project installation directory that contains the code that you downloaded from GitHub as the 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 Adobe 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 <Adobe Commerce install dir>/bin/magento setup:backup --media
   

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

3. Transfer the media file to your Adobe Commerce on cloud infrastructure system:

   1
   rsync <Adobe 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 <Project 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 Adobe Commerce on cloud infrastructure env.php file in each environment in a later step.

Migrate Commerce data

Create a database dump and transfer the data from an existing database. You will import this data to your Adobe Commerce on cloud infrastructure 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 Adobe Commerce on cloud infrastructure 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 Adobe Commerce into Adobe Commerce on cloud infrastructure