Backdrop Configuration Management » History » Revision 2

Revision 1 (Jon Goldberg, 01/04/2018 02:18 AM) → Revision 2/4 (Jon Goldberg, 01/04/2018 02:33 AM)

{{last_updated_at}} by {{last_updated_by}} 
 # Backdrop Configuration Management 

 ### Structure of config directory: 

 Create the following folders: 


 ### 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 config/staging && cp -a -av config/versioned ../config/staging` 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": 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 ``, comes alphabetically before another upon which it depends, in this case ``. 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/ 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 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. `` and ``, 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 
 > stage_file_proxy.settings.yml 

 > # Ignore dev-only modules altogether 
 > modules/stage_file_proxy