Installing Podman Locally and on a VPS

Podman with podman-compose on macOS and on a Debian or Ubuntu server, with the same commands on both sides and a first-run check.

I wanted the same container runtime on my MacBook and on the VPS: same commands, same compose file, same mental model. I picked Podman over Docker mostly because it runs rootless by default and doesn't need a daemon on Linux. On a small VPS every background process costs something.

The setup

  • Local: macOS with Homebrew, Podman running inside its managed VM.
  • Server: Debian or Ubuntu VPS, Podman installed from the distribution's packages.
  • Compose: podman-compose on both sides, no Docker binaries involved.

Local installation (macOS)

brew update
brew install podman podman-compose

Podman on macOS runs inside a lightweight Linux VM. Initialise and start it:

podman machine init
podman machine start

A quick check that the client can reach the VM:

podman --version
podman info
podman system connection list

Gotcha: Homebrew installs both podman compose (the subcommand) and podman-compose (a separate Python project). The subcommand happily calls docker-compose if it's on the PATH, which defeats the point. Pin the provider explicitly:

export PODMAN_COMPOSE_PROVIDER=/opt/homebrew/bin/podman-compose
echo 'export PODMAN_COMPOSE_PROVIDER=/opt/homebrew/bin/podman-compose' >> ~/.zshrc
source ~/.zshrc

Server installation (Debian/Ubuntu VPS)

sudo apt-get update
sudo apt-get -y install podman podman-compose git

Same check as on macOS:

podman --version
podman info
podman system connection list

With several containers in one compose setup, I wanted service-name DNS to work out of the box: one service reaching another by its compose service name. The default installation doesn't always include the network plugins for this. Install netavark and aardvark-dns, Podman's network and DNS layer:

sudo apt-get -y install netavark aardvark-dns

Now compose services resolve each other by name inside the Podman network, without wiring IPs by hand.

First-run check (both environments)

Pulling a real image and running a throwaway container is the cheapest way to confirm that the runtime and the registry path both work:

podman pull docker.io/library/node:20-bookworm-slim
podman run --rm docker.io/library/node:20-bookworm-slim node --version

A Node version on stdout means the whole chain is healthy: runtime, image resolver, registry access, container exec.

Common first-install issues

  • connection refused on the Podman socket (macOS). The VM is not running or in a bad state. podman machine stop && podman machine start fixes it almost every time.
  • invalid username/password when pulling public images. Stale auth state in ~/.config/containers/auth.json. A plain podman pull often clears it without any extra login.
  • podman compose picks the wrong provider. Set PODMAN_COMPOSE_PROVIDER explicitly instead of relying on the auto-detection.

Day-to-day commands

The three commands I run ninety percent of the time, the same on laptop and server:

podman compose -f compose.yml up --build -d
podman compose -f compose.yml logs -f
podman compose -f compose.yml down

Takeaways

  • Keeping the local and the server installation symmetric pays off on every deploy: no mental translation needed.
  • Rootless is the default, and it's the right default for a small VPS with a single service.
  • To come back after a reboot, the compose stack needs a systemd unit; the restart policy alone is not enough.

More on this

Topic
  • Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.
Basis for
Uses
  • Podman Container engine without a background daemon that runs rootless by default on Linux and uses the same commands on macOS and on a server.
Mentioned in

Show in the graph view →