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 which provides the 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 template 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 which then generates configuration delta yaml files (if any). The CV loads the project configuration from both cms.war and site.war(s). The site.war(s) must be deployed before the cms.war to enable the loading and processing the HCM modules in those site.war(s); the cms.war must be deployed last. The verify-configuration profile automatically takes care of this requirement by ordering and deploying the cms.war (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 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 the 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 the CV where to find its (YAML) configuration file.
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 files (if any).
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 six additional runtime parameters that can or may need to be set: three of them are for configuring the deployment order; 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 set when running the CV to use a different database (storage folder) from a previous cleanly bootstrapped development version of the project, to verify changes on bootstrap configurations only. Assuming the development database is stored below the project root dir in the folder storage, the command line will as follows:
mvn -P cargo.run,verify-configuration -Drepo.path=./storage
Using a production repository database
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 multiple 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 the CV, it reads and a configuration-verifier-config.yaml file, 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 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 - /hippo:configuration/hippo:update/hippo:queue - /hippo:configuration/hippo:update/hippo:history - /hippo:configuration/hippo:update/jcr: - /hippo:configuration/hippo:temporary - /hcm:hcm
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. In addition to this example, the CV also has the following path patterns preconfigured to be filtered for uuids: /hippo:namespaces/**, hippo:configuration/hippo:queries/**.
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. The 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:roles: security # idem /hippo:configuration/hippo:users: security # idem /collections/hippocollection:domains: security # idem /formdata/hst:domains: security # idem /polldata/poll:domains: security # idem /webfiles/webfiles:domains: security # idem /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 # file: config-delta-hst.yaml /targeting:targeting: targeting # file: config-delta-targeting.yaml /hippowpm:hippowpm: projects # file: config-delta-projects.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.