Using the Configuration Verifier
Adding the Configuration Verifier to a project
The following step typically only has to be done once per project.
Bloomreach Experience Manager projects are expected to use the com.onehippo.cms7:hippo-cms7-enterprise-release parent pom, and as of version 12.0.2, the parent pom provides a custom Maven profile add-configuration-verifier, which can be executed to generate a custom Maven pom.xml, by default named configuration-verifier-pom.xml, and its accompanying configuration file configuration-verifier-config.yaml to the project.
Execute the following command from the project root folder:
mvn -N -P add-configuration-verifier
Make sure to provide the -N (--non-recursive) parameter otherwise the configuration verifier pom and config files also will be added to your sub modules!
Optionally, a runtime parameter -DverifierName may be specified to customize the (prefix) name of the files generated, e.g. executing:
mvn -N -P add-configuration-verifier -DverifierName=my-verifier
will generate the files my-verifier-pom.xml and my-verifier-config.yaml instead.
The generated configuration-verifier-pom.xml will use the current Maven pom.xml as parent pom, with the same Maven coordinates (including its version), thereby inheriting all the project specific configurations including its profiles, like the cargo.run profile. This allows it to be used as a custom Maven pom.xml through which the cargo.run profile as setup for the project can be executed as expected, with some customizations of its own.
Executing the Configuration Verifier
Running CV is done by executing the Maven cargo.run profile via the configuration-verifier-pom.xml instead of the standard pom.xml:
mvn -f configuration-verifier-pom.xml -P cargo.run
This will start Tomcat with only the cms.war deployed together with the hippo-enterprise-configuration-management-verifier-<version>.jar and the hippo-enterprise-repository-engine-<version>.jar. These jars and their versions are dependency managed by the com.onehippo.cms7:hippo-cms7-enterprise-release project parent pom.
If the Hippo Repository (database) to be used is already properly indexed, running CV typically only takes a few seconds, after which the process automatically terminates (unlike the normal execution of the cargo.run profile).
CV uses two additional parameters, and its processing can be further customized with the configuration-verifier-config.yaml file.
In the configuration-verifier-pom.xml the following two system parameters are pre-defined in the cargo.run profile, and passed on to CV:
- repo.verify.configuration.configfile=${project.basedir}/configuration-verifier-config.yaml
This (optional) parameter is used to tell CV where to find its (YAML) configuration file.
- repo.verify.configuration.exportpath=${project.basedir}/configuration-verifier-output
This parameter defines the folder location where CV will generate its configuration delta output (if any).
In general, we advise not to modify the upgrade-verifier-pom.xml (as a standard provided and generated file) to override these parameters, but instead redefine them if needed on the Maven command line using -Dparameter=value.
Configuring the Repository (database)
Using a development Repository database
By default, CV will verify the current project configuration against the current configured Hippo Repository (development) database.
That can be useful during development to verify configuration changes, before having them applied, since the last execution of the cargo.run profile.
Or when using the default (embedded) h2 database: a different repo.path parameter can be specified when invoking CV to use the database (storage folder) of a previous cleanly bootstrapped development version of the project, to verify the changes on bootstrap configurations only.
Using a production Repository database
To verify what configuration changes an updated or upgraded project will produce when released to production, first a copy (recent backup) of the Repository production database needs to be setup and configured locally. This effort is beyond the scope of this document, but as a best practice or guideline, you can follow the instructions for Use MySQL in a Development Environment.
When working with two different databases (local development and production) and two different repository storage folders as pointed at by the repo.path parameter, we advise to define two additional Maven profiles for the project, for example mysql-dev and mysql-prod, each configuring a different database connection and different repo.path parameter to be used.
Setup this way, cargo then can be executed for regular development with:
mvn -P cargo.run,mysql-dev
and CV can be executed against the production database with:
mvn -f configuration-verifier-pom.xml -P cargo.run,mysql-prod
Configuring the Configuration Verifier
When executing CV, it uses configuration from configuration-verifier-config.yaml, which by default looks like:
config:
export:
ignorepaths:
# - /some/path/with/delta/which/can/be/ignored
# - /another/path/with/delta/which/can/be/ignored
filteruuidpaths:
# - /some/path/for/which/uuid/export/should/be/ignored
# - /another/path/for/which/uuid/export/should/be/ignored
path-prefix-source-mapping:
# /hst:hst/hst:sites: upgrade-delta-hst.yaml
# /hst:hst/hst:configurations: upgrade-delta-hst.yaml
Instead, the above examples for the path-prefix-source-mapping configuration should be replaced with:
# /hst:hst/hst:sites: hst # /hst:hst/hst:configurations: hst
ignorepaths
When CV checks for possible differences between the new configuration and the existing data in the Hippo Repository, it skips a few hard-coded paths, as well as any path configured through the ignorepaths in configuration-verifier-config.yaml.
The hard-coded paths (path prefixes) excluded by CV are:
- /jcr:system - /hippo:log - /content/attic - /formdata - /webfiles - /hippo:configuration/hippo:initialize - /hippo:configuration/hippo:update/hippo:queue - /hippo:configuration/hippo:update/hippo:history - /hippo:configuration/hippo:update/jcr: - /hippo:configuration/hippo:temporary - /hippo:configuration/hippo:modules/brokenlinks - /hst:hst/hst:channels
For the initial usage of CV, the ignorepaths in configuration-verifier-config.yaml should be (reset to) empty, to get a first ‘raw’ report of detected deltas.
Then, after reviewing and resolving the deltas (see Resolving Configuration Verifier Deltas) they may either:
- Need to be solved/fixed by changes in the project configuration (in case the difference is undesired or non-intended) so that a subsequent execution of CV will no longer report these
- Are expected, intended or otherwise acceptable changes, so no longer need to be reported (unnecessary noise) by a subsequent execution of CV. The delta path can be added to the ignorepaths in configuration-verifier-config.yaml, typically accompanied with a comment explaining why.
filteruuidpaths
CV always ignores a difference between a jcr:uuid specified through the hippo-cms product configuration (group: hippo-cms) and the actual value in the Hippo Repository, as well as jcr:uuid properties defined only in the Hippo Repository (those cannot be modified or removed without removing the mix:referenceable mixin defining that property from its node).
But as a specific jcr:uuid value, unless explicitly referenced elsewhere, typically does not need to be explicitly configured, it can be useful and even better to filter them out from the CV delta reporting through the filteruuidpaths configuration.
This serves the same purpose as the filteruuidpaths configuration used by AutoExport. Note that filteruuidpaths, as with AutoExport, are used as path prefixes.
So for example configuring /hst:hst as a filteruuidpath will filter out all jcr:uuid properties for all /hst:hst nodes. Which actually is the (only) default and predefined filteruuidpaths used by CV already.
path-prefix-source-mapping
When CV detects a difference between the new configuration and the existing data in the Hippo Repository, it will report for each difference a delta definition (see: Configuration Verifier Delta Format). The delta definitions are reported in YAML source files based on the delta definition path. CV uses a default mapping which groups specific paths to a specific source file postfix, producing YAML source files in the CV output folder using the following source file name pattern: config-delta-<postfix>.yaml
The default provided path prefix to source mapping used by the CV is the following:
/hippo:configuration/hippo:frontend: frontend # file: config-delta-frontend.yaml /hippo:configuration/hippo:modules: modules # file: config-delta-modules.yaml /hippo:configuration/hippo:queries: queries # file: config-delta-queries.yaml /hippo:configuration/hippo:documents: queries # idem /hippo:configuration/hippo:security: security # file: config-delta-security.yaml /hippo:configuration/hippo:domains: security # idem /hippo:configuration/hippo:groups: security # idem /hippo:configuration/hippo:roles: security # idem /hippo:configuration/hippo:users: users # file: config-delta-users.yaml /hippo:configuration/hippo:update: update # file: config-delta-update.yaml /hippo:configuration/hippo:workflows: workflow # file: config-delta-workflow.yaml /hippo:configuration/hippo:derivates: workflow # idem /hippo:configuration/hippo:translations: translations # file: config-delta-translations.yaml /hippo:namespaces: namespaces # file: config-delta-namespaces.yaml /hst:hst/hst:configurations/hst:default: hst # file: config-delta-hst.yaml /targeting:targeting: targeting # file: config-delta-targeting.yaml /: # file: config-delta.yaml (catch-all)
Changing or refining the default mapping can be done through the path-prefix-source-mapping in configuration-verifier-config.yaml by adding new or overriding the default mappings.