Using the Configuration Verifier
Executing the Configuration Verifier
Bloomreach Experience Manager projects are expected to use the com.onehippo.cms7:hippo-cms7-enterprise-release parent pom , and which (as of version 13.0.0, the parent pom ) provides two new custom Maven profiles: create-configuration-verifier-config and verify-configuration.
Executing the create-configuration-verifier-config Maven profile creates a skeleton config file that can be used to add or modify some configurations that are explained in Configuring the Configuration Verifier section. The configuration file is always needed to be able to run the CV.
Execute the following command from the project root folder to generate a configuration-verifier-config.yaml file in the project root folder.
mvn -P create-configuration-verifier-config
The second Maven profile, verify-configuration, is used to run the CV and which then generates the configuration delta output yaml files. The CV loads the project configuration from both cms.war and site(s).war (if any). The site(s).war must be deployed before the cms.war to enable the loading and processing the HCM modules in those site(s).war. The cms.war should be deployed last. The verify-configuration profile automatically takes care of this requirement by forcing ordering and deploying the cms.war to be deployed (in Cargo) as last.
The verify-configuration profile must be combined with the Maven cargo:run profile to run the CV. Execute the following command to run the configuration verifier CV (make sure to separate the two profiles only with a comma and not additional spaces):
mvn -P cargo.run,verify-configuration
If the 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).
The CV uses two additional parameters, and its processing can be further customized through the configuration-verifier-config.yaml file.
The following two system parameters are pre-defined in the verify-configuration profile, and passed on to the 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.
Execute the following command to change this parameter. You can override the default value for this parameter by specifying it on the command line as follows:
mvn -P cargo.run,verify-configuration -Drepo.verify.configuration.configfile=another-file-with-path
- repo.verify.configuration.exportpath=${project.basedir}/configuration-verifier-output
This parameter defines the folder location where the CV will generate its configuration delta output delta files (if any).
Execute the following command to change this parameter. You can override the default value for this parameter by specifying it on the command line as follows:
mvn -P cargo.run,verify-configuration -Drepo.verify.configuration.exportpath=another-folder-path
There are also six optional configuration properties that can or may need to be set: three of them are for configuring the deployment order and the other three are for the remote deployment itself (although in practice those are unlikely needed).
| Parameter Name | Default Value | Description |
|---|---|---|
| cargo.war.deploy.first | N/A | WAR context name(s) (not prefixed with `/` and comma separated if more than one) to be deployed first |
| cargo.war.deploy.last | cms | WAR context name(s) (not prefixed with `/` and comma separated if more than one) to be deployed last |
| cargo.war.deploy.order | N/A | comma separated WAR context names to be deployed in relative order |
| cargo.remote.username | admin | admin username for the TomcatManager |
| cargo.remote.password | N/A | admin password for the TomcatManager |
| cargo.remote.uri | N/A | override for the default remote URL of the TomcatManager |
Configuring the repository (database)
Using a development repository database
By default, the CV will verify the current project configuration against the current configured 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 runtime parameter value can be specified when running the CV to use a different database (storage folder) from 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. Using the CV against a production repository database is useful, and nessesary before and during a project upgrade (at least twice!).
There are two main use-cases using a different setup and scenario for this, but both can (re)use the same production repository database:
- Detecting possible runtime configuration changes made in production which have not (yet) be reconciled back in the project configuration sources.
This requires (assumes) running the CV within or for the current deployed project version source tree, e.g. the exact same project source version as used (in production) for the production repository database to verify against. - Detecting resulting runtime configuration changes before deploying a new product (or project) version, which always should be done during a major product upgrade, but can be likewise useful before any new deployment.
Major product upgrade steps assume that the 1st scenario (already) has been done too, before starting with the update steps themselves!
And for both cases the same 'latest' production repository database can be (re)used.
To verify configuration changes between the current project version configuration sources against the current 'in production' configuration, copy, setup and configure a most recent backup of the repository production database for local use. 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 (e.g. local development and production) and therefore using different repository storage folders as pointed at by the repo.path parameter, we advise to define 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,verify-configuration,mysql-dev
and CV can be executed against the production database with:
mvn -P cargo.run,verify-configuration,mysql-prod
This initial index recreation can be skipped or minimized by also reusing a backup of the index (matching with the database backup), for example as created with the Lucene Index Export Service.
Configuring the Configuration Verifier
When executing executing the CV, it uses reads and a configuration from configuration-verifier-config.yaml file, which 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: hst
# /hst:hst/hst:configurations: hst
ignorepaths
When the CV checks for possible differences between the new configuration and the existing data in the repository, it skips a few hard-coded paths, as well as any path configured through the for ignorepaths in the configuration-verifier-config.yaml.
The hard-coded paths (path prefixes) excluded by the CV are:
- /jcr:system - /hippo:log - /content/attic - /formdata - /webfiles - /hippo:configuration/hippo:update/hippo:queue - /hippo:configuration/hippo:update/hippo:history - /hippo:configuration/hippo:update/jcr: - /hippo:configuration/hippo:temporary
For the initial usage of the CV, the ignorepaths in the 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 the 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 the CV. The delta path can be added to the ignorepaths in configuration-verifier-config.yaml, typically accompanied with a comment explaining why.
filteruuidpaths
The 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 repository, as well as jcr:uuid properties defined only in the 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, can (and must) use wildcard patterns, where * means any path element and ** means any path.
So for example configuring /hst:*/** as a filteruuidpath will filter out all jcr:uuid properties for all /hst:hst type nodes.
path-prefix-source-mapping
When the CV detects a difference between the new configuration and the existing data in the 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.