How can I make a Docker container running on Windows (WSL2) accessible from a Raspberry Pi on the same network?

by

Summary

This incident involved a Dockerized WASP node running inside WSL2 on Windows, which was unreachable from a Raspberry Pi on the same LAN, despite exposed ports. The root cause was not Docker itself but the WSL2 networking model, which isolates Linux containers behind a NAT interface that is not directly reachable from the LAN.

Root Cause

The failure stemmed from how WSL2 uses a virtualized NAT network. Even when Docker exposes ports, they bind to the WSL2 VM’s virtual interface, not the Windows host’s LAN interface.

Key points:

  • WSL2 assigns its own internal IP (e.g., 172.x.x.x).
  • Docker binds to that internal IP, not the Windows LAN IP (192.168.x.x).
  • External devices on the LAN cannot reach services bound inside the WSL2 NAT.
  • Windows does not automatically forward ports from the host to the WSL2 VM.

Result: The Raspberry Pi’s requests never reached the container.

Why This Happens in Real Systems

This is a classic example of virtualization-induced network isolation. It appears frequently because:

  • WSL2 behaves like a lightweight VM, not a simple compatibility layer.
  • Engineers assume Docker port publishing works the same on Windows as on Linux.
  • NAT boundaries silently block inbound traffic.
  • Windows firewall rules often block forwarded ports unless explicitly opened.

Real-World Impact

This issue causes:

  • Inaccessible APIs from other devices on the network.
  • Misleading debugging signals (Docker shows ports exposed, but they’re unreachable).
  • Wasted time chasing nonexistent container misconfigurations.
  • Broken distributed systems, especially when nodes must communicate across machines.

Example or Code (if necessary and relevant)

A typical failing setup looks like this:

docker run -p 9090:9090 iota-wasp-node

Even though Docker reports the port as published, it is only reachable inside WSL2 or from the Windows host itself.

How Senior Engineers Fix It

Experienced engineers know that WSL2 requires explicit host-level port forwarding or running Docker in a different mode.

Common fixes:

  • Use netsh to forward ports from Windows → WSL2: 
    netsh interface portproxy add v4tov4 listenport=9090 listenaddress=0.0.0.0 connectport=9090 connectaddress=
  • Allow the port through Windows Firewall.
  • Bind the service to 0.0.0.0 inside the container.
  • Switch Docker to “Docker Desktop with WSL2 integration”, which handles forwarding automatically.
  • Run Docker natively on Windows or on a Linux machine to avoid WSL2 NAT entirely.

Why Juniors Miss It

Less experienced engineers often overlook this because:

  • Docker’s port publishing appears to work normally.
  • WSL2’s NAT behavior is not obvious and poorly surfaced.
  • They assume “exposed port = reachable port”.
  • Windows networking layers (WSL2 → Windows host → LAN) are not intuitive.
  • Tutorials rarely mention cross-device LAN access.

The key lesson: Exposing a port in Docker does not guarantee reachability across virtualization boundaries.

Leave a Comment