Update HST Configuration
Goal
Update HST configuration in a particular server environment (e.g. production).
Stakeholders
Developer, Webmaster
Prerequisites
All channel modification in the target environment must be published before the update.
No channel may be edited in the Channel Manager in the target environment during the update.
Reloading updated HST configuration
The HST configuration, stored in the repository under /hst:hst, contains all configuration settings for your publication channels (websites, mobile sites, etc.). Examples of HST configuration include page template, page components, sitemap, virtual hosts and other channel settings.
Typically the HST configuration is under constant change in the production environment because webmasters can make changes to publication channels using the Channel Manager. Examples of changes made by a webmaster include adding or removing page components, modifying the configuration settings of individual page components and even creating completely new channels such as microsites for events or marketing campaigns.
Because of the dynamic nature of HST configuration, updating it on deployment of a new release can be complex. Any configuration changes included in the new release must effectively be merged with changes made on-the-fly in the target environment by the webmaster.
The best way to handle this is to merge the on-the-fly changes made in the production environment back into the development environment before releasing the project and deploying the new release. This requires some coordination with the webmaster(s) and a short period in which no changes may be made in production until the new release has been deployed. The benefit is that updated HST configuration nodes can simply be reloaded on deployment of the new release, using the reload-on-startup feature.
The procedure is as follows:
- Make sure all channel modifications in the target environment are saved and published and that no channel is being edited.
- Use the JCR diff and patch feature in the CMS console to extract any changes that might have been made to the HST configuration in the target environment.
- Enable the Automatic Export feature in your development environment to automatically export any changes to your HST configuration as XML in the bootstrap module.
- Apply the changes that were made in the target environment to the HST configuration in your development environment. In straightforward cases you can simply apply the patch, created in the target environment, to your development environment. In more complex cases (i.e. if you also made local changes) manual work might be involved.
- Make any additional changes to the HST configuration, required for the next release, in your development environment.
- In your project's bootstrap module make sure the relevant content initialization items are marked as reloadable.
- Commit the changes in your bootstrap module to your Version Control System (as usual).
- Package the bootstrap module with your release artifact(s) (as usual).
- Deploy the release artifact(s) in the target environment. Reload-on-startup will detect the reloadable initialization items and update the HST configuration accordingly.
Updating environment-specific HST configuration
In some cases HST configuration in the production environment is deliberately different from the configuration stored in version control. For example an environment-specific configuration setting such as a URL.
In such a case the relevant initialization item cannot simply be reloaded from the bootstrap, as this would overwrite the environment-specific settings.
In straightforward cases you might be able to properly update the affected node(s) by manually adding a custom initialize item to the bootstrap module and using "Delta XML", effectively merging the updated settings with the environment-specific settings.
In complex cases you might have to write and execute a custom Updater Script. The script is best added to the "script registry" using the bootstrap, and then manually executed by an administrator after the new release has been deployed.
Summary
- The HST configuration by nature is constantly being modified in the production environment.
- It is best to keep the bootstrap module in the Version Control System in sync with the production environment.
- The HST configuration in the production environment can be updated using the reload-on-startup feature, provided that the bootstrap module in the VCS is kept in sync with changed made in the production environment.
- Environment-specific HST configuration must be updated using Delta XML or a custom Updater script.