Deploy code and migrate static files and data
Previous step
Prepare to deploy to Staging and Production
To migrate your database and static files to Staging and Production:
If you encounter errors or need to change project configuration, complete the required updates in your local environment. Then, push the code changes to the Integration environment to deploy and test before pushing to Staging and Production environments.
Deploy code to Staging and Production
You can use the Project Web Interface or SSH and CLI commands to deploy your code to Staging and Production.
Deploy code with the Project Web Interface
The Project Web Interface provides features to create, manage, and deploy code in Integration, Staging, and Production environments for Starter and Pro plans.
For Pro projects, deploy the Integration branch to Staging and Production:
- Log in to your project.
- Select the Integration branch.
- Select the Merge option to deploy to Staging. Complete all testing.
- Select the Staging branch.
- Select the Merge option to deploy to Production.
For Starter, deploy the development branch you created to Staging and Production (master):
- Log in to your project.
- Select the prepared code branch.
- Select the Merge option to deploy to Staging. Complete all testing.
- Select the Staging branch.
- Select the Merge option to deploy to Master.
Deploy code with SSH and CLI
You can use the Magento Cloud CLI commands to deploy code to Starter and Pro environments. You need SSH and Git access to your project. See prepare for deployment.
Prerequisites:
Step 1: Deploy and test the Integration environment
-
After logging into the project, check out the Integration environment:
1
magento-cloud environment:checkout <environment-ID>
-
Synchronize your local Integration environment with the remote environment:
1
magento-cloud environment:synchronize <environment-ID>
-
Create a snapshot of the environment as a backup:
1
magento-cloud snapshot: create -e <environment-ID>
-
Update code in your local branch as needed.
-
Add, commit, and push changes to the environment.
1
git add -A && git commit -m "Commit message" && git push magento <environment-ID>
-
Complete site testing.
Step 2: Merge changes to Staging and deploy
-
Check out the Staging environment:
1
magento-cloud environment:checkout <environment-ID>
-
Synchronize your local Staging environment with the remote environment:
1
magento-cloud environment:synchronize <environment-ID>
-
Create a snapshot of the environment as a backup:
1
magento-cloud snapshot: create -e <environment-ID>
-
Merge the Integration environment to Staging to deploy:
1
magento-cloud environment:merge <Integration-ID>
-
Complete site testing.
Step 3: Deploy to Production
-
Check out, synchronize, and create a snapshot of your local Production environment.
-
Merge the Staging environment to Production to deploy:
1
magento-cloud environment:merge <Staging-ID>
-
Complete site testing.
Migrate static files
Static files are stored in mounts
. There are two methods for migrating files from a source mount location, such as your local environment, to a destination mount location. Both methods use the rsync
utility, but we recommend using the magento-cloud
CLI for moving files between the local and remote environment. And we recommend using the rsync
method when moving files from a remote source to a different remote location.
Migrate files using the CLI
You can use the mount:upload
and mount:download
CLI commands to migrate files between the local and remote environment. Both commands use the rsync
utility, but the CLI commands provide options and prompts tailored to the Magento Commerce Cloud environment. For example, if you use the simple command with no options, the CLI prompts you to select which mount or mounts to upload or download.
1
magento-cloud mount:download
Sample response:
1
2
3
4
5
6
7
8
9
10
11
12
13
Enter a number to choose a mount to download from:
[0] app/etc
[1] pub/static
[2] var
[3] pub/media
[4] All mounts
> 3
Target directory: ~/pub/media/
Downloading files from the remote mount pub/media to pub/media
Are you sure you want to continue? [Y/n] Y
To upload files from a local pub/media/
folder to the remote pub/media/
folder for the current environment:
1
magento-cloud mount:upload --source /path/to/project/pub/media/ --mount pub/media/
Sample response:
1
2
3
4
5
6
7
8
9
10
Uploading files from pub/media to the remote mount pub/media
Are you sure you want to continue? [Y/n] Y
building file list ... done
./
sample-file.jpeg
sent 8.43K bytes received 48 bytes 3.39K bytes/sec
total size is 154.57K speedup is 18.23
Use the --help
option for the mount:upload
and mount:download
commands to see more options. For example, there is a --delete
option to remove extraneous files during the migration.
Migrate files using rsync
Alternatively, you can use the rsync
utility to migrate files.
1
rsync -azvP <source> <destination>
This command uses the following options:
a
–archivez
–compress files during the migrationv
–verboseP
–partial progress
See the rsync man page.
To transfer media from remote-to-remote environments directly, you must enable SSH agent forwarding, see GitHub guidance.
To migrate static files from remote-to-remote environments directly (fast approach):
-
Use SSH to log in to the source environment. Do not use the
magento-cloud
CLI. Using the-A
option is very important because it enables forwarding of the authentication agent connection.To find the SSH access link in your Project Web Interface, select the environment and click Access Site.
1
ssh -A <environment_ssh_link@ssh.region.magento.cloud>
-
Use the
rsync
command to copy thepub/media
directory from your source environment to a different remote environment.1
rsync -azvP pub/media/ <destination_environment_ssh_link@ssh.region.magento.cloud>:pub/media/
-
Log in to the other remote environment to verify the files migrated successfully.
Migrate the database
Database import and export operations can take a long time, which can affect site performance and availability. Schedule import and export operations during off-peak hours to prevent slow performance or outages on Magento Production sites.
Prerequisite: A database dump (see Step 3) should include database triggers. For dumping them, confirm you have the TRIGGER privilege.
Important: The Integration environment database is strictly for development testing and can include data that you do not want to migrate into Staging and Production.
For continuous integration deployments, we do not recommend migrating data from Integration to Staging and Production. You could pass testing data or overwrite important data. Any vital configurations will be passed using the configuration file and setup:upgrade
command during build and deploy.
We do recommend migrating data from Production into Staging to fully test your site and store(s) in a near-production environment with all services and settings.
To transfer media from remote-to-remote environments directly you must enable ssh agent forwarding, see GitHub guidance
To migrate a database:
-
SSH into the environment you want to create a database dump from:
1
ssh -A <environment_ssh_link@ssh.region.magento.cloud>
-
List the environment relationships to find the database login information:
1
php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"]))->database);'
-
Create a database dump file in
gzip
format:For Starter environments and Pro Integration environments:
1
mysqldump -h <database host> --user=<database username> --password=<password> --single-transaction --triggers main | gzip - > /tmp/database.sql.gz
For Pro Staging and Production environments, the name of the database is in the
MAGENTO_CLOUD_RELATIONSHIPS
variable (typically the same as the application name and username):1
mysqldump -h <database host> --user=<database username> --password=<password> --single-transaction --triggers <database name> | gzip - > /tmp/database.sql.gz
-
Transfer the database dump to another remote environment with the
rsync
command:1
rsync -azvP /tmp/database.sql.gz <destination_environment_ssh_link@ssh.region.magento.cloud>:/tmp
-
Type
logout
to terminate the SSH connection. -
Open an SSH connection to the environment you want to migrate the database into:
1
ssh -A <destination_environment_ssh_link@ssh.region.magento.cloud>
-
Import the database dump:
1
zcat /tmp/database.sql.gz | mysql -h <database_host> -u <username> -p<password> <database name>
The following example references the gzip file created by the database dump operation:
1
zcat /tmp/database.sql.gz | mysql -h database.internal -u user main
Troubleshooting the database migration
If you encounter the following error, you can try to create a database dump with the DEFINER replaced:
1
ERROR 1277 (42000) at line <number>: Access denied; you need (at least one of) the SUPER privilege(s) for this operation
This error occurs because the DEFINER for the triggers in the SQL dump is the production user. This user requires administrative permissions.
To solve this problem, you can generate a new database dump changing or removing the DEFINER
clause as shown in the following example:
1
mysqldump -h <database host> --user=<database username> --password=<password> --single-transaction <database name> | sed -e 's/DEFINER[ ]*=[ ]*[^*]*\*/\*/' | gzip > /tmp/database_no-definer.sql.gz
Use the database dump file to migrate the database.
After migrating the database, you can set up your stored procedures or views in Staging or Production the same way you did in your Integration environment.
Related topics