← Home

Installing Podman Locally and on a VPS

Podman

If you use Podman both on your laptop and on a VPS, consistency matters more than fancy setup.

This guide keeps both environments aligned.

1. Local installation (macOS)

Install Podman and podman-compose with Homebrew:

brew update
brew install podman podman-compose

Initialize and start the Podman VM:

podman machine init
podman machine start

Quick validation:

podman --version
podman info
podman system connection list

If podman compose defaults to docker-compose, pin the provider:

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

2. Server installation (Debian/Ubuntu VPS)

Install packages:

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

Verify:

podman --version
podman info
podman system connection list

If you run compose workloads with service-name DNS, install network helpers:

sudo apt-get -y install netavark aardvark-dns

3. First run check (both environments)

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

If this works, your runtime and registry access are healthy.

4. Common issues

  • connection refused to Podman socket on macOS: restart the machine with podman machine stop and podman machine start.
  • invalid username/password while pulling public images: retry plain pull first; stale auth state can cause this temporarily.
  • podman compose uses the wrong provider: set PODMAN_COMPOSE_PROVIDER explicitly.

5. Minimal day-to-day commands

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

The goal is not a clever setup. The goal is a setup you can run half-asleep without surprises.

← Home