Configuration management, or Pipeline Deployment, provides a new way to deploy across your environments with minimal downtime. The process extracts all configuration settings from your Magento implementation into a single file. With this file, you can add it to your Git commit and push it across all of your environments. to keep consistent settings and reduce downtime.
For extensive technical information, see Pipeline Deployment. This section provides specific walk-throughs for Magento Commerce (Cloud) Starter and Pro environments.
It provides the following benefits:
- Better way to manage and synchronize the configuration across your development or Integration, Staging, and Production environments.
- Less time required to build and deploy your project by moving static file deployment from deploy to the build phase. Your site is in maintenance mode until deployment completes.
- Sensitive data is automatically added into and environment variables file (
/app/etc/env.php). You can also manually add sensitive environment variables using the Project Web Interface, the CLI, or directly in the Magento Admin. For example, payment processor passwords and API keys.
These new methods are optional but strongly recommended. The process ensures faster deployments and consistent configurations across your environments.
If you used configuration management in 2.1, this process is similar in 2.2. The name of the file has changed to
config.php and updating the file changed. You can migrate your
config.local.php settings to a new
config.php. This file includes a number of changes including:
- A list of modules
- Should not be deleted to regenerate
Configuration management was released in
magento-cloud-configuration 101.4.1 on Magento Commerce (Cloud) 2.1.4 and later. The options and functions differ in Magento Commerce (Cloud) 2.2. We provide recommendations for Magento Commerce (Cloud) deployments in this section.
To complete these configuration management tasks, you must have at a minimum a project reader role with environment administrator privileges.
How it works
Magento’s store configurations are stored in the database. When updating configurations in development/Integration, Staging, and Production environments, you would need to make those changes in the Magento Admin per environment. By using these commands, you generate a file, exporting all Magento configuration settings into a single text file:
After configuring your environment, generate the file using one of the following commands:
php vendor/bin/m2-ece-scd-dump: Recommended. Exports only modified configuration settings
php bin/magento app:config:dump: Exports every configuration setting, including modified and default settings
For Magento Commerce (Cloud), we do not recommend app:config:dump as this command pulls and locks all values as read-only. This will affect Fastly and other important modules.
Any data that exports to the file becomes locked. The corresponding field in the Magento Admin becomes read-only. This ensures consistent configurations as you push the file across all environments. And every time you run this command, any new configurations are appended to your config.php file. If you need to modify or delete an existing configuration, you must edit the file manually.
By using the
scd-dump command, you can configure only the settings you want copied across all environments. After you merge the code, you can configure additional settings in Staging and Production. For sensitive configurations, you can also add those settings to environment variables. For example, you may want to add different PayPal merchant account credentials for Staging (sandbox) and Production (live).
If sensitive data is found in your configurations, it is generated as environment variables to
env.php. This file remains in the environment and should not be added to your Git environment.
System settings refer to the configurations in the Magento Admin in Stores > Settings > Configuration. Depending on the command used, all or just modified system configurations save to the file.
This file can include all system configuration settings for stores, sites, extensions, and static file optimization settings. System values related to static content deployment (for example, static file optimization) are also stored in
Sensitive values are not stored in
app/etc/config.php. Any sensitive configurations should export to
app/etc/config.php during the
scd-dump process. You can also create environment variables using CLI commands or the Project Web Interface.
You can set any value using environment variables, but we recommend using environment variables for sensitive values.
Static content deployment performance
Depending on the size of your store, you may have a large amount of static content files to deploy. Normally, static content deploys during the deploy phase, which is in Maintenance mode. To move the deployment of static content to the build phase, generate the configuration file.
If you generate
config.php, the build and deploy hooks identify the file and deploy all static files during the build phase. This helps reduce the time spent in Maintenance mode during the deploy phase.
How we set configurations
All system settings are set according to 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.php. Values in
config.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.
Configuration settings you can change
The following table shows the configuration settings affected by the
bin/magento magento-cloud:scd-dump command. These are the configuration settings that you can manage in Git. If you use
php bin/magento app:config:dump, all settings are exported.
|Description||Path in Magento Admin (omitting Stores > Configuration)|
|Store locale||General > General, Locale Options > Locale|
|Static asset signing||Advanced > Developer, Static Files Settings > Static Files Signing|
|Server-side or client-side LESS compilation||Advanced > Developer, Frontend Developer Workflow > Workflow type|
|HTML minification||Advanced > Developer, Template Settings > Minify Html|
|CSS minification||Advanced > Developer, CSS Settings > Merge CSS Files and Minify CSS Files|
|Disable modules output||Advanced > Advanced > Disable Modules Output|
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 help you manage those settings more easily. For example, you may want to change the default locale and a store’s static file optimization settings, with different settings in Staging and Production. Instead of making these changes in every environment, use
We strongly recommend using
scd-dump to generate
config.php. This file includes only the settings you configured without locking all default values. It also ensures all extensions used in Staging and Production do not break due to read-only configurations, especially Fastly.
To fully understand the process, please see our extensive example.
The Starter plan environment high-level overview of this process:
The Pro plan environment high-level overview of this process:
Step 1: Configure your store
Complete all configurations for your stores in the Admin console:
Log into the Magento Adming for one of the environments:
- Starter: An active development branch
- Pro: The
masterenvironment in Integration
- Create and configure all store settings. These configurations do not include the actual products unless you plan on dumping the database from this environment to Staging and Production. Typically development databases don’t include your full store data.
Open a terminal on your local and use an SSH command to generate
/app/etc/config.phpon the environment:
ssh -k <SSH URL> "<Command>"
For example for Pro, to run the
scd-dump on Integration
ssh -k firstname.lastname@example.org "php vendor/bin/m2-ece-scd-dump"
Step 2: Transfer and add the file to Git
config.php to Git. To push this file to the
master Git branch, you need to complete a few extra steps because this environment is read-only.
config.phpto your local system using
scp. You can only add this file to the Git branch through your local.
rsync <SSH URL>:app/etc/config.php ./app/etc/config.php
Add and push
config.phpto the Git master branch.
git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master
Once this file is added to your code, you should not delete it. If you need to remove or edit settings, you must manually edit the file to make changes.
Step 3 & 4: Push Git branch to Staging and Production
Log into the Magento Admin in those environments to verify the settings. If you used
scd-dump, only configured settings display. You can continue configuring the environment if needed.
For Starter, when you push, the updated code pushes to the active environment. Merge the branch to Staging and finally
master for Production. Complete any additional configurations in Staging and Production as needed.
For Pro, when you push to the Git branch, the Integration
master environment updates. Deploy this branch to Staging and Production. Complete any additional configurations in Staging and Production as needed.
If you need to modify or remove any existing configuration settings in
config.php, you will need to modify the file manually with a text editor. After completing edits or removals, you can push it to Git to update.
To add new configurations, modify your environment through the Magento Admin panel and run the command again to generate the file. Any new configurations are appended to the code in the file. Push it to Git to update.
While you can manually edit
config.php in Staging and Production, we don’t recommend it. The file helps keep all of your configurations consistent across all of your environments.
You should never delete
config.php to rebuild it. Deleting the file can remove specific configurations and settings required for build and deploy processes.
Migrate config.local.php to config.php
If you upgrade to Magento Commerce (Cloud) 2.2 or later, you may want to migrate settings from
config.local.php to your new
config.php file. If the configuration settings in your Magento Admin match the contents of the file, you can follow the instructions to generate and add
If they differ, you can append content from
config.local.php to your new
- Follow instructions to generate the
config.phpfile using the recommended method.
config.phpand delete the last line.
config.local.phpand copy the contents.
- Paste the contents into
config.php, save, and complete adding it to Git.
- Deploy across your environments.
You only need to complete this migration once. When you need to update the file, you will always update the new