Drupal: Configuration Management

Configuration management involves exporting Drupal site configuration settings into yaml files that can then be captured in the site repository using Git. Those yaml files are then imported into the remote site, syncing that site's configuration with the instance they were exported from. 

This article will provide an overview and step by step instructions for managing configuration on the UMN Drupal Enterprise Platform.

In this article:

What is Configuration Management?

Configuration management refers to the process of syncing Drupal site configuration between different environments.

Drupal stores much of its structure inside the Database alongside its content. By exporting a site's configuration into the code, it will have its structure and functionality captured within the codebase repository. This gives one the advantage of having everything critical to the functioning of the site stored safely in Github. This will also allow one to deploy features that rely on both code and configuration seamlessly. 

Prerequisites

Drupal Enterprise

Configuration management is intended for Drupal Enterprise sites

Git

A basic working knowledge of the Git command line interface and a site repository on the UMN github enterprise instance.

Note: The OIT Drupal platform does not currently support site owners storing their site repositories on the UMN Github Cloud instance. We will send an announcement to our Drupal Enterprise Platform Google Group when that option becomes available. Presently, site owners must store their site repositories in the University On-Premise instance Github.umn.edu. 

Local dev environment (optional)

Using a local development environment is not required to use a configuration management workflow but it is highly recommended. Making configuration changes on one's local environment and then deploying those changes through configuration management is an ideal workflow. It is especially useful when multiple developers are working on the same site as it will expose conflicting configuration changes in version control. 

Overview of the workflow

When using this method for copying configurations, you overwrite the configurations for your production environment so it is important that you do not make configuration changes in your production environment.

The general workflow for making configuration changes to your drupal site if you are using local development (preferred):

  1. Sync your production configs with your repository 
  2. Make changes in your local environment
  3. Test the changes in your remote development environment
  4. Apply the changes to your production environment

If you are not using local development:

  1. Make the changes in your development environment
  2. Apply the changes to your production environment

Initial Setup

Setup your Local Environment to Work for Configuration Management

These steps assume that you are choosing to use the preferred method of using a local environment and that you have set up the local environment on your machine per OIT instructions.

  1. Navigate to the docroot/sites/default directory or your local environment
  2. Open the settings.php file in a text editor or in your IDE
  3. Add the following lines to the bottom of the file:

 if (file_exists($app_root . '/' . $site_path . '/settings.site.php')) {

   include $app_root . '/' . $site_path . '/settings.site.php';

 }

Set up Your Repository

  1. Get the site folder name for you site by logging into Drupal Management and noting the primary URL
  2. At the root of your site repository, create a file called settings.site.php
  3. In the settings.site.php, add this code, substituting {Primary URL} with the URL from step 1

<?php

 

/*

* Sync directory for configurations

*/

if (isset($_ENV['AH_SITE_ENVIRONMENT'])) {

  $settings['config_sync_directory'] = dirname(DRUPAL_ROOT) . '/docroot/sites/{Primary URL}/config/sync';

} else {

$settings['config_sync_directory'] = dirname(DRUPAL_ROOT) . '/docroot/sites/default/config/sync';

}

  1. Add and commit the settings.site.php file to your site repository

Working with Local Development

Sync Configs with Production

Before working with configurations, you need to sync your local site with production.  Do this step frequently to keep your local in sync with production.  This step needs to be done every time the Drupal Team announces the completion of an update.

  1. Go to Drupal Management
  2. Click the link to download your production database
  3. Go to your site repository (i.e. docroot/sites/default)
  4. In your local container, import your site database: ddev import-db --src=/path/to/your/database
  5. Clear the cache in your local container: ddev exec drush cr
  6. Export the configs from your local: ddev exec drush cex
  7. Add the configs to your repository: git add config/sync
  8. Commit the changes to your repository: git commit -m "Sync production changes into repository"

Adding Configuration Change to your Site Repository (Local Development)

Once you have made the changes to your local environment, you need to export and commit the changes to your site repository:

  1. Open your terminal and navigate to your local environment
  2. Navigate to the docroot/sites/default directory on your local environment
  3. Confirm you are on the correct branch
    1. Log into Drupal Management
    2. Navigate to your site
    3. Note the name of the branch under "Development branch/tag"
    4. Check your current branch
      git branch
    5. If you are not on the correct branch, change to the correct one
      git checkout {branch name}
  4. Export your configuration files
    ddev exec drush cex
  5. Review the list of changes to make sure it looks correct
    Example showing an output that lists Config and Operations changes
  6. Note: If you disabled simple saml or other modules, you should proceed with this step but note the configs related to them
  7. Use git status to review the  changes you made:
    Example using git status and outputting "changes not staged for commit" information and "Untracked files" information
     
  8. Use git checkout to restore configs, such as simplesaml,  that were changed for your local environment:
  9. Repeat steps 4 and 5 until the modified configs in your repository look correct
  10. When the configs are ready, use git add config/sync to add the changes to your repository
  11. Use git commit -m "{Appropriate Commit Message}" to  commit the changes
    Example results of commit -m "Add flower content type" and resulting output listing the changes commited
  12. Use git push origin {branch name} to push the changes to your repository
    Example of git push and resulting output information about the objects being enumerated, counted, compressed, and written
     

Applying changes to Remote Development Environment (Local Development)

It is important to confirm that the changes import correctly before you apply them to your production environment.

  1. Navigate to your site in Drupal Management
  2. Click the button to copy your production database to the development environment.  Note this will overwrite your development environment's database
    Copy PRD Database to DEV
  3. Click the button to deploy development code
    Deploy dev code
  4. Wait about 15 minutes to allow the database copy and deployment to complete
  5. Log into your remote development site
  6. Go to Configuration, then Development, then Configuration synchronization
  7. Review the new / changed configurations to confirm they are what you expect
    Synchronize tab with 7 new configurations listed
     
  8. If they are, click on Import All
  9. Confirm your changes are showing up correctly

Applying the configs to production

Once you have confirmed that the changes are showing up correctly, you should then move the changes into production.

  1. Merge your development configs with your production configs
    1. Log into Drupal Management
    2. Navigate to your site
    3. Note the name of the branch under "Production branch/tag" and "Development branch/tag"
    4. Check your current branch
      git branch
    5. If you are not on the production branch, change to the correct one
      git checkout {production branch name}
    6. Merge the development branch, git merge {development branch name}
    7. Push the changes, git push origin {production branch name}
  2. Submit a ticket to deploy the production code.  In the ticket, you may want to ask the support team to create a backup of your database.
  3. When the support team writes back that the deployment is complete, log into your production site
  4. Go to Configuration, then Development, then Configuration synchronization
  5. Review the new / changed configurations to confirm they are what you expect
    Synchronize tab with 7 new configurations listed
     
  6. If they are, click on Import All
  7. Confirm your changes are showing up correctly

Working with configuration management to sync remote environments

Exporting Configurations as a Zip file from a remote environment

Instead of exporting configuration from your local, you can export configuration from a remote environment into a downloadable zip file.  To do this:

  1. Log into your database of record (the one you want to build your configurations from)
  2. Go to Configuration, then Development, then Configuration synchronization, then Export
  3. Under the option for full archive, click Export. This will give you a zip file containing the configuration .yml files.
    Export tab, then Full archive tab, then Export button selected

Adding Configuration Change to your Site Repository (Remote Development)

Once you have made the changes to your remote development environment, you need to export and commit the changes to your site repository:

  1. Unzip the file that was exported from the remote site's configuration export UI. It will contain the site configuration .yml files.
  2. In your site repository, confirm that you are on the correct branch
    1. Log into Drupal Management
    2. Navigate to your site
    3. Note the name of the branch under "Development branch/tag"
    4. Check your current branch
      git branch
    5. If you are not on the correct branch, change to the correct one
      git checkout {branch name}
  3. Move all of the .yml files from the export into the config/sync directory
  4. Confirm that the correct files have changed
    git status
  5. Add the changes to your configurations to your site repository
    git add config/sync
  6. Commit the changes to your site repository
    git commit -m "{Appropriate Commit Message}"
  7. Push the changes to your remote repository
    git push origin {branch name}

General Tips & Common Pitfalls

Configuration management has many benefits but if one is not careful it can cause serious headaches for developers. Here are some general tips and common pitfalls to avoid.

Avoid configuration changes in Production

It is a good practice to avoid making configuration changes in a production environment. It is possible to misconfigure a production site to become unusable or break critical features. An ideal workflow is to export the configuration with the desired changes from one's local environment and then sync the remote environments with that exported configuration. One can then test those changes on the local and remote development environments before applying those changes to the production environment.

Pulling config changes from the remote repository before exporting your local changes causes problems

When you run a configuration export on your local machine it exports all configuration to the local config directory. So if you just pulled down changes from the remote repository you could wipe out that work when you export. Inversely when you import configuration it will wipe out any changes you have in your local Database. Detangling conflicting configurations when this happens can be cumbersome. Some guidelines to avoid this:

  • Always export your local configuration changes (if you have any) before pulling from the remote repository.
  • Always immediately import configuration changes into your local site after pulling from the remote repository.
  • Always pay attention to what is changing when running a configuration import or export.

Drupal Core and Module Updates Routinely Change Configuration Schema

It is common for configuration schemas to change for modules as they are updated. When those updates are applied the modules will programmatically adjust the configuration in the database to match the updated schema. This can create a situation where the updated schema changes exist in the database but not in the stored configuration files in the site repository. When one next imports the configuration from the site repository, they could overwrite the config changes needed for the updated modules and cause errors. Be cognizant of when updates were last deployed to the platform and when the last configuration export was made for your site.

Pay Attention to the Configuration Changes being Imported/Exported

When exporting or importing changes, always pay attention to the name of every configuration file being changed. If you see something you do not remember changing or that looks wrong then you may need to examine what you are doing. This will help prevent you from undoing previously done configuration work.

Last modified

TDX ID

7331