Remote Debugging Cloud Foundry Apps

Context

While debugging Java applications in an IDE like IntelliJ Idea is straightforward, it involves slightly more effort to debug a remotely running app. While debugging a remotely running app in production is generally not a good idea, the ability to remote debug apps in lower environments, like integration testing, may be useful.

Cloud Foundry is a platform that allows you to deploy and run your workloads easily and intuitively. IntelliJ Idea is a popular IDE, especially for Java developers.

In this article, we will see how to establish a remote debugging session with a remotely running Java Spring Boot app in Cloud Foundry. It need not be a Spring Boot app for you to attach a remote debugger. You just need to ensure that the JVM is up and running when you start your remote debugging session. A typical example is an app that exposes some REST endpoints listening on some server port like 8080. However, you won't be attaching your remote debug session with that port. You will be attaching to a different port like 5000 on which the JVM would be listening for connections from your IDE.

Preparing Your Cloud Foundry App

Prerequisites

1. You should have a Cloud Foundry instance and a space setup. Cloud Foundry is also provided as a managed service from some public Cloud Providers. You can run Cloud Foundry on your own servers as well. See this for reference.
2. You should have the Cloud Foundry CLI installed on your machine from where you will be initiating the deployment using the cf push command.
3. You should have a Java Spring Boot app ready to deploy; it should compile well and if you are using a build tool like maven, you should run the mvn package command. Ensure that you use the Maven Spring Boot plugin so that all your dependencies are packaged in the deployable. You should be ready with the final jar file (assuming you are using packaging type as jar) to do the deployment.

Steps

1. Issue the following commands to log in to Cloud Foundry and push your app

# Provide endpoint, credentials when prompted
cf login

# Switch to your space in Cloud Foundry
cf target -s YOUR-CF-SPACE-NAME

# Push your app to cloud Foundry; This will push the app and will not start it right away
cf push -s cflinuxfs3 YOUR-CF-APP-NAME --no-start -p "full-path-to-your-jar-file"

# Set an environment variable to enable debugging for your CF app
cf set-env YOUR-CF-APP-NAME JBP_CONFIG_DEBUG '{enabled: true, port: 5000}'

# Start your app in Cloud Foundry
cf start YOUR-CF-APP-NAME

2. When your app starts, it should be ready to accept connections on the 5000 debug port. It is assumed that your app is also listening for traffic on a port like 8080 for HTTP traffic.

Setting Up IntelliJ Idea for Remote Debugging

1. It is to be noted that, your remotely running app should have ssh enabled. By default, it is enabled. If not enable SSH using the cf enable-ssh YOUR-CF-APP-NAME command.

2. You will next establish an SSH tunnel between your local machine where you will start the debugging session and your remote app using the following command.

cf ssh -N -T -L 5000:localhost:5000 YOUR-CF-APP-NAME

3. You are now ready to start your debugging session in IntelliJ Idea. Start IntelliJ Idea and create a Remote JVM Debug Configuration with the following settings.

4. Add a breakpoint where you want to receive control when the debugging starts.

5. Now select the Remote JVM Debug Configuration that you created above, and click on the green debug icon in IntelliJ Idea.

6. Now make the API call (or whatever triggers your logic) so that your breakpoint would be hit.

7. You would see that code execution halts at your breakpoint and you can now single step from that point in debug mode.

Troubleshooting

• I can't establish the SSH tunnel — Ensure that the remote debug port in Cloud Foundry is the same as the debug port on your local machine.
• My debug session won't start — Ensure that the SSH tunnel is correctly established.
• Control is not returned to the correct debug breakpoint — Ensure that the jar deployed to Cloud Foundry was created from the code in your IDE. If the binary does not match your source code, you will get unexpected results.
• My debugging session is very slow — If your remote machine and your local IDE are geographically distant, you may expect higher latencies.