Remote Debug on Rancher

Open

image-20241219-120739.png

Click on configMap and copy keyId and secretKey (it will be required later on)

if all of 3 prerequisite tools installed, please proceed with the following configurations:

AWS CLI:

• command to execute: aws configure

• paste previously copied keyId into in AWS Access Key ID prompt

• paste previously copied secretKey into in AWS Secret Access Key prompt

• type us-west-2 in Default region name prompt

• type json in Default output format prompt

Open

image-20241219-121121.png

kubectl:

• Command to execute: aws eks update-kubeconfig --region us-west-2 --name {{clusterName}} depending on there your environment has been deployed, that value should be placed in {{clusterName}} placeholder, in our case it's folio-edev

Open

image-20241219-121902.png

Once required tools installed and configured, visit: Folio Rancher Debugger

Part 2

Select desired namespace and deployment, click on "Start Debug" button

Open

image-20260303-065731.png

While the new target deployment's pod is being created, now it's time to start port-forward session, port-forward command will appear on UI(usually it takes ~10-15 seconds):

Open

Screenshot 2026-03-03 at 13.34.23.png

Copy command and paste to your terminal/cmd

Part 3: Configure IntelliJ IDEA

Step 1: Open Debug Configurations Dialog

1. In IntelliJ IDEA, go to Run menu → Edit Configurations...

2. Alternatively, use keyboard shortcut: Ctrl+Alt+R (Windows/Linux) or Cmd+Option+R (Mac)

3. Click the + button in the left sidebar to add a new configuration

4. Select Remote JVM Debug from the dropdown menu

Step 2: Create Remote Debug Configuration

1. Name: Enter a descriptive name (e.g., "Remote Debug - Spitfire - mod-audit")

2. Host: Set to localhost

3. Port: Set to 5005

Step 3: Configure VM Options

1. Enable Use module classpath: Check this option

2. Debugger mode: Select "Attach to remote JVM" (this should be default)

3. Transport: Select "Socket" (this should be default)

Step 4: Apply and Create Configuration

1. Click Apply to save the configuration

2. Click OK to close the dialog

Step 5: Start Port-Forward

Open your terminal/cmd and run the kubectl port-forward command that was displayed in the Debugger UI:

This command forwards: - Port 5005: Java Debug Wire Protocol (JDWP) for debugging - Port 8081: Application port for local testing

Step 6: Launch Debug Session

1. In IntelliJ IDEA, select your newly created remote debug configuration from the dropdown in the top-right toolbar

2. Click the Debug button (green bug icon) to start the debug session

3. You should see in the Debug console: "Connected to the target VM"

Step 7: Set Breakpoints and Debug

1. Open the source code file in IntelliJ IDEA

2. Click in the left gutter next to the line number where you want to set a breakpoint

3. When the application hits the breakpoint, execution will pause

4. Use the Debug panel to: - Step through code (F10 to step over, F11 to step into) - View variables and expressions - Use the console to execute commands in the current context

Step 8: Stop Debugging

1. Click the Stop button in the Debug toolbar

2. (Optional) Terminate the port-forward session in terminal: Ctrl+C

Important Notes

• Port-forwarding must be active while debugging; terminating it will disconnect the debug session

• The debug port 5005 is only available after you click "Start Debug" in the Folio Rancher Debugger UI

• If you don't see the breakpoint hit, verify that:

• The port-forward command is still running

• The remote JVM configuration host and port match the port-forward settings

• The breakpoint is in code that will be executed

• You can have multiple debug configurations for different namespaces/deployments

Troubleshooting

Connection refused error: Verify the port-forward command is running in your terminal

Breakpoints not hitting: Ensure you're debugging the same code version that's deployed in the pod

Slow stepping through code: This is normal for remote debugging; network latency may cause delays