Backdrop Configuration Management¶
- Table of contents
- Backdrop Configuration Management
- 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
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 -a config/versioned ../config/staging
drush updbto run any database updates necessitated by the code you've pulled down from
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
stagingconfiguration that you copied over from the
versionedconfig); and the removed configurations, indicating elements that have been removed entirely from the
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.
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/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: