{{last_updated_at}} by {{last_updated_by}}

Backdrop Configuration Management¶

• Table of contents
• Backdrop Configuration Management
  • • Structure of config directory:
    • Update settings.php to point at these directories:
  • Syncing configuration changes from one environment to another
  • Checking for updates to the canonical configuration
  • Selectively importing/exporting configurations
    • Ignoring dev-only modules:
• Ignore annoying config files for modules that differ between environments
• Ignore dev-only modules altogether

Structure of config directory:¶

Create the following folders:

<webroot>/config/versioned
<webroot>/../config/active
<webroot>/../config/staging

Update settings.php to point at these directories:¶

$config_directories['sync'] = '../config/staging';
$config_directories['active'] = '../config/active';
$config_directories['versioned'] = 'config/versioned';

Syncing configuration changes from one environment to another¶

In this example, we are syncing configuration from the local environment to the dev environment, which houses the canonical database that cannot be simply overwritten.

• local: Overwrite versioned directory with active (deletions too!): rm -rf config/versioned && cp -av config/active config/versioned
• local: Add the changes in config/versioned, commit, push to hub
• dev: Pull changes from hub. From here, you can either overwrite the database on the site you're updating, or, if you can't do that because you want to preserve the target database (e.g. when moving configuration changes to the canonical database that cannot be overwritten), you can sync the configuration via the following steps.
• dev: overwrite staging directory with versioned: rm -rf config/staging && cp -av config/versioned config/staging
• dev: run drush updb to run any database updates necessitated by the code you've pulled down from hub.
• dev: Go to the Configuration management admin page at /admin/config/development/configuration, where you'll see the new configurations (configurations that are not yet present on your current site at all); the changed configurations (which exist on your site but differ from the staging configuration that you copied over from the versioned config); and the removed configurations, indicating elements that have been removed entirely from the versioned configuration. # dev: after reviewing the changes that will be made to your current environment's configuration, you can click the "IMPORT ALL" button at the bottom of the Configuration management admin page.

Checking for updates to the canonical configuration¶

Follow these steps to check for updates to Backdrop site configuration on the "canonical environment":https://hq.palantetech.coop/projects/pt/wiki/Git_Workflows_and_Environment_Protocols#Environments that have not yet been committed to git.

From the root directory of the canonical environment:

rm -rf config/versioned && cp -a ../config/active config/versioned
git status

If git reports that there is nothing to commit and the working directory is clean, then no changes have been made to the active configuration on the canonical environment that need to be committed to git. If there are changes to commit, you'll be able to easily tell whether there are new, changed or deleted configurations to be committed to git.

h2. Configuration sync failures & possible solutions

When a Backdrop configuration sync fails, it fails completely; even if there is only one error reported with a single configuration, none of the other configuration additions, changes or deletions will have been imported.

At this point, the easiest option is usually to overwrite the database of the environment you're trying to update with the canonical database; this is usually the best and quickest option when you're updating your local site and don't need to preserve any local development that hasn't already been exported into configuration and committed to git. However, if you can't overwrite the database for some reason--you can't lose content that's in there, or it's the canonical database--you'll need to either remove the configuration file in question (see below) or resolve the sync errors before proceeding with the import.

Here are some configuration sync errors we've encountered and possible solutions:

The content type "post" cannot be deleted with active content associated to it. Delete the content manually, then retry the import.

Fairly self-explanatory: you either need to delete all nodes of content type post or somehow migrate them to a different content type, then run the import again.

The configuration "<module>.<configuration_file_name>" is not owned by any module. Try enabling the module that provides this configuration, then importing again.

This most commonly occurs when a module has been added and enabled in one environment but not another. Enable the module (currently only possible via the Backdrop UI, not using Drush) and try the import again.

However, this can unfortunately also occur when a given configuration file, such as addanother.news, comes alphabetically before another upon which it depends, in this case node.type.news. In that occurrence, your only options are to either overwrite the entire database or, if that's not possible, manually move configuration files around between configuration folders and import in stages. This is probably a bug, I just don't have time to report it!--JA 8/3/16

Example: commands I used to deal with the situation above, from within the Backdrop root on my local environment:

rm -rf config/staging && cp -av config/versioned config/staging
mkdir config/newstemp
mv config/staging/*news* config/newstemp
mv config/newstemp/node.type.news.json config/staging
[ran the import via the UI once]
rm -rf config/staging && cp -av config/versioned config/staging
[ran the import via the UI a second time, this time with far fewer configurations to import]

Also see https://hq.palantetech.coop/issues/26794#note-9 for troubleshooting of a somewhat similar situation on the Woolman dev site.

Selectively importing/exporting configurations¶

Because config files are labeled in easily readable ways, e.g. field.instance.node.post.field_image and node.type.post, you can pick and choose which configuration elements to synchronize and which to leave out via the filesystem. If for some reason there are certain elements that you don't want to sync after reviewing them on the configuration management admin page, you can copy those specific files from config/active to config/staging, effectively ignoring what you'd copied earlier from config/versioned. (At that point, though, you might wonder whether you should have skipped committing those particular changes to config/versioned at all!

Ignoring dev-only modules:¶

Ignore module enabled/disabled status by adding lines like these to drush/drushrc.php:

$command_specific['config-export']['skip-modules'] = array('devel', 'stage_file_proxy');
$command_specific['config-import']['skip-modules'] = array('devel', 'stage_file_proxy');

Ignore the actual module code and settings file via .gitignore, if desired:

Ignore annoying config files for modules that differ between environments¶

system.menu.devel.yml
stage_file_proxy.settings.yml

Ignore dev-only modules altogether¶

modules/stage_file_proxy