Developing from Source - Remote Debug

Last Updated: Aug 9, 2021
documentation for the dotCMS Content Management System

The following documentation covers development in dotCMS from Eclipse using the dotCMS source code and remote debugging. The recommended methodology for custom development is to download the dotCMS release code and develop custom code in a completely isolated plugin. **See the Developing from Release documentation.

However, if you do wish to develop from a source checkout from Github, please make sure that all customizations to dotCMS files are properly isolated in a plugin that can be deployed and un-deployed independently. See the dotCMS Plugins documentation.

Before you get started

  • The development team at dotCMS has found that debugging dotCMS as a normal Java application makes things easier. We do not suggest using WTP which is an Eclipse Plugin for web development. Basically WTP does what we are going to explain below but tends to break down at times. Setting dotCMS up as a Java Application in Eclipse makes Eclipse run Tomcat directly by hooking up to its bootstrap and providing all JVM and environment variables it needs.

  • When working with dotCMS and Eclipse you want to make sure Eclipse gets to compile everything. This is different from dotCMS outside of Eclipse because you would normally use ANT to build dotCMS. There are a few things you still need ANT for like building SQL and working with Plugins. NOTE: for plugins there are specific ANT tasks for plugin dev which only move plugin config and don't actually compile plugin classes. This is important because you want to make sure Eclipse is compiling your classes when working with plugins.

Downloading from Github & Importing dotCMS in Eclipse or intelliJ

For instructions on how to download the dotCMS source code and to set up your Eclipse or intelliJ development enviroment, please see the Developing from Source documentation

Debug Configurations

  1. (Optional): If you have added a plugin which contains 3rd party jars, you may need to add them to the Build Path too. Click on “Add External Jars…” and search for the plugin's jars:

    • For Static Plugins

    • Jars should be located under “your.static.plugin/lib” folder

    • For Dynamic Plugins (OSGi)

    • Jars should be located under “your.static.plugin/src/main/resources/libs” folder or whenever it's set on the plugin's build.gradle file

  2. To avoid seeing cluster related errors, go to “core/dotCMS/src/main/resources/”, lookup the property called “”, and then change its value. For example, “dotCMSContentIndex`<your-name>`”.

  1. Open up a Terminal pointing to your Core folder (“`<your-path>`/core/dotCMS/”) and run the following commands:

    ./gradlew clean
    ./gradlew deployWarTomcat
  2. Move to the newly created folder called “`<your-path>/tomcatX.x” that now exists at the same level as “`````/core”. Note that the folder creation process, initiated by the previous step, will take a while since all the dependencies will be downloaded from Artifactory into your local.

Starting dotCMS for the first time

At this point, you have everything you need to startup dotCMS with a basic configuration using the H2 database (for testing and development only), by default, special for development purposes. To configure a real staging or Production environment, H2DB should not be used. See the dotCMS Installation and Configuration documentation to learn how to configure different databases in a dotCMS root configuration plugin.

To run dotCMS, follow these steps:

  1. Go back to the Terminal pointing to your dotCMS installation folder and run the following command:


    Optionally, you can run

    .dotserver/_tomcatX.x_/bin/ debug

    You can also specify the port number, like this:

    .dotserver/_tomcatX.x_/bin/ debug 1111

    See the debug configuration below

  2. Once you do that, open up another Terminal and tail the startup log file to check the initialization process. For a development environment, the main system log file is catalina.out. It’s always a good practice to pay real attention to the information displayed here:

    tail -f .dotserver/_tomcatX.x_/logs/catalina.out

During the startup process, the system will execute a series of tasks, checks, Quartz jobs, caching configuration, and database-related operations (hence the importance of viewing the log during the startup). Some of these tasks are run every time the system is restarted, and some other are run only once, they must never be re-executed. The log will indicate when the system is up and running through a message similar to “INFO: Server startup in `<milliseconds>` ms”, running on localhost on port 8080.

The dotCMS project has a file called /tomcat8/webapps/ROOT/META-INF/context.xml which provides the basic template to configure each database connection, so you just need to uncomment the connection you need in the file and update the connection parameters. The H2 database is used by default.

Shutting down dotCMS

To shutdown dotCMS, go back to the Terminal pointing to your Core folder (`<your-path>`/core) and run the following command:


Adding the Remote Debug Configuration in Eclipse

Adding a debug configuration in Eclipse is very simple. Go to Run > Debug Configurations… > Right-click Remote Java Application > New and set a name for it, browse to the project you want to debug (e.g., “core”) leave the default Host (“localhost”) and Port (“8000”)

Adding the Remote Debug Configuration in intelliJ

1) Go to Run → Debug
2) Click the “+” in the upper left
3) Select “Remote” option
4) Type a name
5) Modify the default port in the middle right. Use port 8000 instead
6) Click “Debug”


Do not break your upgrade path! Make sure to package all customizations/configurations inside a dotCMS plugin. For more information, please see the dotCMS Plugins documentation. If additional staff training is needed to achieve the desired customizations, please email us at:

On this page