DocumentationCommerceConfiguration Guide

Example using environment variables

Last update: Fri Apr 21 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin
  • Developer

This example shows how to set shared, system-specific, and sensitive values in your development system, then set all the values in your production system using a combination of the shared configuration, config.php, and PHP environment variables.

These configuration settings can be shared between the development and production systems:

VAT Number and Store Name from Stores > Settings > Configuration > General > General

These configuration settings are either system-specific or sensitive, as indicated:

  • Send Emails To (sensitive) from Stores > Settings > Configuration > General > Contacts
  • Default Email Domain (system-specific) from Stores > Settings > Configuration > Customers > Customer Configuration > Create New Account Options

You can use the same procedure to configure any settings in the following references:

Before you begin

Before you begin, set up file system permissions and ownership as discussed in Prerequisite for development, build, and production systems.

Assumptions

This topic provides an example of modifying the production system configuration. You can choose different configuration options if you wish.

For the purposes of this example, we assume the following:

  • You use Git source control
  • The development system is available in a Git remote repository named mconfig
  • Your Git working branch is named m2.2_deploy

Step 1: Set the configuration in the development system

To set the default locale and weight units in your development system:

  1. Log in to the Admin.

  2. Click Stores > Settings > Configuration > General > General.

  3. If you have more than one website available, use the Store View list in the upper left corner to switch to a different website as the following figure shows.

    Switch websites

  4. In the right pane, expand Store Information.

  5. If necessary, clear the Use Default checkbox next to the VAT Number field.

  6. Enter a number in the field (for example, 12345).

  7. In the Store Name field, enter a value (like My Store).

  8. Click Save Config.

  9. Use the Store View list to select the Default Config as the following figure shows.

    Switch to the default config

  10. In the left navigation, under General, click Contacts.

  11. Clear the Use Default checkbox next to the Send Emails To field.

  12. Enter an e-mail address in the field.

  13. Click Save Config.

  14. In the left pane, click Customers > Customer Configuration.

  15. In the right pane, expand Create New Account Options.

  16. Clear the Use system value checkbox next to the Default Email Domain field.

  17. Enter a domain name in the field.

  18. Click Save Config.

  19. If prompted, flush the cache.

Step 2: Update the configuration

Now that you have changed the configuration in the Admin, write the shared configuration to a file as discussed in this section.

To update the configuration:

  1. Log in to your development system as, or switch to, the file system owner.

  2. Change to the application root and run the dump command.

    code language-bash 
    cd <Magento root dir>
php bin/magento app:config:dump

    For example, if Commerce is installed in /var/www/html/magento2, enter:

    code language-bash 
    cd /var/www/html/magento2
php bin/magento app:config:dump

  3. Confirm that app/etc/config.php was updated.

    code language-bash 
    git status

    Sample response:

    code language-none 
    On branch m2.2_deploy
Changed but not updated:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
       modified:   app/etc/config.php
    note warning
    WARNING
    Do not submit changes to the generated, pub/media, or pub/static directories to source control. You generate those files on your build system. The development system likely has code, themes, and so on, that are not ready for use on the production system.

  4. Check in your changes to app/etc/config.php only to source control.

    code language-bash 
    git add app/etc/config.php && git commit -m "Updated shared configuration" && git push mconfig m2.2_deploy

Note that even though app/etc/env.php (the system-specific configuration) was updated, do not check it in to source control. You will create the same configuration settings on your production system later in this procedure.

Step 3: Update your build system and generate files

Now that you have committed your changes to the shared configuration to source control, you can pull those changes in your build system, compile code, and generate static files. The last step is to pull those changes to your production system.

To update the build system:

  1. Log in to the build system as the file system owner.

  2. Change to the application root directory.

    code language-bash 
    cd <Magento root dir>

  3. Pull the changes to app/etc/config.php from source control.

    code language-bash 
    git pull mconfig m2.2_deploy

  4. Compile code.

    code language-bash 
    bin/magento setup:di:compile

  5. After code has been compiled, generate static view files.

    code language-bash 
    bin/magento setup:static-content:deploy -f

  6. Check the changes into source control.

    code language-bash 
    git add -A && git commit -m "Updated files on build system" && git push mconfig m2.2_deploy

Step 4: Update the production system

The last step in the process is to update your production system. You must do it in two parts:

  • Update the sensitive and system-specific settings
  • Update the shared settings

Update the sensitive and system-specific settings

To set the sensitive and system-specific settings using environment variables, you must know the following:

  • Scope for each setting

    If you followed the instructions in Step 1, the scope for Send Emails To is global (that is, the Default Config scope) and the scope for Default Email Domain is website.

    You must know the website’s code to set the Default Email Domain configuration value. See Use environment variables to override configuration settings for more information on finding it.

  • Configuration path for each setting

    The configuration paths used in this example follow:

    table 0-row-2 1-row-2 2-row-2
    Setting name Configuration path
    Send Emails To contact/email/recipient_email
    Default Email Domain customer/create_account/email_domain

    You can find all sensitive and system-specific configuration paths in Sensitive and system-specific configuration paths reference.

Convert configuration paths to variable names

As discussed in Use environment variables to override configuration settings, the format of variables is:

<SCOPE>__<SYSTEM__VARIABLE__NAME>

The value of <SCOPE> is CONFIG__DEFAULT__ for global scope or CONFIG__WEBSITES__<WEBSITE CODE> for website scope.

To find the value of <SYSTEM__VARIABLE__NAME>, replace each / character in the configuration path with two underscores.

The variable names follow:

Name
Config path
Variable name
Send Emails To
contact/email/recipient_email
CONFIG__DEFAULT__CONTACT__EMAIL__RECIPIENT_EMAIL
Default Email Domain
customer/create_account/email_domain
CONFIG__WEBSITES__BASE__CUSTOMER__CREATE_ACCOUNT__EMAIL_DOMAIN
INFO
The preceding table has a sample website code, BASE, for the Default Email Domain configuration setting. Replace BASE with the appropriate website code for your store.

Set the variables using environment variables

You can set the variable values in the index.php using the following format:

$_ENV['VARIABLE'] = 'value';

To set variable values:

  1. Log in to your production system as, or switch to, the file system owner.

  2. Open <Commerce root dir>/pub/index.php in a text editor.

  3. Anywhere in index.php, set values for the variables similar to the following:

    code language-php 
    $_ENV['CONFIG__DEFAULT__CONTACT__EMAIL__RECIPIENT_EMAIL'] = 'myname@example.com';
$_ENV['CONFIG__WEBSITES__BASE__CUSTOMER__CREATE_ACCOUNT__EMAIL_DOMAIN'] = 'magento.com';

  4. Save your changes to pub/index.php and exit the text editor.

  5. Continue with the next section.

Update the shared settings

This section discusses how to pull all the changes you made on your development and build systems, which updates the shared configuration settings (Store Name and VAT Number).

To update the production system:

  1. Log in to the production system as the file system owner.

  2. Change to the application root and enable maintenance mode.

    code language-bash 
    cd <Magento root dir>
    code language-bash 
    bin/magento maintenance:enable

    For additional options, such as the ability to set an IP address whitelist, see magento maintenance:enable.

  3. Stop any running queue workers by setting cron_run to false in app/etc/env.php as follows:

    code language-php?start_inline=1 
    'cron_consumers_runner' => [
        'cron_run' => false
    ]

  4. Update the configuration.

    code language-bash 
    bin/magento app:config:import

  5. Finally, kill any active consumer processes.

    code language-bash 
    kill <PID>

    Where PID is the process ID to be killed, for example:

    code language-bash 
    kill 1234

  6. Pull code from source control.

    code language-bash 
    git pull mconfig m2.2_deploy

  7. Update the configuration.

    code language-bash 
    bin/magento app:config:import

  8. Clean the cache.

    code language-bash 
    bin/magento cache:clean

  9. End maintenance mode.

    code language-bash 
    bin/magento maintenance:disable

Verify configuration settings in the Admin

This section discusses how you can verify the configuration settings in your production system Admin.

To verify the configuration settings:

  1. Log in to your production system’s Admin.

  2. Click Stores > Settings > Configuration > General > General.

  3. Use the Store View list in the upper left corner to switch to a different website.

    The shared configuration options you set in the development system are displayed similar to the following.

    Check settings in the production system

    note info
    INFO
    The Store Name field is editable in the website scope but if you switch to the Default Config scope, it is not editable. This is the result of how you set the options in the development system. The value of VAT Number is not editable in website scope.

  4. If you have not already done so, switch to Default Config scope.

  5. In the left navigation, under General, click Contacts.

    The Send Emails To field is not editable, as the following figure shows. This is a sensitive setting.

    Check settings in the production system

  6. In the left pane, click Customers > Customer Configuration.

  7. In the right pane, expand Create New Account Options.

    The value of the Default Email Domain field is displayed as follows. This is a system-specific setting.

    Check settings in the production system

recommendation-more-help
386822bd-e32c-40a8-81c2-ed90ad1e198c