Overview of configuration management
magento-cloud-configuration release 101.4.1 on Magento Enterprise Cloud Edition 2.1.4 and later, we provide the following improvements:
Better way to manage the configuration so your integration, staging, and production systems stay in synchronization with each other more easily.
Less time required to build and deploy your project by reducing the time required for static file deployment.
These new methods to manage your configuration are optional. You don’t have to use them, although we strongly recommend you do.
Managing the configuration
We make it easy to manage system-specific settings as follows:
- An improved method to manage system configuration settings (such as store locale settings and static file optimization settings) in a new configuration file,
app/etc/config.local.php, which is in source control.
System values related to static content deployment (for example, static file optimization) are also stored in
config.local.phpis a convenient way to move settings between systems. Managing
config.local.phpin source control means your settings for Integration, Staging, and Production environments are always consistent. For example, you can disable static file optimization in Integration but enable it in both Staging and Production. After initially setting up the configuration, you don’t need to touch it again because it’s in source control.
Static content deployment performance
If you have a
config.local.php, static files are deployed in the Magento Enterprise Cloud Edition build phase instead of in the deployment phase, which decreases the amount of time required to deploy changes to Cloud.
In other words, Cloud’s build phase is less time-consuming than deployment. Therefore, any change you make to your Cloud project deploys faster overall if there is a
config.local.php compared to having no
Configuration settings locked in the Magento Admin
config.local.php are not editable in the Magento Admin. This also helps keep your settings consistent across the integration, staging, and production systems.
How to get
magento-cloud-configuration release 101.4.1
Magento Enterprise Cloud Edition periodically provides patch releases in components like
To test and apply the patch, see Test general patches.
Manage your configuration
Magento’s store configuration is located in the database and there is one database per system. This can make the configuration of multiple systems (such as staging and production) difficult.
Starting with version
magento-cloud-configuration release 101.4.1 on Magento Enterprise Cloud Edition 2.1.4, we store configuration values are specified in a new configuration file,
app/etc/config.local.php, which is in source control.
config.local.php, you can, for example, disable static file optimization in your integration system (where you are developing and testing) and enable static file optimization in staging and production.
The following sections provide more detail.
Example of managing system-specific settings
System settings refer to the configuration in the Magento Admin in Stores > Settings > Configuration. A list of settings can be found in Configuration settings you can change.
To enable you to set system settings, we use the following override scheme.
As the diagram shows, we get configuration values in the following order:
From an environment variable.
Environment variables, if they exist, override all other values.
config.local.phpoverride settings in the database.
From the database.
If no value exists in any of those sources, we use either the default value or NULL.
For an example of how this works, see Example of managing system-specific settings.
Recommended procedure to manage your settings
Managing store configuration is a complex task that’s mostly up to you. What locales do you want to use? What custom themes do you need? Only you can determine the answers to those questions.
We can, however, help you manage those settings more easily. For example, suppose you want to change the default locale and also change a store’s static file optimization settings. Currently, the way you do that is to log in to the Admin on the integration server, save your settings, then (when testing is complete) manually change those settings in staging.
What if someone changes a setting in the staging Admin? You’ll have to go back and make the same change on integration; otherwise, next time you deploy to staging, the old settings are enabled.
Instead of doing that, we enable you to store your settings in
app/etc/config.local.php which is managed in Git. (Because there’s no Git user in integration, staging, or production, you must add the changes to
config.local.php in your local system and push it to the integration server.) In addition, any setting in
config.local.php is not editable in the Admin.
The following figure shows a high-level overview of this process.
Our recommended method relies on the following important points:
- Do all of your configuration in your integration system’s
masterbranch is your “source of truth” for configuration management.
- Transfer those settings using
config.local.phpto the other systems (local, staging, and production).
Step A. Create and configure stores and create
config.local.php in your integration system.
Step B. Push
config.local.php to your integration server’s
The following procedure is required because there is no Git user on your integration server so you can’t use Git commands there. Instead, you generate the configuration on the integration server and transfer it to your local machine where you can push it.
config.local.phpon your integration server’s
config.local.phpto your local system using
scpso you can add it to Git.
config.local.phpto Git (again, in the
config.local.phpto your integration server.
magento app:config:scd-dump, which populates
config.local.php with only the configuration values necessary for static content deployment..
Step C. Magento Enterprise Cloud Edition automatically deploys the settings to your integration server.
Step D. To change settings:
config.local.phpon your integration server.
You must delete it to be able to change the same settings again. In other words, if you changed the store name, that setting isn’t editable in the Admin. You must delete
config.local.phpon the integration server to be able to change the store name again.
- Make configuration changes in the Admin on the integration server.
config.local.phpand repeat Step B.
After you’ve configured the integration server and tested it thoroughly, see Overview of staging and production to start the process of migrating to a staging or production system.
We assume system settings are the same in staging and production.
If you choose to use different system settings in staging and production, you can manually edit
config.local.php, but that is beyond scope of this guide.