Please document known incompatibilities with Docker

[rgov]

I am a Docker Desktop for Mac user. I have tried a few releases of Podman under the impression that it is a drop-in replacement for Docker Desktop, based on comments on the website, in Red Hat blog posts, or hints provided by the tool itself, like:

What is Podman? Simply put: alias docker=podman

Most users can simply alias Docker to Podman (alias docker=podman) without any problems.

You can still connect Docker API clients by setting DOCKER_HOST using the following command in your terminal session: ...

“Does Podman support Docker Compose? Up until recently, the answer was “not yet”. With the soon to be released Podman v3.0, that answer changes to “NOW!”

However it seems that these are a little optimistic about the level of compatibility.

For example, in the current release of Podman 4.0.3, volume mounts on macOS are not transparently supported and must be initially provided to podman machine init—a feature just introduced in 4.0.2, but not explained in the release announcement. Understandably this is a complex feature to implement, but it is also extremely commonly used with Docker Desktop, so it is surprising that this limitation is not documented on the website or on any of the tutorials. The only mention of this caveat I could find is in a sentence in the middle of the 4.0 release announcement blog post:

More features, including support for volume mounts from the host, are planned for Podman v4.1, so stay tuned for more updates.

Moreover, on the What is Podman? page, the roadmap lists just a few upcoming features that seem relatively minor, like "enhancements to speedup pulling of images", that suggest that the core functionality is all there.

If users mistakenly believe that adopting Podman is seamless, and then run into a bevy of undocumented limitations, it will turn them off of trying again even after further improvements are made.

Please consider being more transparent about known Docker incompatibilities by publishing a page that prospective users can follow as development on Podman progresses.

[mheon]

I think the main point of confusion here is the conflation of Docker Desktop and the Docker command line application.

Podman's original goal was complete compatibility with the Docker command line application on Linux, minus the docker swarm clustering system. I am quiet confident that we've achieved our goal here; there are still differences, but they are minor (and usually fixed in the next release, one someone finds them).

Our second goal was to achieve complete compatibility with the Docker REST API, to support services that integrated with Docker using it. This is a much newer goal, but we've achieved broad compatibility here, with many services like Docker Compose being supported.

Our newest, and most recent, goal is to produce a solution to allow Podman to run on OS X and Windows, similar to the Docker Desktop application. We've been working on this for less than a year, and we're not quite there yet. Volume mounts will be working in the upcoming (sometime next week) 4.1.0 release (@baude can provide more details on this), there is work ongoing (albeit in the early stages) to provide a GUI - but you're quite correct that we're not there yet on compatibility.

If there are any issues with our documentation, it's because we did not envision ourselves attempting compatibility with Docker's desktop products until quite recently, and we instead focused purely on compability on a Linux system; and, as noted, we're quite confident in our compatibility there. Documentation can certainly be improved now that we've expanded in this direction, but I think it's perfectly reasonable for us to state we're compatible with Docker; we're just not feature-comparable with Docker Desktop (yet).

[rhatdan]

You state a "bevy of undocumented limitations" and then list one. Do you have any others that you noticed?

podman 4.1 will default to podman machine init -v $HOST:$HOST on a Mac and allow user to pre-configure other volumes they wanted mounted into their machines.

As an open source project, we welcome issues and pull requests to fix all areas including documentation and features.

[rgov]

You state a "bevy of undocumented limitations" and then list one. Do you have any others that you noticed?

I don't state this, I said if people encounter unexpected limitations after the website promises seamlessness, they're going to take a negative view of the project. There have been other examples, for instance if you had tried Podman on macOS this time last year, I believe port forwarding also did not work transparently.

Aside from Docker Desktop, Podman's default behavior is also to run rootless, which is another deviation from Docker that makes it not quite as simple as alias docker=podman. Technical details are explained in the podman manpage but it would be nice to know what this means in practice, e.g., published ports must be >= 1024, to know whether my application will run.

The core development team I think has better awareness of what features are still in development. If there are issues tracking each one then maybe a GitHub issue label could identify them and then the website could link to a search query.

(When the Docker project was promoting the new docker compose command to drop in place of the original docker-compose tool, they published a compatibility page and created an issue label that helps identify problems.)

[rhatdan]

These should probably be handled with troubleshooting.md for us. Podman is well known for defaulting to Rootless. Changing the default for Docker compatibility seems to hurt one of the big benefits of Podman.
Bottom line if you would like to start a document of differences of Podman on Mac versus Docker Desktop on Mac, then open a PR.

[mheon]

I don't think so?

The core of the issue here seems to be that many people conflate Docker Desktop and Docker the container-management daemon. Adding a bit of clarity to podman.io on how Podman replaces the container-management daemon portions but is moving to replace the entire package (just give us a bit of time to get it right) seems appropriate.

[rgov]

Podman is well known for defaulting to Rootless.

If the properties of Podman are so well known, then why bother explaining "What is Podman?" on the website? There are certainly users who have only ever used Docker and have never heard of rootless containers.

Changing the default for Docker compatibility seems to hurt one of the big benefits of Podman.

I don't suggest changing the default.

These should probably be handled with troubleshooting.md for us.

troubleshooting.md seems like the last ditch place to look, since users probably find it by being pointed to it by the GitHub issue template. It is a 1,200 line document and not the best way to organize this kind of "will it work for my use case?" information.

[afbjorklund]

We did something like alias docker='sudo podman' for minikube, since it (k8s) wasn't ready for rootless.

Exporting the whole home directory (in machine) was actually made opt-in on purpose, since it is a security issue.

[github-actions[bot]]

A friendly reminder that this issue had no activity for 30 days.

[rhatdan]

Since we have documents like troubleshoot.md and transfer.md with a lot of this information, I am going to close move this issue to a discussion. If we have ideas of what should be documented in these documents, then open new issues specific on what needs to be documented, or better yet open PRs with the actual documentation.

[tmmvn]

Here's one. Fresh Debian 11 server (also tried with whatever current podman on current CentOS 9 Stream). Did apt-get for podman. Running podman run -ti docker.io/wickr/bot-cloud:5.92.06.01 exits after displaying what node version is used and does not function.

Installed docker following official docker instructions. Running docker run -ti docker.io/wickr/bot-cloud:5.92.06.01 correctly shows a welcome screen and the container functions.

Tried going through all the run flags in podman that could make a difference and that could be different defaults, but couldn't figure out the magic combo. So definitely not a direct alias for docker as of now and not easy to figure out why something works in docker and not in podman.

[mheon]

That sounds like it could be a bug. Please file a bug report about this.

[JerryMWeeks]

Apologies if this has been answered by other docker answers but I am struggling.
does podman support pull of images from the Microsoft container hosting via Docker like mcr.microsoft.com/dotnet/core/sdk:3.1-alpine
I am getting name server failure / ping mcr.microsoft.com fails etc.
In the build code we do calls like this:
FROM mcr.microsoft.com/dotnet/core/sdk:3.1-alpine
COPY /Dockerfile.init /

There is a little about it discussed here:
NET Core Container Images now Published to Microsoft Container Registry

[mheon]

podman pull mcr.microsoft.com/dotnet/core/sdk:3.1-alpine works for me.

[JerryMWeeks]

podman pull mcr.microsoft.com/dotnet/core/sdk:3.1-alpine works for me.

on second try it worked for me too (seems like there is some bug that causes the path to fail if the container exists and a new build session is started)

STEP 1/2: FROM mcr.microsoft.com/dotnet/core/sdk:3.1-alpine
STEP 2/2: COPY --from=code-packages /root/.nuget/packages/. /root/.nuget/packages/
Error: error building at STEP "COPY --from=code-packages /root/.nuget/packages/. /root/.nuget/packages/": checking on sources under "/home/user/.local/share/containers/storage/overlay/e5f635e2f5a082f7843c8aed1e22d46b7e455f03dd7ac8fc423323587fb7e7b8/merged": copier: stat: "/root/.nuget/packages": no such file or directory

But if I run
podman rmi -a -f
Then the same build code again it doesn't fail (might be my existing PowerShell and associated Docker file that causes this).

STEP 1/2: FROM mcr.microsoft.com/dotnet/core/sdk:3.1-alpine
Trying to pull mcr.microsoft.com/dotnet/core/sdk:3.1-alpine...
Getting image source signatures
Copying blob sha256:ce4ae16774dd8ab6421eba54346e8b5a6b99160e4cad223827f3399847027273

...

Copying config sha256:9d962797964f190ae11b12b51650870ea04ebacb893c40b968963292486769ab
Writing manifest to image destination
Storing signatures
STEP 2/2: COPY /Dockerfile.init /
COMMIT code-packages

[JerryMWeeks]

Perhaps another?
When the build progresses
In PowerShell we run something like this:
podman build -t code-base . --file .tools/docker-build/DockerInit/Dockerfile.base
Dockerfile.base starts with

FROM scratch
COPY .tools/code-analysis /.tools/code-analysis

The output produces this error (which seem to stem from pkg/bindings/images/build.go

STEP 1/70: FROM scratch
STEP 2/70: COPY .tools/code-analysis /.tools/code-analysis
]: syntax error in patternsEP "COPY .tools/code-analysis /.tools/code-analysis": error processing excludes list [**/bin/**/* 

The folder code-analysis contains a couple of simple enough files:

eg:

[rgov]

It would be best, to keep this discussion focused and informative to future readers, to file your issues as separate support requests in the Discussions tab or on StackOverflow, etc. and post here if indeed it turns out to be an incompatibility with Docker, summarizing the nature of that incompatibility that you discover.

When you post those other discussions, please follow bug reporting best practices and include data like the version of Podman you are using, and the operating system version. Since you are asserting that Podman does not work but Docker does, you should also include the version of Docker and the docker command that you tested with.

In this case it looks like you have maybe a .dockerignore file that Podman can't read? Is it malformed? What does it contain?

[mheon]

You'd probably be best off writing a fresh Github issue for specific problems (though I concur that this specific issue probably a .dockerignore or .containerignore that does not parse)

[rgov]

The Podman 4.3.0 release addresses some more incompatibilities with Docker. It still seems to me that when such incompatibilities are known, it would be useful to collect them in some reference file for users.

https://podman.io/releases/2022/10/22/podman-release-v4.3.0.html

[hlovdal]

The link https://podman.io/releases/2022/10/22/podman-release-v4.3.0.html is now a dead link. Please fix (a redirect to a new location is acceptable) and make sure such things does not happen in the future.

[afbjorklund]

• Release Announcements? podman.io#117

Hopefully it will get fixed eventually, along with the old blog posts?

• Old blog article link is broken podman.io#125

Content: https://github.com/containers/podman.io_old/blob/main/old/_posts/2022-10-22-podman-release-v4.3.0.md

[rgov]

Incompatibility: podman doesn't support COPY --link #20436