Make Podman support more prominent in the documentation

[rgaiacs]

By

• using "container" instead of Docker when possible
• mention Podman configuration

[rgaiacs]

Please correct me if I got something wrong.

Before #1402, repo2docker used Docker SDK for Python for all operations with Docker. The Docker client was created using from_env() that read information from the DOCKER_HOST environment variable. This allowed users to configure DOCKER_HOST to point to their Podman installation, see procedures.

After #1402, repo2docker did not work with Podman. Changes in DockerEngine included in this pull request, restore the support to Podman.

Regarding container technology, the big players are

• Docker
• Podman (backed by Red Hat)
• Singularity (from Sylabs)
• Apptainer (fork of Singularity and under the umbrella of the Linux Foundation)

Podman keeps some level of compatibility with Docker. As far as I know, Singularity / Apptainer are incompatible with Docker.

My first question is, should repo2docker also support Podman as first class container engine? I mean: repo2docker documents how to use Podman and run tests with Podman.

If the answer is "yes", a follow up question is what would be the road map for repo2podman, a plugin for repo2docker that @manics developed.

[minrk]

My understanding was that podman was supported as long as it the engine backed by the docker cli (e.g. I use colima, not docker engine), but podman cli is not supported first-class in this package. Is that accurate, @manics?

I agree generally that pointing most language to OCI terms is good, but I don't know what commitment we are making in terms of cli compatibility assumptions.

[manics]

Originally repo2docker should've worked fine with Podman when run as a service since podman has a docker compatible API:

podman system service --time 0
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

After #1402 we're now using the Docker CLI. In general the Podman CLI should be compatible, but I haven't looked at how good buildx support is. If it currently works I've no objection to supporting if, and ensuring that any future changes to repo2docker only use buildx features that podman supports.

[minrk]

If we've got tests running that verify it (to a reasonable degree), I'm happy to make the support official.

[rgaiacs]

After

• change the code to do base the logic in DOCKER_HOST
• add container_cli as a GitHub Actions matrix dimension

most of the tests using Podman fails. One of the tests fails in

repo2docker/repo2docker/app.py

Lines 633 to 634 in 358888c

	image = client.inspect_image(self.output_image_spec)
	image_workdir = image.config["WorkingDir"]

When I try to investigate it locally, I observe

>>> import docker
>>> client = docker.APIClient(base_url="unix:///run/user/1000/podman/podman.sock")
>>> image = client.inspect_image("localhost/r2d-tests-dockerfile-2fsimple-1759752459")
>>> image.config
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    import platform
    ^^^^^^^^^^^^
AttributeError: 'dict' object has no attribute 'config'
>>> dir(image)
['__class__', '__class_getitem__', '__contains__', '__delattr__', '__delitem__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getstate__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__ior__', '__iter__', '__le__', '__len__', '__lt__', '__ne__', '__new__', '__or__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__ror__', '__setattr__', '__setitem__', '__sizeof__', '__str__', '__subclasshook__', 'clear', 'copy', 'fromkeys', 'get', 'items', 'keys', 'pop', 'popitem', 'setdefault', 'update', 'values']
>>> image.keys()
dict_keys(['Id', 'RepoTags', 'RepoDigests', 'Parent', 'Comment', 'Created', 'ContainerConfig', 'DockerVersion', 'Author', 'Config', 'Architecture', 'Os', 'Size', 'VirtualSize', 'GraphDriver', 'RootFS', 'Metadata', 'Container'])
>>> image["Config"]
{'Hostname': '', 'Domainname': '', 'User': '1000', 'AttachStdin': False, 'AttachStdout': False, 'AttachStderr': False, 'Tty': False, 'OpenStdin': False, 'StdinOnce': False, 'Env': ['PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'LANG=C.UTF-8', 'GPG_KEY=A035C8C19219BA821ECEA86B64E628F8D684696D', 'PYTHON_VERSION=3.10.18', 'PYTHON_SHA256=ae665bc678abd9ab6a6e1573d2481625a53719bc517e9a634ed2b9fefae3817f', 'HOME=/tmp'], 'Cmd': ['/bin/sh', '-c', '"/bin/sh"'], 'Image': '', 'Volumes': None, 'WorkingDir': '', 'Entrypoint': None, 'OnBuild': None, 'Labels': {'io.buildah.version': '1.40.0', 'repo2docker.ref': 'None', 'repo2docker.repo': 'local', 'repo2docker.version': '2025.08.0+61.gced04a5'}}
>>> image["Config"]["WorkingDir"]
''

@manics do you know what might be happening?