Before pushing your code to your Starter or Pro Staging and Production environments, you should fully build on your local. Fully testing builds and deploys along with full site testing can reduce the risk of issues or delays for your final site deployment, and expose any issues early for debugging.
These tasks walk through:
- Complete development on your local
- Complete a full build and deploy process on your local (deploys to the associated active development environment)
- Test fully before continuing deployment to Staging
For more information on the full five step process, see the Deployment process.
We highly recommend completing your testing in an Integration active environment and the Staging environment. Only complete final tests for going live in the Production environment. Your Staging environment is best for testing with code, data, and services including Fastly, New Relic, and others.
Update composer if you add extensions
If you modified your
composer.json file to add modules, we recommend running the
composer update command in a terminal. This command updates any dependencies in the
composer.lock. During the build phase, we run
composer install on a fresh clone of your Git branch of code to retrieve the latest dependencies.
Verify all required files in Git
Your Git branch must have the following files for building and deploying to your local, Integration, Staging, and Production environments:
auth.jsonin the root project directory. This file includes the authentication keys entered when creating the project. If you need to verify the file and settings, see Troubleshoot deployment.
config.phpif you use Configuration Management to manage configuration settings
.magento.app.yamlis updated and saved in the root directory
services.yamlis updated and saved in
routes.yamlis updated and saved in
Test build your code locally before pushing
Sometimes you just want to test your build prior to pushing your code to Git. You can use a specific set of commands to build locally. Do NOT push the generated build files from this test to your remote Git branch. This is a test to ensure no issues occur before pushing to Git. Remember, when you push to the remote Git branch, a full build and deploy process begins automatically.
- SSH into your local workspace.
- Move to another location to run your build. You should keep this build separate from your usual Git branch.
Run the following command to build locally. The command builds the current project locally strictly to test the build without the full patching and commit process.
For details, enter
magento-cloud local:build --help.
- Watch for the results. A series of files will generate for the build. If you do not encounter errors, you can push code to the remote Git branch and continue.
If errors occur during the build, you can investigate and resolve the code issues. You should not commit the files from this build to Git.
To remove these test builds, you can use the
magento-cloud local:clean command. For details, enter
magento-cloud local:clean --help.
Push code to Git and Integration
Before you continue, push all current code to the remote Cloud server so that, in event of issues, you can recover the state of the application.
To get started with environment branches:
On your local workstation, change to your Cloud project directory.
Switch to the file system owner.
Log in to your project.
List your projects.
List environments in the project. Every environment includes an active Git branch that contains your code, database, environment variables, configurations, and services.
It is important to use the
magento-cloud environment:listcommand because it displays environment hierarchies, whereas the
git branchcommand does not.
Fetch origin branches to get the latest code.
git fetch origin
Checkout, or switch to, a specific branch and environment.
magento-cloud environment:checkout <environment-ID>
Git commands only checkout the Git branch. The
magento-cloud checkoutcommand checks out the branch and switches to the active environment.
You can create a new environment branch using the
magento-cloud environment:branch <environment-name> <parent-environment-ID>command syntax. It may take some additional time to create and activate a new environment branch.
Use the environment ID to pull any updated code to your local. This is not necessary if the environment branch is new.
git pull origin <environment-ID>
(Optional) Create a snapshot of the environment as a backup.
magento-cloud snapshot:create -e <environment-ID>
To push code to your remote environment:
- Change to your project root directory.
Complete code commits in a terminal.
git add -A && git commit -m "<comment>"
git push origin <branch name>
- The build and deploy phases begin. Wait for the deployment to complete.
During the build phase, we perform the following tasks:
- Apply patches distributed to all Adobe Commerce on cloud infrastructure accounts
- Apply patches we provided specifically to you
- Enable modules to build
- Compile code and the dependency injection configuration
The build also checks for a configuration file. If the file exists, the static file deployment is also completed during the build stage. If not, it is completed in the deployment stage.
Before you continue, you must know the file system path to any patch we provided specifically to you. Typically, hotfixes are in the
<Project root dir>/m2-hotfixes directory.
To build your site:
Apply patches distributed to all Adobe Commerce on cloud infrastructure accounts.
Enter the following command from the project root directory:
Output includes the following:
1 2 3 4 5 6 7 8 9 10 11 12
[2016-11-30 15:05:15] Copying static.php to front-static.php [2016-11-30 15:05:15] Command:git apply /var/www/html/magento2/vendor/magento/magento-cloud-configuration/patches/000-MAGETWO-57719-2.1.2.patch [2016-11-30 15:05:15] Status:0 [2016-11-30 15:05:15] Output:array ( ) [2016-11-30 15:05:15] Command:git apply /var/www/html/magento2/vendor/magento/magento-cloud-configuration/patches/MAGETWO-52660-scd-improvement.patch [2016-11-30 15:05:15] Status:0 [2016-11-30 15:05:15] Output:array ( ) ... more ... )
Apply hotfixes and other patches provided to you:
git apply <path to patch>
For example, to apply hotfixes:
git apply m2-hotfixes/<patch file name>
m2-hotfixesdirectory is empty, skip this step.
If patches are present, output from this command is similar to the patches command.
Enable all missing modules.
Compile code and the dependency injection configuration:
php bin/magento setup:di:compile
This command can take several minutes to complete and produces messages similar to the following:
1 2 3 4 5 6 7 8 9 10 11
Compilation was started. 0% 1 sec 54.0 MiB%message% 0/7 [>---------------------------] 0% 1 sec 54.0 MiBProxies code generation... 0/7 [>---------------------------] 0% 1 sec 54.0 MiB Proxies code generation... 1/7 [====>-----------------------] 14% 1 sec 58.0 MiB Repositories code generation... 1/7 [====>-----------------------] 14% 1 sec 58.0 MiB Repositories code generation... 2/7 [========>-------------------] 28% 30 secs 176.0 MiB ... ... Interception cache generation... 7/7 [============================] 100% 5 mins 324.0 MiB
If you receive errors, debug them when possible and open a support ticket for further assistance.
We strongly recommend you complete your testing in an Integration or Staging environment only, and not in a Production environment.
We highly recommend installing the Adobe Commerce application prior to deployment. During the deployment phase, we perform the following tasks:
- Install the Adobe Commerce application if needed
- If the Adobe Commerce application is installed, upgrade components
- Clear the cache
- Set the Adobe Commerce application for
To deploy your site:
- If you have not already, log in as or switch to the file system owner.
- Change to your project root directory.
Enter the following command:
php bin/magento setup:upgrade
We highly recommend having Adobe Commerce already installed if you followed the First time deployment. If you have not installed the Adobe Commerce application yet, use the
magento setup:installcommand instead. Be advised, you may encounter issues with enabled modules on a fresh installation.
Clean the cache:
php bin/magento cache:clean
Set the application for production mode:
php bin/magento deploy:mode:set production