Jay's blog

Tips For Becoming A Pod Person

Original art, with apologies to Donald Sutherland

I made the leap from Docker to Podman. Well... only on my personal laptop. Podman isn't a completely hassle-free, drop-in replacement for Docker. It's damn close! Close enough that I'm willing to use it at home, but it's still finicky and different enough that I'd spend too much time futzing at work trying to use it while keeping everything Docker-compatible for my colleagues.

Here are some tips if, like me, you're coming from Docker and you just want to get productive.

I need Docker Compose

A large part of Docker's value to me comes from Docker Compose. If switching to Podman meant losing Docker Compose, I wouldn't have switched.

Thankfully, Pop!_OS (and probably any other platforms that include Podman in their repos) has a package called podman-docker that satisfies packages that depend on Docker. Just make sure you install podman-docker before or at the same time as docker-compose so APT doesn't try to install Docker to satisfy Docker Compose's dependencies.

If you're feeling adventurous, Podman Compose is a thing. But it's not available via my OS's default repositories and Docker Compose is.

PermissionError: [Errno 13] Permission denied

I recently received this error when I tried running Docker Compose. I had already installed podman-docker like I mentioned. The solution was to add this to my .bash_profile:

export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock

I need Docker Hub

I also wouldn't use Podman if it meant I lost Docker Hub.

The easiest way to get access to Docker Hub with Podman is to write the following file to $HOME/.config/containers/registries.conf:1

registries = ['docker.io']

Potentially insufficient UIDs or GIDs available in user namespace

I had just installed Podman and I wanted use the NodeJS image from Docker Hub.

$ podman run -it --rm node
Resolving "node" using unqualified-search registries (/home/jsherby/.config/containers/registries.conf)
Trying to pull docker.io/library/node:latest...
Getting image source signatures
Copying blob ca3bce705f6c done  
Copying blob 167c7feebee8 done  
Copying blob e9cdcd4942eb done  
Copying blob 32fb02163b6b done  
Copying blob d6dfff1f6f3d done  
Copying blob 4f4cf292bc62 done  
Copying blob 8347f8b4b86b done  
Copying blob c5f20f1b0856 done  
Copying blob d220dfa3e187 done  
Error: writing blob: adding layer with blob "sha256:32fb02163b6bb519a30f909008e852354dae10bdfd6b34190dbdfe8f15403ea0": Error processing tar file(exit status 1): potentially insufficient UIDs or GIDs available in user namespace (requested 0:42 for /etc/gshadow): Check /etc/subuid and /etc/subgid: lchown /etc/gshadow: invalid argument

This seems to be a common issue.

First, make sure the fuse-overlayfs package is installed.

If you look around the internet, you're going to find advice telling you to add the following file at $HOME/.config/containers/storage.conf:2

driver = "overlay"

ignore_chown_errors = "true"

BUT BE WARNED! This change is meaningful and makes Podman behave differently than you probably expect. I'll quote the manual directly.

ignore_chown_errors can be set to allow a non privileged user running with a single UID within a user namespace to run containers. The user can pull and use any image even those with multiple uids. Note multiple UIDs will be squashed down to the default uid in the container. These images will have no separation between the users in the container.

Although this setup will make Podman stop complaining, there's a good chance this will bite you in the ass later on, especially if you're trying to stay compatible with Docker.

Instead, I added my user to /etc/subuid and /etc/subgid. Here's what both files look like on my machine:3


Then I ran podman system migrate and I was good to go.

  1. /etc/containers/registries.conf is the equivalent system-wide config file.

  2. /etc/containers/storage.conf is the equivalent system-wide config file.

  3. When supporting namespaces for multiple users, the middle value needs to be offset so the namespaces don't overlap. Check the man pages that come with your local shadow package for details.

#docker #podman