Developing from Release — Remote Debug

Last Updated: Apr 27, 2022
documentation for the dotCMS Content Management System

Developing new custom features or modifying existing dotCMS features should be achieved thru the creation of plugins. DotCMS provides both static plugin and dynamic OSGi plugin methodologies for development.

Although development is recommended from release code to avoid breaking upgrade paths, development from source code documentation is also available.

  1. Download and install dotCMS from a release
    • Debug Option 1: before starting up the dotCMS release, edit the file and establish remote debugging by uncommenting this line:
      #JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"
      ⚠️ Warning: Expose remote debugging only on a development environment, never on a live dotCMS instance.
    • Debug Option 2: You can also download the source as shown in the developing from source documentation and remote debug so you can click thru the source code as you are developing extensions for dotCMS.
  2. Create a new dotCMS project in Eclipse for your dynamic OSGi plugin or static plugin.
  3. Deploy your plugin:
    • Static plugins: Moving the custom files to the plugins directory, stopping the dotCMS instance, run the /bin/ or /bin/deploy-plugins.bat commands, and restart the dotCMS instance.
    • Dynamic plugins: Create a jar file from your plugin source code and upload your OSGi plugin from the dotCMS backend under CMS Admin > Dynamic Plugins
  4. Add plugin's source code to Build Path
    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
  5. Adding the Debug Configuration in Eclipse (if running Debug Option)
    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)
  6. Test your plugin: Drop break points in Eclipse and examine for errors in log files as the custom plugin functionality is tested.

On this page