Integrating Podman Desktop with your own wsl2 distribution

Abstract

Previously, when I was using the Docker Desktop app, the integration between the app itself and the Docker installation within my WSL2 Ubuntu 22.04 distro was seamless. All I had to do was open the options and switch a toggle next to my Linux distribution.

Recently, I had to transition to the Podman Desktop app. Since Podman (similar to Docker) uses its own distribution within WSL to host its containers, I was surprised that the process wasn’t as smooth as it was with Docker Desktop. Before I could use Podman similarly to how I had used Docker, I had to do quite a bit of work to get everything set up.

I hope following my steps will save you some time when setting it up for yourself!

Prerequistions

All of the further steps has been done on WSL 2.3.24.0, Windows 10.0.19045.5011.

However, as far as I can tell from reading all the requirements correctly, you will need:

Windows 10 version 2004 and higher (>Build 19041)
wsl2 pre-installed (it will make your next step easier, if you install it without podman ingeration)
- If you are using Windows 11, you can run wsl --install --no-distribution in PowerShell
- Or install from PowerShell with winget install -id=Microsoft.WSL -e
- Or follow steps from official MS Documentation

Installation

Setting up Podman Desktop

Install Podman Desktop App on your Windows machine
- using winget within PowerShell winget install -e --id RedHat.Podman
- or by following steps on the official Podman Desktop Website
Set up your podman machine by
- following the steps shown in the application
- or by running podman machine init followed by podman machine start in the PowerShell
  
  By default, your machine should be set in “rootles” mode and named as ‘podman-machine-default’

Tip

You can run PowerShell commands directly from your Linux distribution in WSL by prepending the commands with powershell.exe <command>

Check the status of your machine by executing podman machine info

PS> podman machine info
  host:
    ...
    currentmachine: podman-machine-default
    defaultmachine: podman-machine-default
    ...
    machinestate: Running

If you need to run the machine in “rootful” mode (e.g., for exposing ports below 1024), run: podman machine set --rootful

The above steps will create a Podman distribution in your WSL2. You can check it from PowerShell withwsl -l

PS> wsl -l
  Windows Subsystem for Linux Distributions:
  Ubuntu (Default)
  podman-machine-default
  podman-net-usermode

Login to your podman-machine-default distribution by running podman machine ssh in PowerShell
Check the /etc/fstab content
```
[user@PC ~]$ cat /etc/fstab
  ## fstab intentionally empty for containers
  /run/user/1000/podman/podman.sock /mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock none noauto,user,bind,defaults 0 0
```
- If the file content is similar to mine (the paths might be different), then you’re good to go. The fstab file will ensure that the Podman socket is automatically mounted every time you start the Podman machine.
- If it’s not, you’ll need to add it manually. The Podman machine is almost fully debloated, so you’ll need to use vi or install vim/nano.
  
  This step is very important, because otherwise you will need to mount podman.sock manually after each system shutdown
Copy the mount destination path; you will need it in the next steps. In my case, it’s: /mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock
You can exit podman machine with exit. That’s all for now

Installing podman in Ubuntu-22.04

Warning

Do not install Podman from the default Ubuntu package repository, as the version you download will be too old to perform some of the steps described here.

Connect to your distro

If Docker is already installed, remove it from your distro.

remove Docker

[user@PC ~]$ sudo apt autoremove docker-ce docker-ce-cli containerd.io

remove the Docker repository and keys

[user@PC ~]$ sudo rm /usr/share/keyrings/docker-archive-keyring.gpg /etc/apt/sources.list.d/docker.list

Get newest podman version from official github (change <version> to the newest one)

[user@PC ~]$ wget https://github.com/containers/podman/releases/download/<version>/podman-remote-static-linux_amd64.tar.gz
[user@PC ~]$ mkdir -p ~/.podman                                                      # create podman directory in home
[user@PC ~]$ tar -C ~/.podman -xzf podman-remote-static-linux_amd64.tar.gz           # unpack the files to newly created directory
[user@PC ~]$ mv ~/.podman/bin/podman-remote-static-linux_amd64 ~/.podman/bin/podman  # rename file it to simply 'podman'

Append podman ~/.podman/bin to system path, for example by appending ~/.bashrc with
~/.bashrc
```
  if [ -d "$HOME/.podman/bin" ]; then
    PATH="$HOME/.podman/bin:$PATH"
  fi
```
I would also recommend adding a symbolic link for Docker integration, as some programs (e.g., VSCode) might try to use it by default ln -s ~/.podman/bin/podman ~/.local/bin/docker
In some cases, it’s suggested to run sudo mount --make-rshared / efore the first Podman process starts to avoid certain WARNING messages, but I did not do that.

Connecting Ubuntu to podman machine via mounted socket

Now we will set up a “default” connection for Podman installed in our distribution, so that every time we execute a podman command, it will run inside the Podman distribution. This will allow us to observe and make changes through the Podman Desktop app.

Create a default connection between the distribution and the mounted socket that I asked you to remember from the instructions above
- To do so, execute below command replacing unix://<path> with the filepath from podman machine
```
podman system connection add --default podman-machine-default unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock
```
- Additionaly you can ensure that you has correct accesses
```
sudo usermod --append --groups 10 $(whoami)
```
Refresh your shell and try running podman pull hello-world (you can also use docker pull hello-world instead of Podman, as we created a symbolic link)
The image should be visible in the Podman Desktop app. You can also try accessing it the other way through the Podman Desktop app