2023-05-09

Installing Podman on OS X with Homebrew

Update: After a few strange bugs involving volumes, I’ve moved from Podman to OrbStack, which is a great replacement for Docker for Mac. I’m still waiting for proper Docker contexts integration in testcontainers.org, so I can use the more minimal colima. But messing with global ENVs is a big no-go for me.

I’ve been trying to get away from Docker Desktop for years. It feels bloated, and I have some mixed feelings about Docker, Inc.

The Podman Logo is licensed under Apache License 2.0

Podman looks promising and is usable on OS X since March 2021¹. It runs in a local QEMU VM which is managed via podman machine, similar to the docker-machine application from a few years ago (which got replaced by Docker for Mac and then Docker Desktop). Basic container management works well and the VM seems to be fine energy-wise. And finally, the last blocking bug (for me) has been fixed - reason enough to write this blog ✌️.

Here’s my setup for a working Podman, Docker client and testcontainers.org setup on macOS Ventura:

$ brew info podman
==> podman: stable 4.5.0 (bottled), HEAD
Tool for managing OCI containers and pods
[...]
$ brew install podman
# for the docker client (backed by podman)
$ brew install docker
# makes docker work with the podman socket
$ sudo /usr/local/Cellar/podman/4.5.0/bin/podman-mac-helper install
# adjust resources as you like it - this may take some time
# without -v $HOME:$HOME volume mounts won't work
$ podman machine init --cpus 4 -m 4096 -v $HOME:$HOME --now
$ podman run hello-world

Hello from Docker!
$ docker run hello-world

Hello from Docker!

Containers are up and running! 🎉

Enable the OS X Keychain Credential Helper

Install the docker-credential-helper bottle and enable it in Podman² (and optionally Docker).

$ brew install docker-credential-helper

$ cat ~/.config/containers/auth.json
{
  "credHelpers": {
    "registry.example.com": "osxkeychain"
  }
}

# keychain prompts for credentials on the first login
$ podman login registry.example.com
Authenticating with existing credentials for registry.example.com
Existing credentials are valid. Already logged in to registry.example.com

And optionally for docker, if you want docker login to behave the same.

$ cat ~/.docker/config.json
{
  "credsStore": "osxkeychain",
  [...]
}

$ docker login registry.example.com
Authenticating with existing credentials...
Login Succeeded

Additional Setup for testcontainers.org

To get testcontainers.org to work with Podman, the podman machine needs to be rootful and Ryuk must run in privileged mode³.

$ podman machine stop
$ podman machine set --rootful
$ podman machine start
$ cat ~/.testcontainers.properties
ryuk.container.privileged=true
[...]

It looks like this is only required by Ryuk⁴, the optional resource reaper component. So disabling Ryuk might be an option, too.

See also this (little bit dated) quarkus.io blog post about Podman and testcontainers.org.

Sidenote: Broken DNS with Earlier Podman Versions on OS X

An open bug regarding DNS with podman login made the switch impossible for me, since it broke podman login to my companies’ container registry, which is only accessible via VPN.

But, fast-forward a few months, this is fixed! The current artifacts (> 4.5.0) on GitHub and Homebrew are built with Go > 1.20.x, which handles the OS X DNS magic with cgo disabled.

$ podman version
Client:       Podman Engine
Version:      4.5.0
API Version:  4.5.0
Go Version:   go1.20.3
Git Commit:   75e3c12579d391b81d871fd1cded6cf0d043550a
Built:        Fri Apr 14 15:28:20 2023
OS/Arch:      darwin/amd64

Server:       Podman Engine
Version:      4.5.0
API Version:  4.5.0
Go Version:   go1.20.2
Built:        Fri Apr 14 17:42:22 2023
OS/Arch:      linux/amd64