Example of managing system-specific settings

Configuration management exports your configurations to a file for pushing across your environments. This file, config.local.php, keeps your configurations consistent across all environments, decreases downtime by moving static deploy to build, and much more. This information details an example for configuring your settings, exporting the file, and deploying it.

This example shows how to use the recommended procedure for managing the configuration:

  1. Enter your configurations in your Integration environment Admin panel.
  2. Create config.local.php and transfer it to your local system.
  3. Push config.local.php to the branch and Integration environment.
  4. Verify your settings are not editable in the Admin panel. Any configurations exported to config.local.php make those fields in the Admin panel read-only and disabled for edits.
  5. Update and modify configurations again in Integration and recreate the file to update in Git:
    1. Delete config.local.php on the Integration environment.
    2. Change configuration settings on the Integration environment.
    3. Re-create and push the updated config.local.php to the Integration environment.

For example, you may want to set the following settings:

  • Disable locale and static file optimization settings in your Integration environment
  • Enable static file optimization in Staging and Production environments
  • Configure Fastly in Staging and Production with specific credentials for each

Static file optimization means merging and minifying JavaScript and Cascading Style Sheets, and minifying HTML templates.

Prerequisites

To complete these configuration management tasks, you need the following:

  • Minimum a project reader role with environment administrator privileges
  • Magento Admin panel URL and credentials for Integration, Staging, and Production environments
  • Push all updated code to your Integration environment:

    • For Starter: To an Integration branch and environment
    • For Pro: To the Integration master branch and environment

Configure Magento through the Integration Admin panel

Log into the Magento Admin panel in Integration to modify configurations. For a list of settings, see List of system-specific configuration settings for details.

To change locale and static file optimization settings:

  1. Log in to the Integration environment Admin panel. You can access this URL through the Project Web Console.
  2. Navigate to Stores > Settings > Configuration > General > General.
  3. In the right pane, expand Locale Options.
  4. From the Locale list, change the locale. You can change it back later.

    Change the locale

  5. Click Save Config.
  6. In the left navigation pane, click Advanced > Developer.
  7. In the right pane, expand Template Settings.
  8. Clear the Use default value check box next to the Minify Html list.
  9. From the Minify Html list, click No.
  10. In the right pane, expand CSS Settings.
  11. From the Merge CSS Files list, click No.
  12. From the Minify CSS Files list, click No.

    Set static file optimization settings

  13. Click Save Config.
  14. If prompted, flush the Magento cache.
  15. Log out of the Magento Admin.

Export values and transfer config.local.php to your local system

This step creates and transfers the config.local.php configuration file on the Integration environment using a command you run on your local machine.

This procedure corresponds to step 2 in the recommended procedure. After you create config.local.php, transfer it to your local system so you can add it to Git.

To create and transfer config.local.php:

  1. On your local system, find the integration server’s SSH URL.

    magento-cloud environment:ssh --pipe
    
  2. Create config.local.php on the integration server.

    ssh -k <SSH URL> "php bin/magento magento-cloud:scd-dump"
    

    For example,

    ssh -k itnu84v4m4e5k-master-ouhx5wq@ssh.us.magentosite.cloud "php bin/magento magento-cloud:scd-dump"
    
  3. If you haven’t done so already, change to the project root directory.
  4. Transfer config.local.php to your local system.

    rsync <SSH URL>:app/etc/config.local.php ./app/etc/config.local.php
    

The following snippet from config.local.php shows an example of changing the default locale to en_GB and changing static file optimization settings:

 'general' =>
      array (
        'locale' =>
        array (
          'code' => 'en_GB',
          'timezone' => 'UTC',
        ),

        ... more ...

 'dev' =>
      'template' =>
        array (
          'allow_symlink' => '0',
          'minify_html' => '0',
        ),

        ... more ...

        'js' =>
        array (
          'merge_files' => '0',
          'enable_js_bundling' => '0',
          'minify_files' => '0',
        ),
        'css' =>
        array (
          'merge_css_files' => '0',
          'minify_files' => '0',
        ),

Push and deploy config.local.php to environments

Now that you’ve created config.local.php and transferred it to your local system, commit it to Git and push it to your environments. This procedure corresponds to step 3 and 4 in the recommended procedure.

The following command adds, commits, and pushes to master:

git add app/etc/config.local.php && git commit -m "Add system-specific configuration" && git push origin master

Complete code deployment to Staging and Production. For Starter, you push to staging and master branches. For Production, you will need to SSH into your environments and push. For details on deployment commands, see Deploy your store.

Wait for deployment to complete in all environments.

Verify your configuration changes

After you push config.local.php to your environments, any values you changed should be read-only in the Magento Admin. In this example, the modified default locale and static file optimization settings should not be editable in the Magento Admin. These configuration settings are set in config.local.php.

To verify your configuration changes:

  1. If you haven’t done so already, log out of the Magento Admin in one of the environments.
  2. Log back in to the Magento Admin.
  3. Click Stores > Settings > Configuration > General > General.
  4. In the right pane, expand Locale Options.

    Notice several fields cannot be edited, as shown in the following sample. These configuration settings are maintained by config.local.php.

    Can't edit certain values in the Admin

  5. In the left navigation pane, click Advanced > Developer.
  6. In the right pane, expand Template Settings, JavaScript Settings, and CSS Settings.

    Notice several fields cannot be edited, as shown in the following sample. These configuration settings are maintained by config.local.php.

    Can't edit certain values in the Admin

  7. Log out of the Magento Admin.

Change and update system-specific configuration settings

If you need to modify any of these settings and update config.local.php, you will need to delete the file, update configurations, generate the file, and push it to Git following the previous steps. For an overvidew, see the recommended procedure.

For this example, we’ll modify static file optimization settings.

Delete config.local.php on the Integration environment

Before you can change settings on the Integration environment, delete app/etc/config.local.php from that environment. With this file removed, all configuration settings are available to modify in the Admin.

To delete config.local.php:

  1. On your local system, make sure you’re on the master branch.
  2. SSH to the integration server:

    magento-cloud ssh
    
  3. Delete config.local.php.

    rm app/etc/config.local.php
    
  4. Close the SSH tunnel.

    exit
    

Change configuration values in Integration

To change values in the Integration environment Magento Admin:

  1. If you haven’t done so already, log out of the Integration Admin.
  2. Log in to the Integration Admin.

    For URL and credentials, see Find Admin login information.

  3. Click Stores > Settings > Configuration > Advanced > Developer.
  4. In the right pane, expand Template Settings.
  5. Clear the Use default value check box next to the Minify Html list.
  6. From the Minify Html list, click Yes.
  7. In the right pane, expand CSS Settings.
  8. From the Merge CSS Files list, click Yes.
  9. From the Minify CSS Files list, click Yes.

    Set static file optimization settings

  10. Click Save Config.
  11. If prompted, flush the Magento cache.
  12. Log out of the Magento Admin.

Generate a new version of config.local.php

To generate a new file:

  1. On your local system, find the integration server’s SSH URL.

    magento-cloud environment:ssh --pipe
    
  2. Create config.local.php on the integration server.

    ssh -k <SSH URL> "php bin/magento magento-cloud:scd-dump"
    

    For example,

    ssh -k itnu84v4m4e5k-master-ouhx5wq@ssh.us.magentosite.cloud "php bin/magento magento-cloud:scd-dump"
    
  3. If you haven’t done so already, change to the project root directory.
  4. Transfer config.local.php to your local system.

    rsync <SSH URL>:app/etc/config.local.php ./app/etc/config.local.php
    

Push the changes to Git

To push your changes, enter the following command:

git add app/etc/config.local.php && git commit -m "Add system-specific configuration" && git push origin master

Wait for deployment to complete.

Repeat the deployment process for pushing the code to all environments.