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 includesmagento-vars.php
—for multiple websites and stores
Add these files to your Adobe Commerce code:
-
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. - Log in to your Adobe Commerce system as, or switch to, the file system owner.
-
Change to the project installation directory and create a
.magento
directory.1
cd <Project installation dir>
1
mkdir .magento
-
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:
- In the Adobe Commerce on cloud infrastructure GitHub, click .magento.app.yaml.
-
In the upper right, click Raw, as the following figure shows.
- In your Adobe Commerce project, open a text editor in the Adobe Commerce installation directory (for example,
/var/www/html/magento2
). - Paste the raw contents of
.magento.app.yaml
from GitHub into the text editor. - Save the file using the name:
.magento.app.yaml
-
Repeat these tasks for the other files.
- Create
magento-vars.php
in the project root directory. - Create
routes.yaml
andservices.yaml
in the.magento
subdirectory.
- Create
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:
-
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 newauth.json
file.
- Using a text editor, create an
-
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>" } } }
-
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:
-
In the Project Web Interface, click the configuration icon in the upper left corner.
-
In the Configure Project view, click the Variables tab.
-
Click Add Variable.
-
In the Name field, enter
env:COMPOSER_AUTH
. -
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>" } } }
-
Select Visible during build and deselect Visible at run.
-
Click Add Variable.
-
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
:
- Go to the project installation directory that contains the code that you downloaded from GitHub as the file system owner.
- In a text editor, open
composer.json
in the project root directory. -
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, yourmagento-cloud-metapackage
version must also be 2.3.3. -
Update the
"files"
directive in theautoload
section to refer toapp/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" ] }
- Save your changes to
composer.json
and exit the text editor. - In the terminal application, run
composer update
to updatecomposer.lock
. Wait while dependencies are updated. -
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:
- Get the integration system’s SSH URL.
-
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. -
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.
- Open
<Project install dir>/app/etc/env.php
in a text editor. - Search for the value of
key
in thecrypt
array. - 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.
-
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 alsomagento
:1
mysqldump -p -u magento magento --single-transaction --no-autocommit --quick | gzip > ~/db.sql.tgz
-
Use the
rsync
command to transfer the database dump to the Adobe Commerce on cloud infrastructure environment in thevar
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