Usage
The configuration plugin comes with a portlet that makes it easy to check if your overrides are working. To enable the portlet you need to add it as a Tool to one of the dotCMS admin tabs. As an example let's pass it to the CMS Admin tab. To do this follow these steps:
- Click on the "System" tab and select the "Roles & Tabs" submenu.
- In the tree structure on the left, select the role that you would like to give this new tool to. In this example we'll choose "CMS Administrator"
- Click on the "CMS tabs" tab on the right of the tree menu.
- At the top-right corner click on "Create Custom Tab", a pop-up should appear.
- Name and order the tab, and select the "Configuration Cache" tool from the tools drop-downlist.
- Click on "Add" and finally hit "Save".
- The tab should be added to the list of existing tabs.
- Check the created tab from the list and click on "Save".
- Refresh the page and the tab should be added to the dotCMS tabmenu.
The "Configuration Cache" portlet is a handy tool that lets you not only see what hosts and plugins contain what configuration settings, but also enables you to clear the configuration's cache. Because of performance the configuration plugin maintains a cache that must be cleared to see any changes that are made to the configuration files on disk. You do not need to restart dotCMS if you change any plugin's configuration on disk: just flush the cache and the changes will be loaded into memory immediately.
When you open the portlet you'll see three sections, marked A, B and C in the image above. The button in section A clears the cache. The pulldowns in section B let you restrict the host and/or plugin that you want to see all configuration values of. In section C you see all the configuration properties per selected host and per selected plugin/host combination. When there are no overrides defined yet, the configuration of a plugin wil be the same for all hosts (the dotCMS default). You can see this very well in the portlet: all name/values for all plugins are identical. More about the "environment = DEV" property in the "host configuration" paragraph below.
An important note is that the configuration plugin will only work with configuration that is added to the plugin.properties file of other plugins, NOT with any < context-param > parameters that are defined in the web-ext.xml of a plugin. If you want to override those parameters then move them from the web-ext.xml to your plugin's plugin.properties file. This of course only works for web.xml parameters not for the other tags such as servlet and filters.
Below we show how the plugin can be used to fix the typical problems we presented in the why is this plugin useful section above. In the examples below we use a plugin named "demo-plugin" that has the following configuration defined in its plugin.properties file:
// These are the default values defined in
// the plugins's conf/plugin.properties file
testkey1 = testvalue1
testkey2 = testvalue2
testkey3 = testvalue3
The reason we're doing all of this is so that you as a developer can use the configuration name/value pairs in your code. Because the configuration plugin adds itself transparentely to dotCMS you can use the default dotCMS API's to read these values:
// Java code: Reading the value of property of a plugin
// "pluginId" with name "key" for the current host.
APILocator.getPluginAPI().loadProperty("pluginId", "key")
// Velocity code: Reading the value of property of a plugin
// "pluginId" with name "key" for the current host.
$pluginapitool.loadProperty('pluginId', 'key')Suppose we would like to override the value for testkey1 for this specific dotCMS instance. Create a file also named "plugin.properties" and place that in the folder /tomcat/conf/applications/[name of plugin]. In this example [name of plugin] is "demo-plugin" (the folder name of the plugin the property is defined in). Below is what we used in this example:
// This is the override for the demo-plugin for this dotCMS
// instance defined in the plugin.properties in
// /tomcat/conf/applications/[name of plugin]
testkey1 = instance specific value
When we click on the "flush" button in the portlet the override we just defined is picked up and are loaded into memory. Below is the result. You can see that the value for testkey1 is different than the default value and is used in all hosts. The override is only defined in one location and because it is outside of the plugin folder we can overwrite the entire folder with a new version of the plugin without deleting the override.
Let's say that we'd like to define an override for the host demo.dotcms.com. We'll override the "testkey2" property of the "demo-plugin" plugin (see image above). To do this create a file also named "plugin.properties" and place that in the folder /tomcat/conf/applications/[name of host]/[name of plugin]. In this example [name of host] is "demo.dotcms.com" (the value of the "host name" field of the host you want to create the override for). [name of plugin] again is "demo-plugin". Below is what we used in this example:
// This is the override for the demo.dotcms.com host for
// the demo-plugin defined in the plugin.properties in
// /tomcat/conf/applications/[name of host]/[name of plugin]
testkey2 = other testvalue2
extrakey = extra value
Below is the result of this override (remember to click the flush button in the portlet first). You can see that the value for testkey2 is different for the two hosts and that the extrakey is only avaiable in the demo.dotcms.com host. The instance specific override of the previous example is also still visible.
Let's say that we'd like to define an override for the client with IP 10.211.55.2. We'll override the "testkey3" property of the "demo-plugin" plugin (see image above). To do this create another file named "plugin.properties" and place that in the folder /tomcat/conf/applications/[name of host]/[name of plugin]/[IP of client]. [name of host] and [name of plugin] are the same as in the previous example. [IP of client] is 10.211.55.2. Below is what we used in this example:
// This is the override for the demo.dotcms.com host for
// the demo-plugin and the client with IP address 10.211.55.2
// defined in the plugin.properties in
// /tomcat/conf/applications/[name of host]/[name of plugin]/[IP of client]
testkey3 = other testvalue3
Below is the result of this override (remember to click the flush button in the portlet first). You can see that the value for testkey3 is different for the demo.dotcms.com host than in the previous examples. If the same portlet would be viewed from another client (with another IP address) the value would be the same as in the previous example. Only this client will see this value for testkey3 for the host demo.dotcms.com and the plugin it is defined in.
By default the configuration plugin only supports client overrides per host & plugin basis, so you cannot define an override for a specific client for all hosts in one place (like in the instance specfic override). However: adding this functionality is relatively simple and you can read more about it in the Tips and Tricks section.
The client specific overrides are only used if the global "environment" property defined in /tomcat/conf/applications/serverConfig.xml has the value DEV. This is because we only want to use client exceptions for development dotCMS instances to prevent production issues. See "host configuration" below for more information about this environment variable.
Let's say that we'd like to use a nested XML structure as the layout of the plugin's configuration. We could write it as a dot separated key/value pair (eg keypart1.keypart2.keypart3 = value) in the default plugin.properties file, but that can become pretty hard to read when the xml structure becomes complex. That is why the configuration plugin adds a new way to define configuration in a plugin: the "pluginConfig.xml" file. You can use this file anywhere you'd normally use a plugin.properties file, you can even use both at the same time. You could override the default plugin.properties in the host specific override using this type of xml file. Below is what we used in this example:
// This is the override for the demo.dotcms.com host for
// the demo-plugin defined in pluginConfig.xml in
// /tomcat/conf/applications/[name of host]/[name of plugin]
<?xml version="1.0" encoding="UTF-8" ?>
<config>
<testkey2>other xml testvalue2</testkey2>
<extrakey>extra xml value</extrakey>
<complexkey>
<item>
nested value 1
</item>
<item>
nested value 2
</item>
</complexkey>
</config>Below is the result of this override (remember to click the flush button in the portlet first). You can see that the xml file is read and displayed as dot separated name/value pairs. We added the "testkey2" and "extrakey" properties to the xml file as xml nodes. You could leave them in their own plugin.properties override file and only have the complex values in their own pluginConfig.xml file. We recommend however that you stick to one type of file, because it can get hard to keep track of all the different filetypes and different ways key/value pairs are defined.
All the examples above described overrides for plugins. The configuration plugin also enables you to define variables for hosts directly or even for the entire system.
Variables for the entire system are defined in the /tomcat/conf/applications/serverConfig.xml file. By default there is one property there already: "environment". This variable indicates whether this dotCMS instance is a development (DEV), user acceptance test (UAT) or production (PROD) server. Important: do not remove this property because the configuration plugin depends on it! If you also use DEV, UAT and PROD instances you might want to fill in the correct environment type in this property for each dotCMS instance. You can use this property to switch to a slightly different behaviour in your Java or Velocity code depending on the value of this variable. All variables in the serverConfig.xml are available in the context of hosts and also in the context of plugins. You can see that fact in the images of the examples above: they all contains the "environment = DEV" property.
When you want to define a host specific variable create a file named "hostConfig.xml" and put it in the folder: /tomcat/conf/applications/[name of host]. You can only use the xml format and not the properties format here. Because dotCMS doesn't know about "host configuration" the configuration plugin defines its own API to enable you to read these values:
// Java code: Reading the value of a property with name "key"
// for the current host
ConfigurationService.getHostParameters().getString("key");
ConfigurationService.getHostParameters().getBoolean("key");
ConfigurationService.getHostParameters().getInt("key");
ConfigurationService.getHostParameters().getLong("key");
... etc
// Velocity code: Reading the value of a property with name "key"
// for the current host
$configuration.keyHere's an example of an hostConfig.xml file.
// These are host variables for the demo.dotcms.com host defined
// in the hostConfig.xml file in
// /tomcat/conf/applications/[name of host]
<?xml version="1.0" encoding="UTF-8" ?>
<config>
<extra-host-param>some value for this host</extra-host-param>
</config>Below is the result of this hostConfig.xml file (remember to click the flush button in the portlet first). You can see that the value for extra-host-param is included outside of a specific plugin and only for the host demo.dotcms.com. You can also create client specific overrides for host configuration. This works in the same way as the client overrides for plugins.
Until now we have only spoken about creating override files on the server's file system. The problem with this is that you cannot change the values of the configuration properties through the dotCMS admin. If you would like to enable some dotCMS users to change these values then you're out of luck. We solve this issue by leveraging the default dotCMS site browser.
In the case of plugin overrides you can create a folder "/config/[name of plugin]/" in the root of the site browser of the dotCMS admin and place a pluginConfig.xml file in there (plugin.properties does not work here, so don't use those files). There is no [name-of-host] because the host will obviously be the host the directory is created in. The values in these files will be read as well and will override the default values of the plugin itself. See "override order" below to find out what overrides what exactly.
You can do the same for host configuration. Create a folder "/config/" in the root of the site browser of the dotCMS admin and place a hostConfig.xml file in there.
Important: Make sure to remove the CMS anomymous permissions on the /config folder. If you do not do this all of the files in that folder will be visible for everbody on the internet.
Here's an example of a pluginConfig.xml file that was placed inside of dotCMS:
Below is what we used in this example:
// This is the override for the demo.dotcms.com host for
// the demo-plugin defined in the pluginConfig.xml in
// /[dotCMS site browser]/config/[name of plugin]
<?xml version="1.0" encoding="UTF-8" ?>
<config>
<testkey1>override from within dotCMS</testkey1>
<extrakey2>extra property from within dotCMS</extrakey2>
</config>Below is the result of this override (remember to click the flush button in the portlet first).
It is possible to define an override rule for a property in both /tomcat/conf/applications/[name of plugin] and /tomcat/conf/applications/[name of host]/[name of plugin]. So which override will win? The default override order is straightforward and is listed below (a file lower in this list will override the files above it). You can change this order or even the location of the files yourself, see the Tips and Tricks section for more info about how to do that.
Override order for plugin configuration:
- [plugin folder]/conf/plugin.properties
- [plugin folder]/conf/pluginConfig.xml
- tomcat/conf/applications/[name of plugin]/plugin.properties
- tomcat/conf/applications/[name of plugin]/pluginConfig.xml
- [dotCMS site browser]/config/[name of plugin]/pluginConfig.xml
- tomcat/conf/applications/[name-of-host]/[name of plugin]/plugin.properties
- tomcat/conf/applications/[name-of-host]/[name of plugin]/pluginConfig.xml
- tomcat/conf/applications/[name of host]/[name of plugin]/[IP of client]/plugin.properties
- tomcat/conf/applications/[name of host]/[name of plugin]/[IP of client]/pluginConfig.xml
- tomcat/conf/applications/serverConfig.xml
Override order for host configuration:
- [dotCMS site browser]/config/hostConfig.xml
- tomcat/conf/applications/[name-of-host]/hostConfig.xml
- tomcat/conf/applications/[name of host]/[IP of client]/hostConfig.xml
- tomcat/conf/applications/serverConfig.xml
As you can see the tomcat/conf/applications/serverConfig.xml is always read last. So nothing can override the values that are defined in that file.
Try out some of the overrides we described above and use the portlet to see if everything works as expected.