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.
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.
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
- Install IntelliJ IDEA
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.
- Install Docker
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
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>
- Run a Docker container instance using the WSO2 API Manager Docker image (from the Docker Hub) passing
-debug 5005argument, where port 5005 is used as the remote debugging port.
docker run --rm -it \
-p 5005:5005 wso2/wso2am:2.6.0 -debug 5005The 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.
- Open the source code via IntelliJ IDEA IDE.
Open the previously cloned WSO2 Carbon Kernel Git repository through 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.
- 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.
Else,
— Choose Add Configuration on the toolbar.
Then, choose Remote as the configuration template from the Run/Debug Configuration dialog box.
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.
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.
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.
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
- Remote Debugging WSO2 products using Intellij idea IDE — https://medium.com/@anuradha.15/remote-debugging-wso2-products-using-intellij-idea-ide-c0e828abd700
Follow us on Twitter 🐦 and Facebook 👥 and join our Facebook Group 💬.
To join our community Slack 🗣️ and read our weekly Faun topics 🗞️, click here⬇
