Debugging Remote Docker Applications Locally Using SSH Local Port Forwarding (-L Flag)

08 Jul, 2024

Why SSH Local Port Forwarding Matters for Remote Docker Debugging

Imagine you have a Dockerized application running on a remote server — for example, a Pop!_OS machine — and you want to debug its web interface or API locally on your laptop. Directly exposing the remote ports to the internet can be risky and is usually blocked by firewalls. How can you securely access the remote Docker service as if it were running locally?

This is where SSH Local Port Forwarding, enabled by the -L flag, steps in. It creates a secure tunnel that forwards traffic from a port on your laptop to a port on the remote server, enabling you to interact with your Docker application as if it were running on your own machine.

Understanding the -L Flag: How Local Port Forwarding Works

The -L flag in SSH sets up Local Port Forwarding, also called SSH tunneling. The syntax looks like this:

ssh -L :: user@remote_server

What happens under the hood?

• SSH creates a secure tunnel between your laptop and the remote server.
• Any traffic you send to localhost: on your laptop is forwarded through this tunnel.
• The remote server receives this traffic on :.
• For example:

ssh -L 8050:localhost:8050 user@pop-os-server

This means:

When you open http://localhost:8050 on your laptop’s browser, the request is securely tunneled to port 8050 on the remote Pop!_OS server, where your Docker app is listening.

Debugging with Verbose Output: Using -v Flags for Insight

When setting up SSH tunnels, you might encounter connection issues or want to understand what’s happening behind the scenes. The -v flag enables verbose output, which logs detailed connection events.

Basic verbose mode:

ssh -v -L 8050:localhost:8050 user@pop-os-server

More detailed debugging:

ssh -vvv -L 8050:localhost:8050 user@pop-os-server

Sample verbose output highlights:

debug1: Local connections to LOCALHOST:8050 forwarded to remote address localhost:8050
debug1: channel 0: new [port listener]
debug1: Local forwarding listening on ::1 port 8050.
debug1: Remote connections from LOCALHOST:8050 forwarded to local address localhost:8050
debug1: Authentication succeeded (publickey).
debug1: channel 0: free: port listener, nchannels 1

This output shows:

• SSH establishing the connection
• Setting up the port forwarding listener on your laptop
• Authentication success
• Tunnel creation confirmation

Verbose mode is essential when your SSH tunnel doesn’t behave as expected and helps pinpoint issues like port conflicts or authentication failures.

Long-Form Flag and Best Practices

The long-form equivalent of -L is --local-forward, though it’s rarely used:

ssh --local-forward=8050:localhost:8050 user@pop-os-server

Best practices for debugging remote Docker apps:

• Always use the -L flag to securely forward ports instead of exposing Docker ports publicly.
• Use -v or -vvv to debug connection problems.
• Confirm that the remote Docker container is listening on the forwarded port.
• Test connectivity locally by curling or browsing localhost: after establishing the tunnel.

... thats all fo rnow