Project

General

Profile

Backdrop Configuration Management » History » Version 2

Jon Goldberg, 01/04/2018 02:33 AM

1 1 Jon Goldberg
{{last_updated_at}} by {{last_updated_by}}
2
# Backdrop Configuration Management
3
{{>toc}}
4
5
6
### Structure of config directory:
7
8
Create the following folders:
9
10
~~~
11
<webroot>/config/versioned
12
<webroot>/../config/active
13
<webroot>/../config/staging
14
~~~
15
16
### Update settings.php to point at these directories:
17
18
~~~
19
$config_directories['sync'] = '../config/staging';
20
$config_directories['active'] = '../config/active';
21
$config_directories['versioned'] = 'config/versioned';
22
~~~
23
24
## Syncing configuration changes from one environment to another
25
26
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.
27
28
* `local`: Overwrite versioned directory with active (deletions too!): `rm -rf config/versioned && cp -av config/active config/versioned`
29
* `local`: Add the changes in `config/versioned`, commit, push to hub
30
* `dev`: Pull changes from `hub`.
31
_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._
32 2 Jon Goldberg
* `dev`: overwrite staging directory with versioned: `rm -rf ../config/staging && cp -a config/versioned ../config/staging`
33 1 Jon Goldberg
* `dev`: run `drush updb` to run any database updates necessitated by the code you've pulled down from `hub`.
34
* `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.
35 2 Jon Goldberg
36 1 Jon Goldberg
# `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.
37
38
## Checking for updates to the canonical configuration
39
40
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.
41
42
From the root directory of the canonical environment:
43
44
~~~bash
45
rm -rf config/versioned && cp -a ../config/active config/versioned
46
git status
47
~~~
48
49
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.
50
51
h2. Configuration sync failures & possible solutions
52
53
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.
54
55
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.
56
57
Here are some configuration sync errors we've encountered and possible solutions:
58
59
`The content type "post" cannot be deleted with active content associated to it. Delete the content manually, then retry the import.`
60
61
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.
62
63
`The configuration "<module>.<configuration_file_name>" is not owned by any module. Try enabling the module that provides this configuration, then importing again.`
64
65
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.
66
67
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_
68
69
Example: commands I used to deal with the situation above, from within the Backdrop root on my local environment:
70
71
~~~bash
72
rm -rf config/staging && cp -av config/versioned config/staging
73
mkdir config/newstemp
74
mv config/staging/*news* config/newstemp
75
mv config/newstemp/node.type.news.json config/staging
76
[ran the import via the UI once]
77
rm -rf config/staging && cp -av config/versioned config/staging
78
[ran the import via the UI a second time, this time with far fewer configurations to import]
79
~~~
80
81
Also see https://hq.palantetech.coop/issues/26794#note-9 for troubleshooting of a somewhat similar situation on the Woolman dev site.
82
83
## Selectively importing/exporting configurations
84
85
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!
86
87
### Ignoring dev-only modules:
88
89
Ignore module enabled/disabled status by adding lines like these to drush/drushrc.php:
90
91
> $command_specific['config-export']['skip-modules'] = array('devel', 'stage_file_proxy');
92
> $command_specific['config-import']['skip-modules'] = array('devel', 'stage_file_proxy');
93
94
Ignore the actual module code and settings file via .gitignore, if desired:
95
96
> # Ignore annoying config files for modules that differ between environments
97
> system.menu.devel.yml
98
> stage_file_proxy.settings.yml
99
100
> # Ignore dev-only modules altogether
101
> modules/stage_file_proxy