Overview of configuration management

In 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 app/etc/config.local.php.

    config.local.php is a convenient way to move settings between systems. Managing config.local.php in 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 file optimization means merging and minifying JavaScript and Cascading Style Sheets, and minifying HTML templates.)

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 config.local.php.

Configuration settings locked in the Magento Admin

Settings in 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 magento-cloud-configuration.

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.

Using 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.

How configuration variable values are determined

As the diagram shows, we get configuration values in the following order:

  1. From an environment variable.

    Environment variables, if they exist, override all other values.

  2. From config.local.php.

    Values in config.local.php override settings in the database.

  3. 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.

Overview of Cloud configuration management

Our recommended method relies on the following important points:

  • Do all of your configuration in your integration system’s master branch; the master branch is your “source of truth” for configuration management.
  • Transfer those settings using config.local.php to 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 master branch.

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.

  1. Generate config.local.php on your integration server’s master branch.
  2. Transfer config.local.php to your local system using rsync or scp so you can add it to Git.
  3. Add config.local.php to Git (again, in the master branch).
  4. Push config.local.php to your integration server.

You generate config.local.php using 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:

  1. Delete config.local.php on 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.php on the integration server to be able to change the store name again.

  2. Make configuration changes in the Admin on the integration server.
  3. Re-create config.local.php and 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.

Next step

Example of managing system-specific settings