As a best practice for managing your code and updating your live site and stores, we strongly recommend following a development and deployment process. This process includes at a minimum developing code in code branches, using a testing or staging server, deploying to staging and testing, then finally deploying to production and testing.
Depending on your environments and Magento version, you may have additional best practices, recommended, or required steps. This article walks through the general processes and provides additional in-depth links for more information in DevDocs.
Environment and technologies
- Magento Commerce
- Magento Commerce (Cloud)
See the prerequisites and requirements per Magento version (select another version in DevDocs to review that information):
Magento Commerce deployment
We include a couple options for deploying your code for Magento Commerce based on the size of your environment.
For advanced deployment reducing downtime and ensuring consistent configurations across Magento environments, we recommend Pipeline Deployment (requires 2.2). We recommend this deployment method for anyone with a large site who does not want downtime during deployment.
- Development system: Machine on which developers work to customize code; and install extensions, themes, and language packages from Magento Marketplace. In addition, you make all configuration changes on your development system. You can have many development systems.
- Build system: One system on which you deploy static assets and compile code for your production system. Because you build these assets on a system not in production, your production system’s downtime is minimized. Your build system does not have to have Magento installed on it. It needs only the Magento code but no database connection is required. Also, your build system doesn’t need to be a physically separate server.
- Staging system: Optional. You can optionally set up a staging system to use for final testing of all integrated code, including User Acceptance Testing (UAT). Set up a staging system the same way you set up a production system. Except for the fact that staging is not your live store and doen’t process orders from customers, it’s identical to production.
- Production system: Your live store. You should make minimal configuration changes here and no changes to websites, stores, store views, products, or the catalog. You should make all those types of changes in your development system.
After you have modified your code and configured your system, you can use a command to generate a PHP file (
config.php) populated with all configuration information including modules, store configurations, sensitive data, and more.
You add the
config.php file to your Git branch for compiling through your build system. The code and configurations are then deployed to Staging (optional) and Production.
Once you have generated the file, and configuration included in the file is read-only through the Magento Admin.
To modify or remove existing settings, you need to manually edit the file, located at
app/etc/config.php. To add new configurations to the file, you can follow the steps to generate the file. New configurations are appended to the file.
Single Machine Deployment
For smaller merchant installations, we recommend single machine deployment. This process may incur a longer deployment and downtime process.
Magento Commerce (Cloud) deployment
Magento Commerce (Cloud) includes multiple environments for your Pro and Starter plans to best develop, test, and deploy your stores. You develop and test initially in your Integration environments. When code is ready for further "live" testing, you deploy to Staging, a pre-production environment with all Production services available. When all testing and UAT is complete, you can deploy to Production to complete go live steps.
All Cloud plans receive a set of environments for developing, testing, and going live. These environments are read-only, receiving deployed code from your local.
- Integration: The ultimate developer environments, Integration provides three testable environments. Each environment includes an active Git branch, database, web server, caching, services, environment variables, and configurations.
- Staging: We highly recommend you create an active staging branch as one of the three Integration environments. Create this branch directly from master. As code and extensions pass your tests, you can merge your Integration branches to staging. This Staging environment becomes your pre-Production testing environment. It includes the staging active branch, database, web server, caching, services, environment variables, configurations, and Production services like Fastly and New Relic.
- Production: When code is ready and tested, all code merges to master for deployment to the Production live site. This environment includes your active master Git branch, database, web server, caching, services, environment variables, and configurations. This environment includes additional services like Fastly.
- Integration: The ultimate developer environment, Integration provides eight testable environments including a master. Each environment includes an active Git branch, database, web server, caching, services, environment variables, and configurations. Actively develop, deploy, and test your code before merging to master to push to Staging.
- Staging: As code and extensions pass your tests, deploy the Integration master Git branch to Staging for pre-Production testing. This environment includes a database, web server, caching, services, environment variables, configurations, and Production services like Fastly and New Relic.
- Production: When code is ready and testing complete, deploy the Integration master Git branch into Production for your live store. The container includes a three node high-availability architecture for your data, services, caching, and store. This is your live, public store environment with environment variables, configurations, and Fastly.
For detailed information, see:
Cloud Development and Deployment
We highly recommend the following best practices and considerations for your deployment process:
- Always follow the deployment process to ensure your code is THE SAME in Integration, Staging, and Production. This is vital. Pushing code from Integration environments may become important or needed for upgrades, patches, and configurations. This deployment overwrites Production and any differences in code in that environment.
- Ensure that the upgrade was successfully executed on a local machine
- All 3rd party extensions are upgraded (if needed)
- All custom extensions are upgraded (if needed)
- Custom theme(s) are compatible with new version
- ALL FUNCTIONAL OR OTHER BUGS RELATED TO UPGRADED CUSTOM AND 3rd Party EXTENSIONS VERSIONS EXPECTED to be fixed and documented and well known, (so could be fixed immediately after upgrade) at this point
- Always add new extensions, integrations, and code in iterated branches to then build and deploy using the process. Some extensions and integrations must be enabled and configured in a specific order due to dependencies. Adding these in groups can make your build and deploy process much easier and help determine where issues occur.
- Enter the same variables environment-to-environment. The values for these variables may differ across environments, but the variables may be required for your code.
- Keep sensitive configuration values and data in environment-specific variables. This includes an env.php file, CLI-entered variables, and Project Web Interface-entered variables. The values can differ, but having the variables is important.
- Ensure all three nodes are accessible by SSH (production)
- Indexers are set to Update on Schedule
- There is available storage space (production)
- Check size of database (understand the expected size, is there enough allocated memory and storage in that partition?)
- Free up space in /log and /tmp directories prior to deploy (df -k to check for "close to full" partitions at a minimum)
- Assert DB Upgradeability (including 3rd party and custom tables/data)
- Ensure MySQL is up and running
- Assert system configuration static files validity and readiness for upgrade:
- If deploying static content, it is CRITICAL to follow these static content best practices:
- Assert composer.json file validity and readiness for upgrade
- Versions match what is actually installed (ElasticSearch)
- If deploying static content, it is CRITICAL to follow these static content best practices:
- Test your build and deploy locally and in Staging before deploying to Production. Extensions and custom code work great in development. Some users push to production only to have failures and issues. Staging gives you an opportunity to fully test your code and implementation in a production environment without extended downtime if something goes wrong in Production.
- Shared staging shares an Elasticsearch installation with Production, any change made will impact production
- Prepare production account instance for upgrade (may include setting env variables, backup prod DB, etc)
- Push the new version to GIT and perform upgrade on production environment
- Watch over the upgrade process and mitigate issues if needed
- Post upgrade tasks
- Assert all CRON jobs states. Re-run if needed
- Assert all indexers states. Re-run if needed
- Post-upgrade UAT and bug-fixing (if related to custom code or 3rd party)
For continuous integration, you can quickly follow this process and use features like Configuration Management (or Pipeline Deployment) to reduce deployment time (moving static content deploy to build phase) and ensure consistent configurations across environments.
Magento Commerce (Cloud):
- Starter architecture and deployment process content
- Pro architecture and deployment process content
- Deploy your store process, walk-through, and content from local to Integration to Staging and Production
- Go live content for launching
- Configuration Management (or Pipeline Deployment), requires 2.1.4 and later, 2.2 and later