Remote Debugging

While not required for development, the ability to remotely debug dotCMS and plugin code makes OSGi plugin development and troubleshooting much easier. Below are the steps required to enable remote debugging in a dockerized environment

TL;DR - Here is a docker-compose example that has remote debugging enabled by default: https://github.com/dotCMS/core/tree/main/docker/docker-compose-examples/single-node-debug-mode

Steps to set up remote debugging

1. Set up a local dotCMS environment per the quick start guide: docker environment quick start.

2. Turn on java debugging in your docker-compose.yml. Once the local environment is set up and functioning normally, shut it down using docker compose down. You will need to remote attach your debugger to the java process running in the container. To do this, you will need to add the following to the CMS_JAVA_OPTS environmental variable to your docker-compose.yml.

   "CMS_JAVA_OPTS": ' -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:8000'
   

   Additionally, make sure that port 8000 is mapped and externally available, e.g.:

   ports:
       - “8000:8000”
   

   This will allow your IDE to attach to your dotCMS instance, activate breakpoints and allow you to step through your custom code.
   ⚠️ Warning Never open the debugging port to the world in a live environment as the debugging port does not require any authentication/authorization and represents a security risk.

3. Create a new dotCMS project in your IDE for your plugin.

4. Deploy your plugin. Create a jar file from your plugin source code. Generally, this can be done by running ./gradlew jar to compile the code. Once compiled, upload the resulting .jar file into the dotCMS backend under CMS Admin > Plugins.
   

5. Add plugin's source code to Build Path
   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 your plugin project from the list and click on Add Project

6. Adding a new 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)

7. Test your plugin: Drop a break points in your plugin code in Eclipse to make sure debugging is enabled. You can also examine the log files for any errors as the custom plugin functionality is tested.