DEV Community

G.L Solaria
G.L Solaria

Posted on

.NET Aspire and WSL Docker

#dotnet #docker

So you have probably heard how great .NET Aspire is. If you aren't convinced, take the time to watch this video .NET Aspire Tutorial For Beginners.

Currently, the only supported way to use Aspire on Windows requires either Podman or Docker Desktop to be installed. If, for whatever reason, you can't use either of these 2 options, there is another way to connect .NET Aspire directly to Docker running on WSL. But be warned - setting up this option isn't simple, isn't supported, and has some limitations. If you need something that is simple and supported, use Podman or Docker Desktop.

The solution I have posted below is not ideal and I am keen to hear from anyone who has managed to find a better solution. Creating a docker.cmd file with wsl.exe docker %* no longer works on the latest version of Aspire. Creating a wrapper application that correctly handles the complex argument escaping required to work with Aspire will probably end up blocked by Smart App Control unless you sign the application. So please post a comment if you have found a better solution that doesn't use Docker Desktop or Podman.

Install WSL

If you are not familiar with Windows Subsystem for Linux (WSL) then you have a steep learning curve and this approach may not be right for you. If you want to go ahead any way you can start to learn by going here.

To install WSL, open a powershell command prompt as Administrator and type:

wsl --install -d Ubuntu-24.04
Enter fullscreen mode Exit fullscreen mode

Follow the instructions to create a WSL user/password and reboot Windows.

Install Visual Studio Code

Next install VS Code.

Install Docker in WSL

Start a WSL Session from VS Code

Start VS Code and select Open a Remote Window in the bottom left of the window.

Then select Connect to WSL.

Install Docker on WSL

From a terminal in VS Code connected to WSL, install Docker on your instance of Ubuntu by following these instructions.

Allow Docker Commands to Run as Non-Root User

To be able to run docker commands on WSL without needing to run with sudo you will need to follow these instructions.

Install the Container Tools Microsoft Extension in VS Code

From the Extensions tab in VS Code connected to WSL, search for Container Tools and verify you have the found official Microsoft extension then install it.

Verify the Installation of Docker on WSL

Click on the container icon in VS Code connected to WSL and confirm the Container Tools extension can connect to the Docker daemon. If it is connected you should see No items found in the Images and Containers panel.

From a terminal in VS Code connected to WSL, run:

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

You should now see something like this:

Modify Docker Configuration to Listen on TCP

In a terminal opened in VS Code connected to WSL, run:

sudo nano /etc/docker/daemon.json
Enter fullscreen mode Exit fullscreen mode

Enter the following text and save:

{
  "hosts": [
    "unix:///var/run/docker.sock",
    "tcp://0.0.0.0:2375"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Next override the Docker daemon startup to use this new daemon.json configuration file by:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/override.conf
Enter fullscreen mode Exit fullscreen mode

Enter the following text and save:

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd
Enter fullscreen mode Exit fullscreen mode

Reload and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker
Enter fullscreen mode Exit fullscreen mode

Next allow the port through the Ubuntu firewall:

sudo iptables -I INPUT -p tcp --dport 2375 -j ACCEPT
Enter fullscreen mode Exit fullscreen mode

Finally note down the IP address of the WSL Ubuntu instance:

ip addr show eth0
Enter fullscreen mode Exit fullscreen mode

Add DOCKER_HOST Windows Environment Variable

We need to create an environment variable that will be used on the Windows side to communicate with Docker running in WSL.

To do this create a new user environment variable in Windows called DOCKER_HOST and set it to tcp://wslip:2375 where wslip is the IP address you noted down from the WSL command ip addr show eth0.

Download Docker CLI for Windows

Next we need the docker.exe that will run on Windows. The official builds of just the CLI are here. Download the latest and extract the zip file to some location.

Add the path to docker.exe to your Windows PATH environment variable.

Finally, verify you can now run docker commands that connect to your WSL docker engine by opening a powershell prompt and running:

docker image ls
Enter fullscreen mode Exit fullscreen mode

You should see the hello-world image in the output.

Limitations

You should now be able to run your .NET Aspire App Host project that manages containers but there are limitations.

You will need to keep your VS Code window to WSL open while you want to run your Aspire application. This is because Windows will automatically shut WSL down after a period of inactivity.

Also Windows may decide to change the IP address of your WSL instance. If it does, you will need to edit the DOCKER_HOST environment variable and restart your IDE. If this bothers you, you could look in to setting up a static IP address for WSL but this is also not straight forward.

Conclusion

I warned you it wasn't simple! If you know of a better way that does not involve installing another Windows application like Podman or Docker Desktop, then please leave a comment.

Top comments (0)