blog: Podman and Docker Rootless in DDEV, fixes #453 #476

stasadev · 2025-11-22T17:06:59Z

The Issue

Blog: Podman Support for DDEV #453

How This PR Solves The Issue

Adds a blog.

I haven't tested any configuration with Podman Desktop yet, so I don't know if additional configuration is needed there.

Manual Testing Instructions

https://pr-476.ddev-com-fork-previews.pages.dev/blog/podman-and-docker-rootless/

Automated Testing Overview

Release/Deployment Notes

github-actions · 2025-11-22T17:08:36Z

🌐 Fork Preview for PR #476

https://pr-476.ddev-com-fork-previews.pages.dev

This preview updates automatically when you push changes to your fork.

rfay · 2025-11-23T15:02:30Z

Just starting on this... Since this will come out before v1.25.0, it should mention the v1.25.0 or HEAD requirement to test, right?

rfay

Here's my first visit. Congrats on this milestone.

As mentioned, this should probably discourage people from using these options unless they know they need them. Early on it should have a link to normal setup and say "You don't need this unless you think you want it :) "

Now I'll experiment with the various options.

rfay · 2025-11-23T15:03:40Z

src/content/blog/podman-and-docker-rootless.md

+- **Removed legacy docker-compose features** ([#7642](https://github.com/ddev/ddev/pull/7642)): Podman refuses to work with deprecated `links` and `external_links` directives in `docker-compose` files. We removed these legacy features and modernized DDEV's compose file generation.
+- **Added Podman and Docker Rootless support** ([#7702](https://github.com/ddev/ddev/pull/7702)): DDEV now detects and supports Podman (rootful and rootless) and Docker Rootless. We added handling for Podman-specific limitations and enabled rootless environments to work without root privileges.
+
+These changes enabled Podman and Docker Rootless support.


An amazing journey, congratulations!

Maybe add a small statement about why these two features go hand-in-hand, why they developed together.

rfay · 2025-11-23T15:05:21Z

src/content/blog/podman-and-docker-rootless.md

+- Container processes cannot access root-owned files
+- Reduced attack surface if a container is compromised
+
+Podman is rootless by default. Docker Rootless requires special setup.


It is probably worth explaining here that DDEV's traditional support has had its containers run as an unprivileged user, limiting the attack space. DDEV's built-in containers do not use root privileges (although docker itself does need root by default)

src/content/blog/podman-and-docker-rootless.md

rfay · 2025-11-23T15:10:14Z

src/content/blog/podman-and-docker-rootless.md

+
+After installing Podman, enable the API socket so DDEV can connect.
+
+### Podman Rootless on Linux


Should this say "Linux and WSL2" ?

rfay · 2025-11-23T15:27:47Z

src/content/blog/podman-and-docker-rootless.md

+
+## Setting Up Docker Rootless with DDEV
+
+Docker Rootless offers rootless security with full Docker compatibility.


This is linux-only right? Should mention that.

src/content/blog/podman-and-docker-rootless.md

rfay · 2025-11-23T15:29:41Z

src/content/blog/podman-and-docker-rootless.md

+   - [Mounting a volume with rootless always assigns ownership to root](https://github.com/moby/moby/issues/45919)
+   - [Add ability to mount volume as user other than root](https://github.com/moby/moby/issues/2259)
+
+   The `root` user inside the container maps to your host user, but many services will not run as root:


It's interesting that this is the same classic problem we've had with Docker Desktop for Linux and for a time with virtiofs.

src/content/blog/podman-and-docker-rootless.md

rfay · 2025-11-23T15:32:28Z

src/content/blog/podman-and-docker-rootless.md

+   ddev start
+   ```
+
+## Which Runtime Should You Choose?


Great section. However, it should encourage standard Docker setup first, with link to the docs, as it's by far the best for local development.

rfay

Another comment: One reason people have often requested podman is the belief that it was the only open-source alternative to Docker Desktop. We should clear that up in here, pointing out the there are several other fully open source alternatives on every platform.

rfay · 2025-11-25T14:55:49Z

This and docs probably need a compatibility table showing all the options and what works etc.

src/content/blog/podman-and-docker-rootless.md

rfay · 2025-11-25T18:54:57Z

src/content/blog/podman-and-docker-rootless.md

+
+### Podman Installation Options
+
+Podman can be installed with or without a GUI:


I think we probably need a little more than this. I missed both podman init and podman start. Maybe one of those collapsed sections with basic instructions on macOS and Linux? The majority of our users are macOS, but probably the majority of interested users are on Linux.

I'll check the formatting options for Markdown here.

rfay · 2025-11-26T03:00:24Z

I'm not sure if you already have this in there, but the inability to bind to default ports 80/443 is a pretty significant liability for a web developer.

tyler36 · 2025-11-26T03:23:28Z

Just tried installing rootless podman in a isolated WSL Ubuntu environment:

I got a warning "Problem with your Docker provider: installed Podman version 4.9.3 is not supported, please update to version 5.0 or newer."

But it seem Ubuntu old has older versions available(?)

$ sudo nala search podman
...
podman 4.9.3+ds1-1ubuntu0.2 [Ubuntu/noble universe]
└── tool to manage containers and pods

Install Podman Desktop on windows got a "current" version though:

❯ podman -v
podman version 5.7.0

stasadev · 2025-12-09T19:09:10Z

Summary of Changes from Original Version

Added release status clarity: now explicitly states support is in DDEV HEAD with GA planned for v1.25.0.
Added full platform separation: Linux/WSL2, macOS, and Windows now have dedicated sections.
Added Open Source alternatives to Docker Desktop (Rancher, Lima, Colima, etc).
Improved rootless security explanation by distinguishing container user vs daemon privileges.
Moved subuid/subgid setup into the main Podman Rootless configuration flow (more correct).
Added Docker Rootless loopback/Xdebug fix using RootlessKit environment override.
Added a full runtime comparison table with features and recommendations.

Content that was shortened or removed

Removed the full UID/GID failure error log example and explicit recovery command (podman system migrate).
Removed the explicit privileged ports error message text (rootlessport cannot expose privileged port 80).
Removed the Arch Linux-specific pacman example for fuse-overlayfs.

Overall Impact

Documentation is now broader, more accurate, and more structured.
One-off deep Linux troubleshooting examples were reduced, but no core setup steps were lost.

stasadev · 2025-12-09T19:11:52Z

src/content/blog/podman-and-docker-rootless.md

+## macOS
+
+macOS users can use Podman and Podman Desktop, but setup has its own challenges. Docker Rootless is not available on macOS.
+
+### Installing Podman
+
+Install Podman using Homebrew:
+
+```bash
+brew install podman
+```
+
+Or install [Podman Desktop](https://podman-desktop.io/docs/installation/macos-install) if you prefer a GUI.
+
+For more information, see the [official Podman installation guide for macOS](https://podman.io/docs/installation#macos) and [Podman tutorials](https://github.com/containers/podman/tree/main/docs/tutorials#readme).
+
+### Installing Docker CLI
+
+```bash
+brew install docker
+```
+
+### Configuring Podman
+
+After installing Podman, initialize and start the Podman machine:
+
+```bash
+podman machine init
+podman machine start
+```
+
+The Podman machine will automatically configure the socket. Verify it's running:
+
+```bash
+podman info --format '{{.Host.RemoteSocket.Path}}'
+```
+
+If you have Docker CLI installed, you can create a context for Podman:
+
+```bash
+# Create Podman context
+docker context create podman-rootless \
+    --description "Podman (rootless)" \
+    --docker host="unix://$(podman info --format '{{.Host.RemoteSocket.Path}}')"
+
+# Switch to the new context
+docker context use podman-rootless
+
+# Verify it works
+docker ps
+```
+
+Otherwise, set the `DOCKER_HOST` environment variable in your shell profile (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+export DOCKER_HOST=unix://$(podman info --format '{{.Host.RemoteSocket.Path}}')
+```


I didn't test macOS, hoping for possible improvements or tips from @rfay in this section.

Co-authored-by: Randy Fay <[email protected]>

rfay

I think this should either be targeted at the v1.25.0 release, or alternately promote it earlier and try to get some people to use HEAD.

It's looking good, I added some more suggestions.

Now I'll try some more manual testing.

rfay · 2025-12-10T17:40:42Z

src/content/blog/podman-and-docker-rootless.md

+
+The DDEV community has requested Podman and Docker Rootless support for years. This support is now available in [DDEV HEAD](https://docs.ddev.com/en/stable/developers/building-contributing/#testing-latest-commits-on-head) as an experimental feature, general availability is planned for upcoming DDEV v1.25.0.
+
+It allows DDEV to work in corporate environments where Docker Desktop is not allowed due to security policies or licensing restrictions.


Suggested change

It allows DDEV to work in corporate environments where Docker Desktop is not allowed due to security policies or licensing restrictions.

It allows DDEV to work in corporate environments where Podman or Rootless Docker are preferred due to security policies or licensing restrictions.

rfay · 2025-12-10T17:41:52Z

src/content/blog/podman-and-docker-rootless.md

+  - Guides
+---
+
+The DDEV community has requested Podman and Docker Rootless support for years. This support is now available in [DDEV HEAD](https://docs.ddev.com/en/stable/developers/building-contributing/#testing-latest-commits-on-head) as an experimental feature, general availability is planned for upcoming DDEV v1.25.0.


Add a TL;DR with simple statement/link about how to get going.

rfay · 2025-12-10T17:42:43Z

src/content/blog/podman-and-docker-rootless.md

+- [Supporting DDEV Development](#supporting-ddevdevelopment)
+- [Conclusion](#conclusion)
+
+## The Journey to Podman Support


I think this is great and useful, but should probably move to the bottom. It's too much for most people to absorb, and not directly relevant to getting them going.

rfay · 2025-12-10T17:44:01Z

src/content/blog/podman-and-docker-rootless.md

+
+All of these work with DDEV. The main reason to choose Podman specifically is if your organization forbids Docker entirely or if you want rootless operation by default.
+
+### Why Choose Rootless?


Great section. Maybe "Why choose Podman" right after it. Or before it.

rfay · 2025-12-10T17:47:12Z

src/content/blog/podman-and-docker-rootless.md

+
+### Why Choose Rootless?
+
+Running containers without root privileges is more secure. Traditional Docker and rootful Podman need elevated privileges, which creates security risks in corporate environments where strict security policies apply.


Suggested change

Running containers without root privileges is more secure. Traditional Docker and rootful Podman need elevated privileges, which creates security risks in corporate environments where strict security policies apply.

Although DDEV's use of all Docker providers is quite secure, and we run containers as normal users with limited privileges, the rootless approaches to Docker and Podman actually run the *docker daemon* without root privileges, closing additional attack surface. Traditional Docker and rootful Podman daemons need elevated privileges, which creates security risks in corporate environments where strict security policies apply. (Note that DDEV is targeted at local development, where there are few risks of specialized attacks using this vector anyway.)

rfay · 2025-12-10T17:56:39Z

src/content/blog/podman-and-docker-rootless.md

+   docker ps
+   ```
+
+   **Option B: Set environment variable in your shell profile** (`~/.bashrc` or `~/.zshrc`):


I guess I'd prefer not to mention DOCKER_HOST, but open to conversation. I think docker contexts are better to use.

rfay · 2025-12-10T17:57:34Z

src/content/blog/podman-and-docker-rootless.md

+
+For additional details, see the [Podman socket activation documentation](https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md).
+
+### Configuring Podman Rootful


I think you had said earlier that podman is innately rootless, so this may need some clarification? Probably we don't even need to cover podman rootful if it has no value.

rfay · 2025-12-10T17:58:37Z

src/content/blog/podman-and-docker-rootless.md

+
+### Podman Rootless Performance Optimization
+
+Podman Rootless is slower than Docker. See these resources:


Suggested change

Podman Rootless is slower than Docker. See these resources:

Podman Rootless is significantly slower than Docker. See these resources:

rfay · 2025-12-10T19:13:07Z

src/content/blog/podman-and-docker-rootless.md

+
+### Recommendations
+
+**Use [standard Docker](https://docs.ddev.com/en/stable/users/install/docker-installation/) if:**


Suggested change

**Use [standard Docker](https://docs.ddev.com/en/stable/users/install/docker-installation/) if:**

**Use of the many [standard Docker providers](https://docs.ddev.com/en/stable/users/install/docker-installation/) if:**

rfay · 2025-12-10T19:13:56Z

src/content/blog/podman-and-docker-rootless.md

+
+- You're comfortable with the most widely used container runtime
+- You don't have rootless security requirements
+- This is the recommended option for most users


Suggested change

- This is the recommended option for most users

_This is the recommended option for the vast majority of users._

rfay

I got it working fine on macOS and will use it for a while for daily use.

I didn't succeed with Fedora 43. The /mnt/ddev_config was always mounted as root and couldn't be copied at startup time.

I imagine this was something I did wrong.

rfay · 2025-12-11T16:07:59Z

src/content/blog/podman-and-docker-rootless.md

+
+### Configuring Podman Rootless
+
+This is the recommended configuration for most users.


Is there even a reason to explain podman rootful?

rfay · 2025-12-11T16:09:04Z

src/content/blog/podman-and-docker-rootless.md

+
+This is the recommended configuration for most users.
+
+1. In order for users to run rootless Podman, a `subuid` and `subgid` configuration entry must exist for each user that wants to use it. New users created using `useradd` have these entries by default:


Can we make this a little smarter? Either check whether it exists already in the statement, or make it less obvious? Since it's the first step... everybody will do it, and end up with broken system like I did. I think username:1000:165535 is a great default, but if it has something more specific in there already... remove it? Respect it?

This was referenced Nov 22, 2025

feat: add Podman rootless/rootful and Docker rootless support, fixes #2276, fixes #2899 ddev/ddev#7702

Merged

Support podman as a docker alternative ddev/ddev#2276

Closed

Feature request: Support rootless docker ddev/ddev#2899

Closed

stasadev force-pushed the 20251122_stasadev_podman branch 2 times, most recently from 4eb31c6 to 5dc0225 Compare November 22, 2025 17:26

rfay reviewed Nov 23, 2025

View reviewed changes

rfay reviewed Nov 25, 2025

View reviewed changes

src/content/blog/podman-and-docker-rootless.md Show resolved Hide resolved

rfay reviewed Nov 25, 2025

View reviewed changes

stasadev force-pushed the 20251122_stasadev_podman branch 2 times, most recently from 4dd642a to ae5ec1b Compare December 9, 2025 19:05

stasadev requested a review from rfay December 9, 2025 19:09

stasadev marked this pull request as ready for review December 9, 2025 19:09

stasadev commented Dec 9, 2025

View reviewed changes

stasadev and others added 4 commits December 10, 2025 10:33

blog: Podman and Docker Rootless in DDEV

b192873

Apply suggestions from @rfay, thanks [skip ci]

372a3eb

Co-authored-by: Randy Fay <[email protected]>

Refine the article

1242f51

use unprivileged ports on macOS

ac6fe7e

rfay force-pushed the 20251122_stasadev_podman branch from bba5f65 to ac6fe7e Compare December 10, 2025 17:33

rfay requested changes Dec 10, 2025

View reviewed changes

rfay requested changes Dec 11, 2025

View reviewed changes

stasadev marked this pull request as draft December 11, 2025 19:02


		After installing Podman, enable the API socket so DDEV can connect.

		### Podman Rootless on Linux


		## Setting Up Docker Rootless with DDEV

		Docker Rootless offers rootless security with full Docker compatibility.


		### Podman Installation Options

		Podman can be installed with or without a GUI:


		The DDEV community has requested Podman and Docker Rootless support for years. This support is now available in [DDEV HEAD](https://docs.ddev.com/en/stable/developers/building-contributing/#testing-latest-commits-on-head) as an experimental feature, general availability is planned for upcoming DDEV v1.25.0.

		It allows DDEV to work in corporate environments where Docker Desktop is not allowed due to security policies or licensing restrictions.


		All of these work with DDEV. The main reason to choose Podman specifically is if your organization forbids Docker entirely or if you want rootless operation by default.

		### Why Choose Rootless?


		### Why Choose Rootless?

		Running containers without root privileges is more secure. Traditional Docker and rootful Podman need elevated privileges, which creates security risks in corporate environments where strict security policies apply.


		For additional details, see the [Podman socket activation documentation](https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md).

		### Configuring Podman Rootful


		### Podman Rootless Performance Optimization

		Podman Rootless is slower than Docker. See these resources:

	Podman Rootless is slower than Docker. See these resources:
	Podman Rootless is significantly slower than Docker. See these resources:


		### Recommendations

		Use [standard Docker](https://docs.ddev.com/en/stable/users/install/docker-installation/) if:

	Use [standard Docker](https://docs.ddev.com/en/stable/users/install/docker-installation/) if:
	Use of the many [standard Docker providers](https://docs.ddev.com/en/stable/users/install/docker-installation/) if:

	- This is the recommended option for most users

	_This is the recommended option for the vast majority of users._


		### Configuring Podman Rootless

		This is the recommended configuration for most users.


		This is the recommended configuration for most users.

		1. In order for users to run rootless Podman, a `subuid` and `subgid` configuration entry must exist for each user that wants to use it. New users created using `useradd` have these entries by default:

Uh oh!

blog: Podman and Docker Rootless in DDEV, fixes #453 #476

Are you sure you want to change the base?

blog: Podman and Docker Rootless in DDEV, fixes #453 #476

Uh oh!

Conversation

stasadev commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The Issue

How This PR Solves The Issue

Manual Testing Instructions

Automated Testing Overview

Related Issue Link(s)

Release/Deployment Notes

Uh oh!

github-actions bot commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rfay commented Nov 23, 2025

Uh oh!

rfay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rfay left a comment

Choose a reason for hiding this comment

Uh oh!

rfay commented Nov 25, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rfay commented Nov 26, 2025

Uh oh!

tyler36 commented Nov 26, 2025

Uh oh!

stasadev commented Dec 9, 2025

Summary of Changes from Original Version

Content that was shortened or removed

Overall Impact

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rfay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rfay Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

stasadev commented Nov 22, 2025 •

edited

Loading

github-actions bot commented Nov 22, 2025 •

edited

Loading

rfay Dec 10, 2025 •

edited

Loading