Skip to content

Update the container documentation for better Podman support #7978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Update the container documentation for better Podman support #7978

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
459cc8f
Update docker-options.md with my Podman fixes
samuel-garmany Jan 30, 2025
3362f18
Update docker-options.md Fixed indentation
samuel-garmany Jan 30, 2025
33beda6
Clarify which file needs to be configured for podman-docker format
samuel-garmany Feb 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions remote/advancedcontainers/docker-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,18 +95,26 @@ You can learn more about using Remote - SSH with Dev Containers in the [develop

However, certain tricks like [Docker-from-Docker do not work](https://github.com/containers/libpod/issues/4056#issuecomment-535511841) due to limitations in Podman. This affects the **Dev Containers: Try a Dev Container Sample...** and [Dev Containers: Clone Repository in Container Volume...](/docs/devcontainers/containers.md#quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume) commands.

To work around issues with rootless Podman (for example, not respecting a non-root `"remoteUser"` and trying to install the server in `root`), you can set the following:
To work around issues where Podman lacks permissions to create a directory in the new devcontainer, you can set Podman to build images with the Docker format, disable labling containers with SELinux, and maintain the user's UID and GID

In `~/.config/containers/containers.conf`:

```toml
[containers]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this located? If it's user configuration this would affect all Podman containers I guess?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yes, this configuration file should be located at ~/.config/containers/containers.conf. It will affect all containers build by podman. I haven't noticed a difference outside of devcontainers working but it is something that could be noted by the docs.

This comment was marked as off-topic.

Sign in to view

This comment was marked as off-topic.

Sign in to view

This comment was marked as off-topic.

Sign in to view

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alviz22 Thats not how containers.conf works, you can’t just delete that line.

env = [
"BUILDAH_FORMAT=docker"
]
label = false
userns = "keep-id"
```

After that you will need to restart Podman add the following to your `devcontainer.json` to prevent Podman from attempting to create directories in `root`

```json
"runArgs": [
"--userns=keep-id"
],
"containerEnv": {
"HOME": "/home/node"
}
"containerUser": "vscode"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Setting HOME is an alternative to this. Not sure what's best, but keeping the container user as root allows entrypoints to run as root which is sometimes needed.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my experience setting HOME did not fix this issue and I still had build problems where permission to create directories was denied. I understand the concern that you can't set the container user to root but the alternative for me was that I couldn't connect to the container at all. This may be an artifact of an immutable OS though so if someone else has experience that would probably be helpful.

```

`"remoteUser"` can be used when `"HOME"` is set because Dev Containers gives that setting precedence over the home folder it finds in `/etc/passwd`.
Podman also has its own implementation of the Compose Spec with [Podman Compose](https://github.com/containers/podman-compose).

Podman also has its own implementation of the Compose Spec with [Podman Compose](https://github.com/containers/podman-compose).

Expand Down