Moving Configurations between Environments

Because many configurations of your site are part of its functionality, it is necessary to know how to move them between environments, especially to avoid overwriting the database once your site is published, so I'm going to tell you the basics and some recommendations that can help you in the process.

Defining a directory for Drupal to store your configurations

Before you can export and import configurations, we must define the destination directory for all configuration files.

In our famous file settings.php find the line that contains 'config_sync_directory' and define a directory, in my case I usually use '../config', so I create this directory as a sibling of web and vendor. So it should be like this:

$settings['config_sync_directory'] = '../config';

Drush commands you'll need:

drush cex

This is the command you should use from your local environment to export all changes you've made.

drush cim

This command will import all configurations.

Some recommendations

• Before the first commit, it's important to export the configuration and add it to your repository.
• In many cases, you won't upload your site to test or production environments until some things are working, so the first time you take that configuration, you could load a copy of your local database or use the Drush installation command with the existing-config parameter.
• Make it a habit to export your configuration and review the changes you need when you're about to add new functionality to your site.
• As part of your continuous integration system, add the command to import configurations, in some cases more than once, because of the interdependence of some configurations, which changes their order of import, and this can cause some not to import at the first attempt.
• When working with a team, make sure to import the configuration before starting to work on something new, which will prevent your local environment from falling behind in changes, and when exporting, it will generate configurations that undo someone else's work.

Ignoring some modules

There are modules that we don't want to have active in test or production environments, an example is the devel module, which we only use for development, in that case, Drupal allows us to avoid having these modules exported using an option in our settings.local.php file, but first, let's clear how to use that file.

In the web/sites directory, you'll find a file called example.settings.local.php this file need to be moved inside the web/sites/default directory with the name settings.local.php and add the following lines at the end of the file settings.php:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

This makes Drupal recognize the configurations that are in your settings.local.php file, once done, at the end of the file you'll find something like this commented out:

#$settings['config_exclude_modules'] = ['devel', 'stage_file_proxy'];

Uncomment that line and leave the modules that you want to ignore, this will not only ignore if they are active but also the entire configuration that comes with them.

Some strategies for handling sensitive information

Although many modules do not store sensitive information in the configuration, you will likely have situations where you want to prevent a piece of data from being exposed in a file in your repository, such as a username, API Key, etc.

The following are some strategies you can use:

A file with those configurations

Let's create a file secrets.settings.php and place it in an inaccessible location on our server, the content of this file should be the configurations you want to keep protected for example:

// Protected credentials.
$config['mi_modulo.settings']['api_username'] = 'mi usuario';
$config['mi_modulo.settings']['api_password'] = 'Mi Contraseña';

And at the end of the file settings.php we add these lines:

if (file_exists('/ruta-al-archivo/secrets.settings.php')) {
  include '/ruta-al-archivo/secrets.settings.php';
}

Environment Variables

Another way to do this is by using environment variables for these configurations directly in the file settings.php as I show below:

// Protected credentials.
$config['mi_modulo.settings']['api_username'] = getenv('NOMBRE_PROTEGIDO');
$config['mi_modulo.settings']['api_password'] = getenv('CONTRASEÑA_PROTEGIDA');

Conclusion

Although I didn't go into detail about other situations that may arise, this article gives you a starting point and some recommendations for managing the configuration of your site between environments.