This article covers a Bloomreach Experience Manager version 13. There's an updated version available that covers our most recent release.

13-12-2019

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).
This output folder will be first deleted when the CV starts executing: backup/rename the folder after execution of the CV to retain its ouput across executions!

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:

  1. 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.
  2. 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
A first execution of the CV against a large (backup of a) production database may take considerable initialization time to (re)create its indices inside the repo.path storage folder.
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.
Be sure to not accidentallly reuse the existing development repo.path storage folder for the production database, as that will result in erratic, inconsistent, broken behavior for the repository! 

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.
Note that these ignorepaths are path prefixes, checked and matched by the CV, they will also result in ignoring changes to child nodes and properties. Make sure to also (first) resolve reported deltas for child nodes and properties!

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.
 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?

    We rely on cookies

    to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

    Manage cookies
    Accept & close

    Cookies preferences

    Accept & close
    Back