Init podman on MacOS

Prerequisites

You need the homebrew package manager for this:

brew install docker docker-compose sqlcl

Upgrade tolerant way of adding SQLcl to your PATH (add it to your ~/.bashrc or ~/.zshrc):

SQLCLPATH=$(ls -t $(brew --prefix)/Caskroom/sqlcl | head -1)
PATH=$(brew --prefix)/Caskroom/sqlcl/$SQLCLPATH/sqlcl/bin:$PATH

Read this for more information.

Installing Podman

If you have no Docker runtime yet, I recommend doing the following:

brew install podman

podman machine init

# I recommend increasing the resources if you have enough
podman machine set --memory 4096
podman machine set --cpus 3

podman machine start

# if it says something like:

# The system helper service is not installed; the default Docker API socket
# address can’t be used by podman. If you would like to install it, run the following commands:
# sudo /opt/homebrew/Cellar/podman/5.3.1/bin/podman-mac-helper install
# podman machine stop; podman machine start

# Please do so

Now test that podman works:

podman ps

The project’s scripts (install.sh, local-26ai.sh, etc.) natively detect Podman — if docker isn’t installed they automatically use podman and the native podman compose subcommand. You can run them as-is. If you have both Docker and Podman installed and want to force Podman, set CONTAINER_CLI:

CONTAINER_CLI=podman ./install.sh

If you’d rather route the scripts’ docker usage through Podman’s Docker-compatible socket instead, you can still do that — test it with docker ps.

Troubleshooting

If this does not work please follow this guide.

If you have this file ~/.docker/config.json, delete or rename it if you see this error: error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH.

Alternatively, you can drive the stack directly with the native podman compose subcommand:

podman compose up -d
podman compose stop
podman ps
# etc

Use podman compose (the subcommand), not the standalone podman-compose package — the latter can cause trouble and doesn’t support everything in this project’s docker-compose.yml.

After a restart

After a restart of your Mac, you need to start the Podman machine again:

podman machine start

Equally you can stop it with:

podman machine stop

But I recommend stopping the database before stopping the Podman machine:

local-23ai.sh stop