Developing from Source - Remote Debug - Documentation topics on: developing,development environment,eclipse,integration,plugins,setting up development environment,.

Developing from Source - Remote Debug

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

Create an account on and then create a directory on your server in which you will run the following command line commands to pull down the dotCMS source code:

  1. git clone https://[Your Github Username] .   ## The period at the end avoids creating a secondary parent directory.
  2. git checkout master-[X.xx]  ## X.xx refers to the dotCMS version number, for example: git checkout master-3.1

    (git status & git branch commands can be used to validate the status of the source download)

Importing the dotCMS project in Eclipse

Eclipse provides a very complete toolset to develop in dotCMS.  The following instructions will show you how to create a new project and start dotCMS from within dotCMS in order to take advantage of this toolset.

  1. Go to File > New > Other… > Java Project.

  2. Uncheck the Use default location and click Browse.

  3. Lookup the Core project in your file system and click Finish.
  4. Right-click the Core project and go to Build Path > Configure Build Path… > Source. Select all the source folder associated to “examples” and click the Remove button.

  5. Add plugin's source code to Build Path (Optional for Debugging)
    Whether it's a static or a dynamic (OSGi) plugin, you will need to add the plugin's source code to the Eclipse Project's build path in case you want to debug its source code when it's executed.
    • Right click the Eclipse Project,  and go to Build Path > Configure Build Path… > Source
    • Select the source folder
    • Static plugins / Dynamic Plugins that are not built with Gradle
      • Select the plugin's "src" plugin and click on "Add Folder"
    • Dynamic Plugins built WITH Gradle
      • Select  "your.custom.plugin/src/main/java" folder and click on "Add Folder"

  6. Now, go to the Libraries tab. Delete all the current libraries EXCEPT FOR the “JRE System Library”.

  7. Click the Add External JARs… button and select all the libraries under these folders:
    • <your-path>/core/libs/buildlibs

    • <your-path>/core/libs/buildlibs/jsp

  8. (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

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

  10. Open up a Terminal pointing to your Core folder (“<your-path>/core”) and run the following commands:
  11.  ./gradlew clean
    ./gradlew deploy-war-tomcat

  12. A folder called “<your-path>/tomcatX.x” will be created at the same level as “<your-path>/core”. This process will take a while since all the dependencies will be downloaded from Artifactory into your local.
  13. Once again, go back to Eclipse, right-click the Core project and go to Build Path > Configure Build Path… > Libraries. Delete all the current libraries EXCEPT FOR the “JRE System Library”.
  14. Click the Add External JARs… button and select all the libraries under “<your-path>/core/dotCMS/WEB-INF/lib” EXCEPT FOR the one called similar to “dotcms_<version-number>_<generated-code>.jar”.

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:

  2. .dotserver/tomcatX.x/bin/

    Optionally, you can run

    .dotserver/tomcatX.x/bin/ debug
    to remotely debug your code form your IDE (port 8000 by default).

    You can also specify the port number, like this:

    .dotserver/tomcatX.x/bin/ debug 1111
    (See the debug configuration below)

  3. 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:

  4. 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 core/extra/tomcat-7/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 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”)


    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: