Using Podman on Mac OSX
By Mark DeNeve
Over five years ago I bought an Apple MacBook Pro to learn Go and deep dive into things like containers and Kubernetes. My reasoning was simple, OSX was “*nix” like, the keyboard was amazing, and I could use Docker Desktop to run and manage containers on this machine. I could have used a Windows machine or built a Linux machine, but I wanted the ease of use of Mac, without having to worry about the constant hassles of patching (Windows) or limitations on drivers and power management (Linux). Over these past few years I have become addicted to using a Mac for my day-to-day work… However starting last year Docker made a change to their licensing terms on Docker Desktop as well as constant reminders to “upgrade to the latest version” have forced me to look elsewhere.
On my Linux servers, I had long since moved over to Podman as a full replacement for Docker. Not only does it work as a drop-in replacement, but I also don’t need to run the docker daemon, or run the docker command as root. But I still use my trusty Mac for my day-to-day testing and development so what is an OpenSource GitOps practitioner to do … Enter “podman machine.”
Until recently, while podman machine has worked on Mac, there has been a big limitation with using Podman as a full replacement of Docker Desktop, host volume mounts, ie. the ability to mount a local folder into a container. With the recent release of Podman 4.0, this limitation has been lifted! This is a brand new feature, so there may be a few limitations and gotchas but in testing a pre-release of Podman for this blog post, I did not run into any issues. The implementation is also still in progress, and based on what I have read, will continue to improve with later releases. That being said, “your mileage may vary”.
My MacBook is an Intel based machine, but per the documentation, this should work for both x86 as well as the new M1/arm based hardware.
Requirements
- Mac Machine - I have tested this with an Intel based Mac, but per the documentation, it should work for M1 hardware as well.
- Homebrew installed
- Docker has been removed from your machine - I am not sure if this is an absolute, but it is on mine :)
Installing Podman
We will be using Homebrew to install Podman in one easy to run command. Homebrew will install Podman and its required dependencies.
$ brew install podman
If you wish to use commands that use the Docker API socket, you will need to install the podman-mac-helper utility. Run the following command to install this additional helper. Since this program needs elevated privileges to install yuo will be prompted for your password.
$ sudo /usr/local/bin/podman-mac-helper install
Initializing the Podman VM
Just like Docker Desktop a Linux VM is required to be able to run Linux Containers. While Docker Desktop on Mac did this in the background, with Podman, we need to explicitly create and start the vm. Podman uses Fedora CoreOS as the base operating system, and automatically handles updates of this OS as they are released (about every 14 days).
The quickest way to getting moving with Podman on OS X is to use the podman machine init command:
$ podman machine init --now
Extracting compressed file
Image resized.
Machine init complete
INFO[0000] waiting for clients...
INFO[0000] new connection from to /var/folders/61/fzg790ts6x3_06vh01rjsntm0000gn/T/podman/qemu_podman-machine-default.sock
Waiting for VM ...
INFO[0023] Socket forward established: /Users/markd/.local/share/containers/podman/machine/podman-machine-default/podman.sock to /run/user/501/podman/podman.sock
API forwarding listening on: /var/run/docker.sock
Docker API clients default to this address. You do not need to set DOCKER_HOST.
Machine "podman-machine-default" started successfully
NOTE: When you first run the podman machine commands you may be prompted to allow network connections, be sure you click “allow” or your Podman experience will be severely limited.
By default, the podman machine init command will create a virtual machine that has 1 CPU, 2GB of RAM and 100GB of disk space. If these defaults are not satisfactory for your applications, it is possible to override the defaults by using the following command line options:
- –cpus
- –disk-size
- –memory
There are additional “geek knobs” that can be used to customize the Podman vm. The full list can be found here podman machine init.
If you have muscle memory like me, you can also create an alias for the podman command to docker as the podman utility uses the same command line options and for most commands is a drop in replacement.
$ nano ~/.bash_profile
# add the following line to your bash profile
alias docker='podman'
Testing it out
We can now start running containers on our Mac machine, just like with Docker Desktop. Let’s start the Docker Desktop “getting started” pod:
$ podman run -dp 8080:80 docker/getting-started
Resolving "docker/getting-started" using unqualified-search registries (/etc/containers/registries.conf.d/999-podman-machine.conf)
Trying to pull docker.io/docker/getting-started:latest...
Getting image source signatures
Copying blob sha256:f2303c6c88653b9a6739d50f611c170b9d97d161c6432409c680f6b46a5f112f
Copying blob sha256:59bf1c3509f33515622619af21ed55bbe26d24913cedbca106468a5fb37a50c3
Mounting local volumes
In Podman version 4.0, local volume support is added as part of the machine initialization. To enable this support we will need to delete and re-create our podman machine to continue.
$ podman machine list
NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE
podman-machine-default* qemu 7 minutes ago Currently running 1 2.147GB 107.4GB
$ podman machine stop
Machine "podman-machine-default" stopped successfully
$ podman machine rm
Are you sure you want to continue? [y/N]
With our test podman machine deleted, we will create a new one and attach it to our local file system. To make a local folder available, we need to mount it into the Podman virtual machine. If we want to make the folder structure /Users/markd/Share available within a Podman container, we need to first make that folder structure available to the Podman virtual machine. We will mount that folder structure on /home/core/Share which is the core user’s home directory within the Podman machine.
$ mkdir ~/Share
$ podman machine init -v ~/Share:/home/core/Share --now
Extracting compressed file
Image resized.
Machine init complete
INFO[0000] waiting for clients...
INFO[0000] new connection from to /var/folders/61/fzg790ts6x3_06vh01rjsntm0000gn/T/podman/qemu_podman-machine-default.sock
Waiting for VM ...
INFO[0018] Socket forward established: /Users/markd/.local/share/containers/podman/machine/podman-machine-default/podman.sock to /run/user/501/podman/podman.sock
Mounting volume... /Users/markd/Share:/home/core/Share
Machine "podman-machine-default" started successfullySo what we now have is the Mac host folder /Users/markd/Share mounted in the Podman virtual machine at /home/core/Share. This will become important in the next step when we run our podman commands.
Testing Local Volume Mounting
With the podman machine configured for local file sharing, we can now run a podman command and mount our local storage. The mount command is the same as the docker command -v <local path>:<container path> HOWEVER remember that we are using the Podman virtual machine which has mounted the Mac local Share folder to /home/core/Share so we need to use THAT as our “local path”:
$ echo "Hello" > ~/Share/hello.txt
$ podman run -ti --rm -v /home/core/Share:/Share fedora:35
Resolved "fedora" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull registry.fedoraproject.org/fedora:35...
Getting image source signatures
Copying blob sha256:58c379c45b4e802c2d39986d161aa987d0f684dcf6bef5a955e042724c60ff68
Copying blob sha256:58c379c45b4e802c2d39986d161aa987d0f684dcf6bef5a955e042724c60ff68
Copying config sha256:73440715a548019127335111c8b8c94b443f7a6024bcfd0a3a07835e5e5d2659
Writing manifest to image destination
Storing signatures
[root@bfa74a5ca7e6 /]
At this point, we are now running inside our Fedora container image. Lets take a look at the “hello.txt” file and then make a small modification to it so we can ensure that the process works.
[root@bfa74a5ca7e6 /] cat /Share/hello.txt
Hello
[root@bfa74a5ca7e6 /] echo 'hello from the other side' >> /Share/hello.txt
[root@bfa74a5ca7e6 /] exit
Back on your Mac, you should be able to cat out the ~/Share/hello.txt file and see the contents that we put in that file, from within the container.
$ cat ~/Share/hello.txt
Hello
hello from the other side
There you have it! Shared folder between your Mac and your Podman container.
But what about my GUI?
I never used the Docker Desktop GUI, as I preferred to stick with the command line. With Podman, at this time, there is no official GUI. However, if you follow the commit logs, as well as some of the GitHub issues (such as this one: RFE Provide a Podman Desktop for Linux, Windows and, Mac) you will see that there are some plans for a GUI in some way shape or, form in the future.
UPDATE The Podman project has released a UI for called Podman Desktop. This UI is the perfect companion to Podman on your platform of choice.
Advanced Usage
One final “geek knob” to mention, “–rootful”. As previously mentioned, Podman runs containers “rootless”, ie. without the need for root privileges. Now we are not talking about root privileges on your Mac, but on the Podman virtual machine that is running your containers. If you have containers that must be run as root, it is possible to create a podman machine that will run its containers as root. This can be done by running the following command when you create your podman machine:
$ podman machine set --rootful
Extracting compressed file
Image resized.
Machine init complete
INFO[0000] waiting for clients...
INFO[0000] new connection from to /var/folders/61/fzg790ts6x3_06vh01rjsntm0000gn/T/podman/qemu_podman-machine-default.sock
Waiting for VM ...
INFO[0018] Socket forward established: /Users/markd/.local/share/containers/podman/machine/podman-machine-default/podman.sock to /run/podman/podman.sock
API forwarding listening on: /var/run/docker.sock
Docker API clients default to this address. You do not need to set DOCKER_HOST.
Machine "podman-machine-default" started successfully
Conclusion
If you are looking for a replacement for Docker Desktop on your Mac, the latest release of Podman may be just the thing you are looking for. With support for local volumes in the latest release, the user experience is that much closer to Docker Desktop. No more prompts to upgrade your Docker Desktop every week, and you can breath a sigh of relief that you don’t need to worry about if the Docker Desktop license effects you or not or purchasing a Docker license.