You may easily overwrite the core dotCMS configuration files via the ROOT folder on any plugin. This provides a single location for all dotCMS configuration files which you have modified, and allows you to maintain and manage configuration files separately from the dotCMS core files.
Note:
It is strongly recommended that you use this method rather than directly editing the dotCMS configuration files, to make new deployments and upgrades much easier.
The dotCMS configuration plugin (**$DOTCMSHOME/plugins/com.dotcms.config) ships with the dotCMS distribution.
- The ROOT folder in the configuration plugin may be used to override any dotCMS configuration files, without the need to install or create a new plugin.
Files to Override
Whenever possible, any time you wish to make changes to any dotCMS configuration files within the dotCMS installation, you should override the files via a plugin ROOT folder.
Some commonly modified configuration files that you should override are:
- server.xml: To modify the port where dotCMS runs.
- context.xml: To modify database connection information.
- For more information, please see the Database Configuration documentation.
- startup.sh or startup.bat: To modify
JAVA_OPTS.- For more information, please see the Performance Tuning documentation.
- log4j2.xml: To change log file location or configuration.
- For more information, please see the Logging Configuration documentation.
- portal.properties: To change authentication and security settings.
- For more information, please see the Password Security Configuration and Login and Session Configuration documentation.
How it Works
The plugin ROOT folder works by overriding files within the core dotCMS directory tree with files of the same name, and in the same path, within the plugin ROOT folder.
- The original dotCMS files remain unchanged in their original locations, so any changes to those files made during a new deployment or upgrade do not overwrite your configuration changes.
- In most cases, to upgrade dotCMS to a new version, or to deploy a new site, you need only copy your plugins folder to the new dotCMS installation and deploy your plugins to restore your modified configuration.
Configuration Steps
To override a dotCMS configuration file, perform the following steps:
1. Create the ROOT folder in your plugin
Create a directory named ROOT at the top level of your static plugin folder (you may do this within any static plugin folder).
For example, the ROOT folder of the default com.dotcms.config plugin is $DOTCMSHOME/plugins/com.dotcms.config/ROOT.
2. Create the directory structure for the file to be overridden
Create the same folder structure under the plugin ROOT folder as exists in the dotCMS installation folder where the file you wish to override is located.
For example, if you wish to override the server.xml file in the $DOTCMSHOME/dotserver/tomcat-8.0.18/conf folder, you must create the folder $DOTCMSHOME/plugins/com.dotcms.config/ROOT/dotserver/tomcat-8.0.18/conf.
3. Copy the configuration file to be overridden
Copy the file you wish to change from its original location in the dotCMS directory tree to the same location within the plugin ROOT folder tree.
For example, to override the server.xml file, copy $DOTCMSHOME/dotserver/tomcat-8.0.18/conf/server.xml to $DOTCMSHOME/plugins/com.dotcms.config/ROOT/dotserver/tomcat-8.0.18/conf/.
4. Edit the copied file
Edit only the copy of the files in the plugin ROOT folder tree.
For example, to override the server.xml file, edit the file $DOTCMSHOME/plugins/com.dotcms.config/ROOT/dotserver/tomcat-8.0.18/conf/server.xml.
5. Deploy your static plugins.
- Linux/MacOS:
bin/deploy-plugins.sh - Windows:
bin\deploy-plugins.bat
Important Notes
- Configuration files overridden by plugins are entirely overwritten, not merged.
- If you need to make multiple changes to the same file, all changes must be included in one plugin only or the last plugin to be deployed will overwrite all changes made by previous plugins.
- The property names in dotCMS configuration files are both case sensitive and sensitive to spaces.
- You must make sure the property name (everything before the equals sign) in properties files exactly match the property name in the core properties file.
- Case mismatches or extra spaces will prevent the new property value from being used, causing the default value to be used instead.
Example: Override the Tomcat server.xml File
For example, here are all the steps on Linux or MacOS to override the /dotserver/tomcat-8.0.18/conf/server.xml file in the dotCMS installation:
- Create the ROOT folder in your plugin directory.
cd $DOTCMSHOME/plugins/com.dotcms.config md ROOT - Create the folder structure ROOT/dotserver/tomcat-8.0.18/conf/ in your plugin directory.
cd ROOT md ROOT/dotserver/tomcat-8.0.18/conf - Copy the server.xml file from its original directory to the new directory:
cd $DOTCMSHOME cp dotserver/tomcat-8.0.18/conf/server.xml plugins/com.dotcms.config/ROOT/dotserver/tomcat-8.0.18/conf/ - Edit the new file copy of the server.xml file and make your desired changes.
vi plugins/com.dotcms.config/ROOT/dotserver/tomcat-X.x.x/conf/server.xml - Deploy your static plugins.
bin/deploy-plugins.sh
The configuration in the new server.xml file (in the plugins ROOT folder) are now used instead of the configuration in the original server.xml file (which remains unchanged in its original location).
Example Directory Structure
The following image shows the directory hierarchy, using the com.dotcms.config plugin to override both the server.xml and context.xml files:
