How to Remotely Debug Java applications deployed to AWS EC2 Instances

Remote debugging capabilities of IDEs can come in handy when you are unable to replicate certain situations locally. If your only option is to debug applications that are running in remote servers, you will have to make sure you have met few requirements:

1. Remote applications are started in debug mode
2. You know these applications' debug ports so you can make connections to them
3. Network is configured to allow you to connect to these server through the identified ports

Recently I found myself in a situation like this where I needed to have my local environment connect to a machine that was running in AWS EC2. This application happens to be WSO2 Identity Server which was deployed into WSO2's Carbon Server. The first thing I had to do was to start WSO2 in debug mode. I was able to do this by running the following command:

IS_HOME/bin/wso2server.sh -debug 8005 (you can specify a different port here if you like)

Once the above command is executed, WSO2 will be ready to start in debug mode. In order to start it however, you will have to first connect to it from your IDE (Eclipse etc.) and set up remote debugging. Before I could do that I needed make sure I can reach this port remotely at AWS. 

You normally access EC2 instances once you set up your key pair. Access is granted with you making SSH connection requests with your key. This obviously is somewhat of a roadblock in order to just directly access this remote port for debugging purposes. This is where SSH Tunneling and Port Forwarding comes into play to help us. There is a good article here that explains it all. 

In order set up a basic SSH Tunnel with Port forwarding you can execute the following command on your machine that you will be using to connect to an EC2 instance for remote debugging. 

sudo ssh -i ~/localkey -Nf -L 8005:localhost:8005 aws_user@aws_ec2_host_ip

This command using your key will set up a tunnel and forward your computer's local port 8005 to remote server's 8005 port. Needless to say you can change this port to some other port. You will want to make sure there are AWS EC2 Security Group settings that allow access to this port. 

Once this command is run, you can now configure your IDE to set up remote debugging for applications. I tend to use Eclipse when I develop. You can easily achieve this in Eclipse by

1. Run => Debug Configurations
2. Remote Java Application
3. Click New (+ Plus button)
4. Select your project 
5. In Connection Properties, you will have to select localhost and the port number you have configured above. In our case it would be localhost, and 8005. 
6. You will then click "Debug" to start execution. 

You can also debug Tomcat applications with this set up as well. You can start Tomcat in debug mode in many different ways. You can use JPDA_OPTS or CATALINA_OPTS to set it up. Here is a good article that covers how to set it up. Once Tomcat is started in debug mode, you can use the same tunneling and port forwarding to remotely debug. 

Enjoy!!