Using the Configuration Verifier

Running the Configuration Verifier

Bloomreach Content projects should use the com.onehippo.cms7:hippo-cms7-enterprise-release parent POM. This parent POM provides the Maven profiles create-configuration-verifier-config and verify-configuration.

Use the create-configuration-verifier-config Maven profile to generate a skeleton configuration file. You can use this file to add or modify settings as described in Configuring the Configuration Verifier. The configuration file is required to run the Configuration Verifier (CV).

To generate a template configuration-verifier-config.yaml file in the project root directory, run:

mvn -P create-configuration-verifier-config

The verify-configuration Maven profile runs the Configuration Verifier and generates configuration delta YAML files if differences are detected. The CV loads configuration from both cms.war and any site.war files. Deploy all site.war files before deploying cms.war to ensure the CV can process HCM modules from the sites. The verify-configuration profile enforces this deployment order by deploying cms.war last using Cargo.

You must combine the verify-configuration profile with the Maven cargo:run profile to execute the Configuration Verifier. Run the following command, using a comma with no spaces to separate the profiles:

mvn -P cargo.run,verify-configuration

If the repository (database) is already indexed, the CV usually completes in a few seconds and then terminates automatically. This differs from the standard cargo.run profile, which continues running.

The Configuration Verifier accepts two additional parameters, and you can further customize its behavior using the configuration-verifier-config.yaml file.

The verify-configuration profile pre-defines and passes the following system parameters to the CV:

repo.verify.configuration.configfile=${project.basedir}/configuration-verifier-config.yaml
Specifies the location of the CV's YAML configuration file. This parameter is optional.

To override the default configuration file location, specify it on the command line:

mvn -P cargo.run,verify-configuration -Drepo.verify.configuration.configfile=another-file-with-path

repo.verify.configuration.exportpath=${project.basedir}/configuration-verifier-output
Specifies the folder where the CV writes configuration delta files.

Info: The output folder is deleted at the start of each CV execution. To retain output files, back up or rename the folder after each run.

To override the default export path, specify it on the command line:

mvn -P cargo.run,verify-configuration -Drepo.verify.configuration.exportpath=another-folder-path

The CV also supports six additional runtime parameters. Three parameters control deployment order, and three configure remote deployment (these are rarely needed in practice).

Parameter Name	Default Value	Description
`cargo.war.deploy.first`	N/A	WAR context name(s) (not prefixed with `/`, comma-separated) to deploy first
`cargo.war.deploy.last`	cms	WAR context name(s) (not prefixed with `/`, comma-separated) to deploy last
`cargo.war.deploy.order`	N/A	Comma-separated WAR context names to deploy in a specific order
`cargo.remote.username`	admin	Admin username for TomcatManager
`cargo.remote.password`	N/A	Admin password for TomcatManager
`cargo.remote.uri`	N/A	Override for the default remote URL of TomcatManager

Repository (Database) Configuration

Using a Development Repository Database

By default, the Configuration Verifier checks the current project configuration against the currently configured repository (development database).

This approach is useful during development to verify configuration changes before applying them, since the last execution of the cargo.run profile.

If you use the default embedded H2 database, you can specify a different database (storage folder) by setting the repo.path runtime parameter. This allows you to verify changes against a previously bootstrapped development database. For example, if the development database is stored in a storage folder under the project root, run:

mvn -P cargo.run,verify-configuration -Drepo.path=./storage

Using a Production Repository Database

Running the Configuration Verifier against a production repository database is required before and during a project upgrade. There are two primary use cases, both of which can use the same production database backup:

Detecting Unreconciled Production Changes:
Identify configuration changes made directly in production that have not been merged back into the project configuration sources.
Run the CV in the source tree for the currently deployed project version (matching the production database).
Detecting Changes Before Deployment:
Identify configuration changes that will result from deploying a new product or project version. This step is mandatory for major upgrades and recommended before any deployment.
Complete the first scenario before starting upgrade steps.

To compare the current project configuration with the production configuration, copy and configure a recent backup of the production repository database for local use. For guidance, refer to Use MySQL in a Development Environment.

If you work with multiple databases (such as local development and production), and use different repository storage folders via the repo.path parameter, define additional Maven profiles (for example, mysql-dev and mysql-prod). Each profile should configure a different database connection and repo.path.

For regular development, run:

mvn -P cargo.run,verify-configuration,mysql-dev

To run the Configuration Verifier against the production database, use:

mvn -P cargo.run,verify-configuration,mysql-prod

Info: The first execution of the Configuration Verifier against a large production database backup may take significant time to initialize and recreate indices in the repo.path storage folder.
To reduce initialization time, restore a backup of the Lucene index that matches the database backup. See Lucene Index Export Service.

Do not reuse the development repo.path storage folder for the production database. Mixing these can cause inconsistent and broken repository behavior.

Configuring the Configuration Verifier

The Configuration Verifier reads the configuration-verifier-config.yaml file at startup. The default structure is:

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

The Configuration Verifier skips certain hard-coded paths and any paths specified in the ignorepaths section of configuration-verifier-config.yaml when comparing the new configuration to the repository.

The following path prefixes are always excluded by the CV:

- /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

When using the CV for the first time, leave ignorepaths empty to get a complete report of detected deltas.

After reviewing and resolving deltas (see Resolving Configuration Verifier Deltas), you can:

Update the project configuration to resolve undesired differences, so they are no longer reported.
Add expected or acceptable delta paths to ignorepaths to suppress unnecessary future reports. Include comments to document the reason for each ignored path.

ignorepaths entries are path prefixes. The CV ignores changes to all child nodes and properties under these prefixes. Always resolve deltas for child nodes and properties before adding a parent prefix to ignorepaths.

filteruuidpaths

The Configuration Verifier always ignores differences in jcr:uuid values between the product configuration (group: hippo-cms) and the repository, as well as jcr:uuid properties defined only in the repository. These properties cannot be changed or removed without removing the mix:referenceable mixin.

In most cases, explicit jcr:uuid values do not need to be configured. To suppress UUID-related delta reports, use the filteruuidpaths configuration.

This setting works like the filteruuidpaths option in AutoExport. You can use wildcard patterns: * matches any path element, and ** matches any path.

For example, /hst:*/** filters out all jcr:uuid properties for all /hst:hst-type nodes. The CV also preconfigures the following patterns for UUID filtering: /hippo:namespaces/**, hippo:configuration/hippo:queries/**.

path-prefix-source-mapping

When the Configuration Verifier detects a difference, it reports each delta in a YAML source file. The file name is determined by the delta's path and the path-prefix-to-source mapping.

By default, the CV groups certain path prefixes into specific source file postfixes, producing YAML files in the output folder using the pattern config-delta-<postfix>.yaml.

The default mapping is:

/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: 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)

To change or extend the default mapping, update the path-prefix-source-mapping section in configuration-verifier-config.yaml. Add new mappings or override existing ones as needed.