WSO2 Products Dockerized: Remote Debug Dockerized WSO2 Products with IntelliJ IDEA

WSO2, the world’s #1 open source integration vendor, provides official Docker images for its products. The previous articles of this series provided an introduction to these Docker images and their usage. This write up intends to cover how IntelliJ IDEA Integrated Development Environment (IDE) can be used to remote debug a WSO2 product server instance running inside a Docker container.

WSO2 products Dockerized

Sometimes, WSO2 product users and developers experience the need to remote debug the WSO2 product servers they use. For example, product users utilize remote debugging of WSO2 products to fix product deployment issues while, developers frequently use the technique to identify the causes of product issues and to test product features.

WSO2 product servers can be started in remote debugging mode using the product startup option -debug <port>, where the port stands for the desired remote debugging port.

IntelliJ IDEA Community Edition 2019.1.1

As you may remember, using product startup options with WSO2 product Docker images was a topic discussed in the last write up of this series.

With this, most recent discussion fresh in our minds, let me provide you with a practical guide on how to remote debug a WSO2 product server using IntelliJ IDEA, one of the most widely used IDEs, in the context of a Docker based deployment.


In the past couple of months, the WSO2 products Dockerized series has introduced you to WSO2 product Docker images and their usage. If you are a fresh user to WSO2 product Docker images, it is highly advised to take a peek into the previous write ups, to gain a better understanding of what I intend to cover in this article.

  • An Introduction: An introductory write up about WSO2 product Docker images.
  • Advanced Usage (Part One): A discussion on advanced usage scenarios associated with WSO2 product Docker images such as, updating product configurations and ensuring the proper functioning of Docker container instances.
  • Advanced Usage (Part Two): A continued discussion on advanced usage scenarios associated with WSO2 product Docker images such as, introducing additional artifacts to a deployment and using product startup options in a Dockerized deployment.

Remote debug Dockerized WSO2 API Manager using IntelliJ IDEA

This section brings to light a practical guide on conducting remote debugging on a WSO2 API Manager server instance running inside a Docker container, with the use of IntelliJ IDEA Community Edition IDE.

In this guide, let us remote debug the process of identifying and reading the information about external third-party libraries, already in OSGi bundle form, during the Carbon server startup. Since, WSO2 API Manager version 2.6.0 is a WSO2 Carbon version 4 based product, this process will be part of its server startup.


WSO2’s API Management solution was named a leader in the The Forrester Wave™: API Management Solutions, Q4 2018 Report.


Note: At the time of writing this article, only WSO2 product Docker images available at the Docker Hub support passing arguments during a WSO2 product server startup. This feature support for product Docker images available at WSO2’s Private Docker Registry will be provided soon.

Prerequisites

For this demonstration, the latest version of IntelliJ IDEA Community Edition (version 2019.1.1, at the time of writing) has been installed and utilized.

If you have followed the previous articles of this series, it is highly likely that you have already completed this step. If not, please complete it.

  • Install Git client

The Git client is required to obtain the source code required for this practical guide.

Steps to follow

  • Obtain the source code mapping the underlying implementation of the server process you intend to remote debug.

The mapping source code for identifying and reading information about third-party OSGi bundles deployed at the directory location <WSO2_APIM_HOME>/repository/components/dropins folder is part of the WSO2 Carbon Kernel implementation.

The mapping source code of the General Availability (GA) release of WSO2 API Manager version 2.6.0 can be found from the Git release tag v2.6.0 available under WSO2 API Manager’s product Git repository.

First, let us identify the corresponding Carbon Kernel version used within WSO2 API Manager version 2.6.0 GA release. As per WSO2 API Manager’s parent Maven pom.xml file, the mapping Carbon Kernel version is 4.4.35.

Hence, let me obtain Carbon Kernel’s source code available at GitHub. The Git release tag mapping Carbon Kernel version 4.4.35 is v4.4.35.

Clone WSO2 Carbon Kernel’s Git repository, using the Git client.

git clone https://github.com/wso2/carbon-kernel.git
Clone WSO2 Carbon Kernel’s Git repository

Now, checkout the relevant Git release tag.

# Ensure that all release tags have been fetched to your local repository
git fetch --all --tags --prune
# Checkout the v4.4.35 release tag
git checkout tags/v4.4.35 -b <desired-branch-name>
Checkout the relevant Git release tag
  • Run a Docker container instance using the WSO2 API Manager Docker image (from the Docker Hub) passing -debug 5005 argument, where port 5005 is used as the remote debugging port.
docker run --rm -it \
-p 5005:5005 wso2/wso2am:2.6.0 -debug 5005

The above command will create and run a Docker container instance of WSO2 API Manager version 2.6.0 while, passing the -debug <port> product startup option to start the server in debug mode (please see the previous write up of this series for a general discussion on passing WSO2 product startup options in a Dockerized server deployment).

Plus, notice that the remote debug port 5005 has been mapped to that of the Docker host.

Run a WSO2 API Manager Docker container instance in debug mode
  • Open the source code via IntelliJ IDEA IDE.

Open the previously cloned WSO2 Carbon Kernel Git repository through IntelliJ IDEA IDE.

WSO2 Carbon Kernel Git repository via IntelliJ IDEA IDE

The Java Class implementation corresponding to reading the OSGi bundle information can be found from here.

Add break point(s) to required line(s) by simply clicking near the line number. In the discussed example, I have placed a break point at line number 92 of DropinsBundleDeployer.java source file.

Place break point(s) to required line(s)
  • Set remote debug configurations.

You can choose one of the following options to achieve this.

— From the main menu, select Run -> Debug. From the dialog box that appears, choose Edit Configurations.

Choose to add debug configurations via the main menu

Else,

— Choose Add Configuration on the toolbar.

Choose to add debug configurations from the toolbar

Then, choose Remote as the configuration template from the Run/Debug Configuration dialog box.

Choose to add remote debug configurations by selecting the appropriate template

Provide an appropriate identifier for the configurations (e.g. in this case, product-apim-dropins). Also, ensure that the Host is set to localhost and the Port is set to 5005.

Provide the appropriate remote debug configurations

Choose Apply -> OK.

  • Start debugging.

Perform one of the following options to start debugging.

— Select Run -> Debug from the main menu. Then, choose the appropriate debug configuration identifier from the dialog box that appears.

Choose to debug via the main menu

Else,

— Press Shift+F9.

If you have followed the above steps successfully, you will experience the server startup getting suspended at the previously added break point. Now, you can continue to conduct remote debugging as per your needs.

WSO2 API Manager product server startup suspended at the break point

For a detailed, general guide on remote debugging WSO2 product servers, you can refer this highly informative write up.


This write up provides a concise, practical guide unto conducting remote debugging on a Dockerized WSO2 product server instance, with the use of IntelliJ IDEA IDE. The defined procedure makes use of the know-how about Dockerized WSO2 products, that was shared in previous write ups of this series.

I intend to cover further similar, frequently encountered use cases associated with WSO2 product Docker images in future write ups of this series.

Happy Dockering till we meet again!!!

References