Store configuration management
The default configurations for your store are stored in a config.xml
for the appropriate module. When you change settings in the Commerce Admin or the CLI bin/magento config:set
command, the changes are reflected in the core database, specifically the core_config_data
table. These settings overwrite the default configurations stored in the config.xml
file.
Store settings, which refer to the configurations in the Admin Stores > Settings > Configuration section, are stored in the deployment configuration files based on the type of configuration:
app/etc/config.php
—configuration settings for stores, websites, modules or extensions, static file optimization, and system values related to static content deployment. See the config.php reference in the Configuration Guide.app/etc/env.php
—values for system-specific overrides and sensitive settings that should NOT be stored in source control. See the env.php reference in the Configuration Guide.
Configuration management provides a way to deploy consistent store settings across your environments with minimal downtime using Pipeline deployment. Adobe Commerce on cloud infrastructure project includes the build server, build and deploy scripts, and deployment environments designed with the pipeline deployment strategy in mind.
Configuration override scheme
All system configurations are set during build and deploy phases according to the following override scheme:
- If an environment variable exists, use the custom configuration and ignore the default configuration.
- If an environment variable does not exist, use the configuration from a
MAGENTO_CLOUD_RELATIONSHIPS
name-value pair in the.magento.app.yaml
file. Ignore the default configuration. - If an environment variable does not exist and
MAGENTO_CLOUD_RELATIONSHIPS
does not contain a name-value pair, remove all customized configuration and use the values from the default configuration.
To summarize, environment variables override all other values.
If the same setting is configured in multiple places, the application relies on the following configuration hierarchy to determine which value to apply to the environment :
Method
environment variables
.magento.app.yaml
variables
section of the .magento.app.yaml
file. Specify values here to ensure consistent configuration across all environments. Do not specify sensitive values in the .magento.app.yaml
file. See Application settings.app/etc/env.php
app:config:dump
command. Set the system-specific and sensitive values using environment variables or the CLI. See Sensitive data. The env.php
file is not included in source control.app/etc/config.php
app:config:dump
command. Shared configuration values are added to config.php
. Set shared configuration from the Admin or using the CLI. The config.php
file is included in source control.config.xml
config.xml
file for a module. If Adobe Commerce cannot find any value set by any of the preceding methods, it falls back to the default value, if set.Configuration dump
You can use the following ece-tools
command to generate a config.php
file that contains all the current store configurations:
./vendor/bin/ece-tools config:dump
The data “dumped” to the app/etc/config.php
file becomes locked, which means the corresponding field in the Commerce Admin becomes read-only. The config.php
file includes only the settings that you configure. It does not lock the default values. Locking only the values you update also ensures that all extensions used in the Staging and Production environments do not break due to read-only configurations, especially Fastly.
ece-tools config:dump
command does not retrieve detailed configurations for modules, such as B2B. If you need a comprehensive configuration dump, use the app:config:dump
command, but this command locks configuration values in a read-only state.Sensitive data
Any sensitive configurations export to the app/etc/env.php
file when you use the bin/magento app:config:dump
command. You can set sensitive values using the CLI command: bin/magento config:sensitive:set
. See Sensitive and environment-specific settings in the Commerce PHP Extensions guide to learn how to designate configuration settings as being sensitive or system-specific.
See a list of Sensitive or system-specific settings in the Configuration Guide.
SCD performance
Depending on the size of your store, you may have a large number of static content files to deploy. Normally, static content deploys during the deploy phase when the application is in Maintenance mode. The most optimal configuration is to generate static content during the build phase. See Choosing a deploy strategy.
If you have enabled Configuration Management after dumping the configurations, you should move the SCD_* variables from the deploy stage to the build stage to properly enable static content generation during the build phase. See Environment variables.
Before Configuration Management:
deploy:
CRON_CONSUMERS_RUNNER:
cron_run: true
consumers: []
SCD_STRATEGY: compact
SCD_MATRIX:
...
REDIS_USE_SLAVE_CONNECTION: 1
After enabling Configuration Management:
Move the SCD_* variables to the build stage:
deploy:
CRON_CONSUMERS_RUNNER:
cron_run: true
consumers: []
REDIS_USE_SLAVE_CONNECTION: 1
build:
SCD_STRATEGY: compact
SCD_MATRIX:
...
Procedure to manage your settings
The following illustrates a high-level overview of this process:
To configure your store and generate a configuration file:
-
Complete all configurations for your stores in the Admin for one of the environments:
- Starter: An active development branch
- Pro: An active branch in the integration environment
These configurations do not include the actual products unless you plan on dumping the database from this environment to Staging and Production environments. Typically, development databases do not include your full store data.
-
On your local workstation, change to your project directory.
-
Create a local dump of the remote database.
code language-bash magento-cloud db:dump
-
Add, commit, and push code changes to update a remote environment.
code language-bash git add app/etc/config.php
code language-bash git commit -m "Add system-specific configuration"
code language-bash git push origin <branch-name>
After the deployment is complete, log in to the Admin for the updated environment to verify the settings. Continue to merge any additional configurations to the Staging and Production environments, as needed.
Update configurations
When you modify your environment through the Admin and run the command again, new configurations are appended to the code in the config.php
file.
config.php
file in the Staging and Production environments, it is not recommended. The file helps to keep all configurations consistent across all environments. Never delete the config.php
file for rebuilding it. Deleting the file can remove specific configurations and settings required for build and deploy processes.Restore configuration files
Copies of the original app/etc/env.php
and app/etc/config.php
files were created during the deployment process and store in the same folder. The following shows the BAK (backup files) and PHP (original files) in the same app/etc
folder:
...
config.php.bak
di.xml
env.php.bak
vendor_path.php
config.php
db_schema.xml
env.php
...
Older configurations used the app/etc/config.local.php
file. See Migrate older configurations.
To restore configuration files:
-
On your local workstation, use SSH to log in to the remote project and environment.
code language-bash magento-cloud ssh
-
Verify the backup files location and availability.
code language-bash ./vendor/bin/ece-tools backup:list
Sample response:
code language-terminal The list of backup files: app/etc/env.php app/etc/config.php
-
Restore backup files.
code language-bash ./vendor/bin/ece-tools backup:restore
Migrate older configurations
If you upgrade to Adobe Commerce on cloud infrastructure 2.2 or later, you may want to migrate settings from the config.local.php
file to your new config.php
file. If the configuration settings in your Admin match the contents of the file, follow the instructions to generate and add the config.php
file.
If they differ, you can append content from the config.local.php
file to your new config.php
file:
-
Follow instructions to generate the
config.php
file. -
Open the
config.php
file and delete the last line. -
Open the
config.local.php
file and copy the contents. -
Paste the contents into the
config.php
file, save, and complete adding it to Git. -
Deploy across your environments.
You only complete this migration once. After migration, use the config.php
file.
Change locales
You can change your store locales without following a complex configuration import and export process, if you have SCD_ON_DEMAND enabled. You can update the locales using the Admin.
You can add another locale to the Staging or Production environment by enabling SCD_ON_DEMAND
in an integration branch, generate an updated config.php
file with the new locale information, and copy the configuration file to the target environment.
-
In the integration environment, enable the
SCD_ON_DEMAND
variable using the.magento.env.yaml
file. -
Add the necessary locales using your Admin.
-
Use SSH to log in to the remote environment and generate the
/app/etc/config.php
file containing all locales.code language-bash ssh <SSH-URL> "./vendor/bin/ece-tools config:dump"
-
Copy the new configuration file from the remote integration environment to your local environment directory.
code language-bash rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
-
Add, commit, and push code changes to update a remote environment.