2021-09-01: Added note about socket bugfix PR
2021-09-01: Added troubleshooting section about port forwarding bug
2021-09-04: Added note about switching to Podman on Windows
2021-09-04: Added update about port forwarding PR
2021-09-04: Added note about M1 Mac support
2021-09-04: Added volume mount limitation
2021-09-04: Added podman-macos utility
Docker has recently announced that Docker Desktop will soon require a subscription and, based on the size of your company, may require a paid subscription. (It remains free for personal use)
There has been quite a bit of reaction to this news:
Depending on which side your opinions lie, you might be looking for alternatives. Well it just so happens that Podman posted this well-timed tweet:
So, lets give it a whirl...
Replacing Docker with Podman (on Mac)
Note: This currently doesn't work for Macs with an M1 CPU. I've come across this post in my search - Running Podman Machine on the Mac M1 - but I've not confirmed if it works or not.
brew install podman
Wait while brew downloads, builds and installs...
Create a virtual machine for Podman to run from:
✨ podman machine init Downloading VM image: fedora-coreos-34.20210821.1.1-qemu.x86_64.qcow2.xz: done Extracting compressed file 🕙 took 2m44s
Start the virtual machine and set up the connection to Podman:
✨ podman machine start INFO waiting for clients... INFO listening tcp://0.0.0.0:7777 INFO new connection from to /var/folders/x_/bfc7v6kn4fs0rl9k77whs0nw0000gn/T/podman/qemu_podman-machine-default.sock Waiting for VM ... qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.80000001H:ECX.svm [bit 2] 🕙 took 34s
alias docker=podman(Add this to your
.bashrc(if using Bash),
.zshrc(if using ZSH) or whatever the correct file for your shell is)
Replacing Docker with Podman (on Windows)
I don't currently have access to a Windows machine where I can test this out but Frank sent me this on Twitter that covers the process needed for those on Windows with WLS2 - How to run Podman on Windows with WSL2.
Ok, so it's not all completely pain free, there are a few issues you might hit...
Failed to parse config
Error: failed to parse query parameter 'X-Registry-Config': "n/a": error storing credentials in temporary auth file (server: "https://index.docker.io/v1/", user: ""): key https://index.docker.io/v1/ contains http[s]:// prefix
Podman seems more strict than Docker when parsing the config file, check the
~/.docker/config.json file for the key with the
https:// prefix (as mentioned in the error message) and remove it.
Sock already exists
✨ podman machine start ERRO "/var/folders/x_/bfc7v6kn4fs0rl9k77whs0nw0000gn/T/podman/qemu_podman-machine-default.sock" already exists panic: interface conversion: net.Conn is nil, not *net.UnixConn
This seems to happen (for me at least) when I've previously run
podman machine stop. It looks like the sock file isn't correctly being removed. Doing an
rm on that file mentioned in the error message will be enough to get you going again.
UPDATE: Looks like this will be fixed in an upcoming release. - PR
✨ podman run --rm -it -v $(pwd):/usr/share/nginx/html:ro --publish 8000:80 docker.io/library/nginx:latest Error: statfs /Users/marcus/web: no such file or directory
Podman machine currently has now support for mounting volumes from the host machine (your Mac) into the container on the virtual machine. Instead, it attepts to mount a directory matching what you specified from the virtual machine rather than your Mac.
This is a fairly big issue if you're looking for a smooth transition from Docker Desktop.
There's currently a fairly active issue about this limitation but as of right now there doesn't seem to be a nice workaround or solution.
Automatic published port forwarding
✨ podman run --rm -it --publish 8000:80 docker.io/library/nginx:latest & ✨ curl http://localhost:8000 curl: (7) Failed to connect to localhost port 8000: Connection refused
The current latest version of Podman (v3.3.1) has a bug where the automatic port forwarding from host to VM when publishing a port with the
-p / --publish flag doesn't work.
There's currently a couple workarounds for this:
The first is passing in the
--network bridge flag to the podman command, e.g.
✨ podman run --rm -it --publish 8000:80 --network bridge docker.io/library/nginx:latest
The other, more perminant option is to add
rootless_networking = "cni" under the
[containers] section of your
To follow the progress of this bug, please refer to the issue. UPDATE: This has now been merged and is expected to be released in v3.3.2 in the next few days or so.
Error: error creating build container: short-name resolution enforced but cannot prompt without a TTY
Ok, this is the big one and the major issue you'll likely hit making the switch today from Docker to Podman. Lets dive into it in a bit more detail...
First we need to understand what a short-name is in this context. It refers to container images that don't have a full domain name prefixed. You've likely come across these quite a lot before - e.g.
When using Docker, these images are actually first prefixed with
docker.io/library for those official images without a namespace) before being pulled.
Podman doesn't have this as a default. It can work in the same way as Docker but needs a bit of configuring.
It's worth breifly pausing here to explain why this behavior is different. Podman takes the secure by default attitude to configuration and installation, and this difference is a prime example of that mindset. You've likely heard in the news over the past few years about some of the supply chain hacks that have had a big impact on some companies and projects. One of the common attack vectors is tricking users into installing what they think is a legitimate package but actually contains malicious code. The use of short names for images opens up the risk of accidentally pulling the wrong image from the wrong registry.
To mitigate this risk Podman has a feature where it will prompt you asking which registry you'd like to pull the shot named image from and will then save that choice to speed things up later. (On a side note, there's a repo where the community is trying to collate a collection of some of the most widely used shortcodes - https://github.com/containers/shortnames)
So, Podman has this handy feature to help out with security so why are we seeing an error? Well, when running Podman on MacOS (or Windows) we're actually running it in a Linux VM and remotely connecting to Podman running in that machine. Because of this we don't have an interactive terminal with the underlying Podman engine so it is unable to recieve our choice if it asked us which registry to use.
There's a couple of solutions for this:
Instead of using short names we could switch to using fully prefixed images (this includes updating any
FROMcommands in our Dockerfiles also).
The other approach is to reduce this security feature to be on-par with the experience we're used to with Docker.
As the first solution really just relies on you changing the image names you're referencing, which will depend on how you're working, I'll focus on the second solution.
With our machine created and started (as outlined above) we need to access the machine to make a small configuration change. Thankfully Podman makes this quite easy:
podman machine ssh
This will drop you into an SSH session within the virtual machine created for Podman. Once in this machine we want to make a change to the
/etc/containers/registries.conf file. If we take a look at the file contents we'll see the final lines of it (at time of writing this) as followed:
# Enforcing mode for short names is default for Fedora 34 and newer short-name-mode="enforcing"
short-name-mode property has 3 possible values:
- enforcing: If no alias is found and more than one unqualified-search registry is set, prompt the user to select one registry to pull from. If the user cannot be prompted (i.e., stdin or stdout are not a TTY), Podman will throw an error.
- permissive: Behaves as enforcing but will not throw an error if the user cannot be prompted. Instead, Podman will try all unqualified-search registries in the given order. Note that no alias will be recorded.
- disabled: Podman will try all unqualified-search registries in the given order, and no alias will be recorded. This is pretty much the same behavior of Podman before short names were introduced.
If we want Podman to perform more like Docker we'll want to change this value to
sudo sed -i 's/short-name-mode="enforcing"/short-name-mode="permissive"/g' /etc/containers/registries.conf
There's one more property in this file that it's worth at least being aware of.
unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "docker.io", "quay.io"]
This property contains a list of all the registries that will be checked (in order) when looking up a short name image. Be sure the values in here are ones that you trust!
With that change made we can
exit from the virtual machine and Podman should then search for any short name images using these registries from now on.
I'm sure there's many more inconsistencies but so far I'm pretty impressed. I'm plan to try using Podman instead of Docker for a while and see how I get on. I'll try and update this post with anything more I find out.
If anyone wants to share their experiences with Podman please reach out to me on Twitter at @Marcus_Noble_.