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-composeon 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 refusedon the Podman socket (macOS). The VM is not running or in a bad state.podman machine stop && podman machine startfixes it almost every time.invalid username/passwordwhen pulling public images. Stale auth state in~/.config/containers/auth.json. A plainpodman pulloften clears it without any extra login.podman composepicks the wrong provider. SetPODMAN_COMPOSE_PROVIDERexplicitly 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.
- 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
-
- Keeping a Compose Stack Running After a Reboot A systemd unit that starts a Podman compose stack on boot, so a website comes back by itself after the VPS restarts.
- 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
-
- Astro SSR with Podman: From Local Setup to VPS Astro with the Node standalone adapter in a two-stage Podman container, run locally with the same compose file that later goes to the VPS.
- Tags