How to migrate from Docker to Podman and manage containers with Podman Desktop

A comprehensive guide to migrating from Docker to Podman and getting started with Podman Desktop. Learn how to install Podman Desktop, configure container registries, and run your first containers using this Docker Desktop alternative that provides a lightweight, daemon-less container management experience.

How to migrate from Docker to Podman and manage containers with Podman Desktop

Ever since Docker announced their licensing changes, there was a demand for a working alternative. People around me know I have a soft spot for Podman. Podman is nearly a 100% command-line compatible with Docker. I already linked Cedric Clyburn’s excellent article on transitioning from Docker to Podman in my previous Podman-related article. Even my local Minikube comes with Podman driver, so running Kubernetes workloads is effortless.

Last year, Podman described a working docker-compose solution using podman-docker. But for enterprises, Podman still wasn’t a real alternative because of its lack of a UI akin to Docker Desktop. I’ve never used Docker Desktop because my command line foo was strong enough. But at Mister Spex, we leave our tech employees the freedom of choice to decide between Windows, Mac and Linux and for the first two, Docker Desktop was basically without alternative.

Podman Desktop enables you to easily work with containers from your local environment. Podman Desktop leverages Podman Engine to provide a lightweight and daemon-less container tool. — podman-desktop.io

Finally, in October at KubeCon North America, Podman Desktop was unveiled, providing this last missing piece. Podman Desktop’s mission is, to ease the handling of containers and deploying pods on Kubernetes, shielding you from the complexity of using podman cli and kubectl using a nice streamlined UI. All so you can focus on your actual tasks instead of caring about running containers. It’s available for Windows, Mac and Linux. Sounds promising? Follow me in taking Podman Desktop for a test ride…

Installing Podman Desktop and Podman

I’m starting on a fresh VM, since my local environment already has all the tools needed, and I want to know how it feels to set up a local working environment from scratch. After setting up a fresh Ubuntu 22.04 VM, I’m ready to start. For Linux, Podman Desktop comes in a nice flatpak, so I’ll install flatpak and podman (yeah, I’m not building from source):

sudo apt install flatpak

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

After restarting my VM, flathub is available, and I can move to install Podman Desktop.

flatpak install podman-desktop-0.9.1.flatpak

Podman Desktop is installed. Easy. Once Podman Desktop has started, it tells me Podman is running. That can’t be right. And indeed, hitting CTRL+R to reload, instead the client tells me that there is no installation of Podman found on my system. I’ve checked the documentation, and on Windows it would now ask to install Podman. On Linux, we do this on our own.

sudo apt install podman

Podman is now installed and I head back to the client. I don’t even have to hit CTRL+R. A small toggle called “Initialize Podman” is waiting to be toggled. “Error: No initialize implementation found for this provider”. Weird. I go to Settings, Extensions, Podman and disable and re-enable the Podman Extension. Now, Podman Desktop correctly shows me that Podman is running. Time to try something practical.

NGINX provides us with NGINX hello-world images on github. That seems like a small enough case to try. The images are hosted at Docker Hub. In the client, I go to the Images tab and click “Pull Image”. It tells me that the container engine isn’t running. Strange. Probably, it hasn’t really registered my installation of Podman. I completely quit the client and then reopen it. Going back to the Images tab, I click “Pull Image” again. That’s better: It asks me what image to pull. I paste “nginxdemos/nginx-hello” and click “Pull image” to greeted by:

Could not connect to Podman: (HTTP code 400) unexpected — failed to resolve image name: short-name “nginxdemos/nginx-hello:latest” did not resolve to an alias and no unqualified-search registries are defined in “/etc/containers/registries.conf”

Admittedly, I should have checked the Podman Desktop troubleshoot section earlier, but my Pull-Image-Issue isn’t there. Why should Linux users use Podman Desktop, anyway? I run the test image pull manually.

podman run quay.io/podman/hello

That works. And then it hit me. I should have read the error message until the end. Podman was able to manually run the container because what I used there, was a qualified image name using the quay.io repository. My nginx-hello image isn’t qualified by its repository. And since I’m lazy and don’t want to qualify my images all the time, I need to add the search registries. It’s right there in the error message.

echo "unqualified-search-registries = ['docker.io', 'quay.io']" \ | sudo tee -a /etc/containers/registries.conf

After restarting the client, it shows my manually pulled image and exited container. I can finally pull the image. Nice. Of course, simply qualifying my image, pulling “docker.io/nginxdemos/nginx-hello” would have sufficed. But why would you type more than absolutely necessary?

Running my first container

So now I have the image, I want to run the container. In the Images tab, I hover over my newly fetched image and select “Run Image”. It asks me for a Port Mapping, probably derived from the Docker file. That’s cool. I leave the default and hit “Start Container”. The client changes to the container tab and I can see my container booting up.

I can click “Open Browser”. It opens localhost:9000, which, weirdly, doesn’t bring the site up. So, I close the browser and focus on the Client again for a moment. If I click the container’s name, it brings me to the container’s details. Upon inspection, I find that port 9000 on my host is mapped to port 80 in the container, and port 8080 on my host is mapped to port 8080 in the container. That makes sense. I click “Open Browser” again and change the URL manually to localhost:8080 to finally be greeted by a running NGINX. Cool.

So, was that easier than using podman cli? Not really. But, it was more convenient, definitely. I can see how having a graphical user interface makes this more approachable. Hopefully, the installation on Windows or Mac is clearer. I’ll leave setting up and deploying this container on Minikube for another day…

So, are you finally moving to using Podman? What’s keeping you? Have you been able to get it running on Windows or Mac? Please let me know!

Also check this out:


Originally published on Medium