You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**TL;DR**: DDEV now supports Podman and Docker Rootless in [DDEV HEAD](https://docs.ddev.com/en/stable/developers/building-contributing/#testing-latest-commits-on-head) (coming in v1.25.0). Podman and Docker Rootless are a bit more trouble than the [recommended normal traditional docker providers](https://docs.ddev.com/en/stable/users/install/docker-installation/) and have some serious trade-offs. On macOS you can't use the normal default ports 80 and 443. On Linux Docker Rootless you can't bind-mount directories, so the entire project has to mutagen-synced.
15
+
**TL;DR**: DDEV supports Podman and Docker Rootless as of v1.25.0. Podman and Docker Rootless are a bit more trouble than the [recommended normal traditional Docker providers](https://docs.ddev.com/en/stable/users/install/docker-installation/) and have some serious trade-offs. On macOS you can't use the normal default ports 80 and 443. On Linux Docker Rootless you can't bind-mount directories, so the entire project has to be mutagen-synced.
16
16
17
17
Jump to setup instructions: [Linux/WSL2](#key-aim-linux-and-wsl2-users) · [macOS](#macos) · [Windows](#windows)
-[Switching Runtimes with DDEV](#switching-runtimes-with-ddev)
@@ -86,6 +89,19 @@ Unlike Podman which is rootless by default, Docker Rootless requires special set
86
89
87
90
The primary focus for this article is Linux and WSL2 (we have test coverage for Linux only for now). Most features and configurations are well-tested on these platforms.
88
91
92
+
### Do You Need an Alternative to Docker?
93
+
94
+
Before diving into setup, consider whether you need an alternative to traditional Docker:
95
+
96
+
| Runtime | Why would you do this? | Key trade-offs | Performance | Setup | Recommendation |
|**Traditional Docker**| Standard, widely-used option | None | Excellent | Simple |**Recommended for most users**|
99
+
|**Docker Rootless**| Security requirement for rootless daemon | Must use `--no-bind-mounts` (everything via Mutagen), can't use default workflow | Moderate (Mutagen overhead) | Moderate | Only if rootless security is required |
100
+
|**Podman Rootful**| Organization forbids Docker | Slower than Docker, different behavior | Slower than Docker | Moderate | Only if Docker not allowed |
101
+
|**Podman Rootless**| Organization forbids Docker + want rootless security | May need sysctl changes for ports <1024, slower than Docker | Slower than Docker | Moderate | Only if Docker not allowed and rootless required |
102
+
103
+
**Bottom line**: Stick with traditional Docker unless organizational policy or security requirements force you to use an alternative. The alternatives work, but have significant trade-offs.
104
+
89
105
### Installing Podman
90
106
91
107
Install Podman using your distribution's package manager. See the [official Podman installation guide for Linux](https://podman.io/docs/installation#installing-on-linux).
@@ -120,7 +136,7 @@ Podman provides a Docker-compatible API, which means you can use the Docker CLI
120
136
121
137
This is the recommended configuration for most users.
122
138
123
-
1. Prepare the system:
139
+
1. Prepare the system by configuring subuid and subgid ranges and enabling userns options, see the [Arch Linux Wiki](https://wiki.archlinux.org/title/Podman#Rootless_Podman) for details:
124
140
125
141
```bash
126
142
# Add subuid and subgid ranges if they don't exist for the current user
@@ -151,9 +167,7 @@ This is the recommended configuration for most users.
151
167
fi
152
168
```
153
169
154
-
For more details, see the [Arch Linux Wiki](https://wiki.archlinux.org/title/Podman).
155
-
156
-
2. Enable the Podman socket and verify it's running:
170
+
2. Enable the Podman socket and verify it's running ([Podman socket activation documentation](https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md)):
157
171
158
172
```bash
159
173
systemctl --user enable --now podman.socket
@@ -165,9 +179,7 @@ This is the recommended configuration for most users.
165
179
podman info --format '{{.Host.RemoteSocket.Path}}'
166
180
```
167
181
168
-
For more details, see the [Podman socket activation documentation](https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md).
169
-
170
-
3. Configure Docker API to use Podman:
182
+
3. Configure Docker API to use Podman ([Podman rootless tutorial](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)):
171
183
172
184
```bash
173
185
# View existing contexts
@@ -185,8 +197,6 @@ This is the recommended configuration for most users.
185
197
docker ps
186
198
```
187
199
188
-
For more details, see [Podman rootless tutorial](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
189
-
190
200
4. Proceed with [DDEV installation](https://docs.ddev.com/en/stable/users/install/ddev-installation/#ddev-installation-linux).
191
201
192
202
### Podman Rootless Performance Optimization
@@ -335,6 +345,15 @@ Docker Rootless on Linux offers rootless security with full Docker compatibility
335
345
336
346
macOS users can use Podman and Podman Desktop, but setup has its own challenges. Docker Rootless is not available on macOS.
337
347
348
+
### Do You Need an Alternative to Docker?
349
+
350
+
| Runtime | Why would you do this? | Key trade-offs | Performance | Setup | Recommendation |
| **Traditional Docker** | Standard, widely-used option | None | Excellent | Simple | **Recommended for most users** |
353
+
| **Podman** | Avoid Docker entirely (organizational policy) | Cannot use ports 80/443 (must use 8080/8443 instead), different behavior | Slower than Docker | Moderate | Only if Docker not allowed |
354
+
355
+
**Bottom line**: Use traditional Docker (OrbStack, Docker Desktop, Lima, Colima, or Rancher Desktop) unless your organization forbids it. The inability to use standard ports 80/443 with Podman creates a significantly different development experience.
356
+
338
357
### Installing Podman
339
358
340
359
Install Podman using Homebrew:
@@ -361,52 +380,51 @@ brew install docker
361
380
362
381
### Configuring Podman
363
382
364
-
1. Initialize and start the Podman machine:
383
+
1. Handle privileged ports (<1024):
384
+
385
+
**Important**: Podman on macOS cannot bind to privileged ports (80/443). You must configure DDEV to use unprivileged ports:
365
386
366
387
```bash
367
-
# check `podman machine init -h` for more options
368
-
podman machine init --memory 8192
369
-
podman machine start
388
+
ddev config global --router-http-port=8080 \
389
+
--router-https-port=8443
370
390
```
371
391
372
-
Example output from `podman machine start`:
373
-
374
-
```text
375
-
~ % podman machine start
376
-
Starting machine "podman-machine-default"
377
-
378
-
This machine is currently configured in rootless mode. If your containers
379
-
require root permissions (e.g. ports < 1024), or if you run into compatibility
380
-
issues with non-podman clients, you can switch using the following command:
392
+
This means your DDEV projects will be accessible at `https://yourproject.ddev.site:8443` instead of the standard `https://yourproject.ddev.site`.
381
393
382
-
podman machine set --rootful
383
-
384
-
API forwarding listening on: /var/folders/x3/r1wk89cd3_x0yb_21dgnj53m0000gn/T/podman/podman-machine-default-api.sock
385
-
386
-
The system helper service is not installed; the default Docker API socket
387
-
address can't be used by podman. If you would like to install it, run the following commands:
394
+
Note: switching to rootful mode with `podman machine set --rootful --user-mode-networking=false` doesn't help with privileged ports because the `--user-mode-networking=false` flag is [not supported on macOS](https://github.com/containers/podman/issues/26780) (it's only available for WSL).
3. Proceed with [DDEV installation](https://docs.ddev.com/en/stable/users/install/ddev-installation/).
434
-
435
-
4. Handle privileged ports (<1024):
451
+
4. Proceed with [DDEV installation](https://docs.ddev.com/en/stable/users/install/ddev-installation/).
436
452
437
-
Podman on macOS cannot bind to privileged ports (80/443). Configure DDEV to use unprivileged ports:
453
+
## Windows
438
454
439
-
```bash
440
-
ddev config global --router-http-port=8080 \
441
-
--router-https-port=8443
442
-
```
455
+
Windows users can use Podman Desktop, but setup has its own challenges. Docker Rootless is not available on traditional Windows (it works in WSL2, see the [Linux and WSL2](#key-aim-linux-and-wsl2-users) section).
443
456
444
-
Note: switching to rootful mode with `podman machine set --rootful --user-mode-networking=false` doesn't help with privileged ports because the `--user-mode-networking=false` flag is [not supported on macOS](https://github.com/containers/podman/issues/26780) (it's only available for WSL).
457
+
### Do You Need an Alternative to Docker?
445
458
446
-
## Windows
459
+
| Runtime | Why would you do this? | Key trade-offs | Performance | Setup | Recommendation |
| **Traditional Docker** | Standard, widely-used option | None | Excellent | Simple | **Recommended for most users** |
462
+
| **Podman** | Avoid Docker entirely (organizational policy) | Different behavior, less mature on Windows | Slower than Docker | Moderate | Only if Docker not allowed |
447
463
448
-
Windows users can use Podman Desktop, but setup has its own challenges. Docker Rootless is not available on traditional Windows (it works in WSL2, see the [Linux and WSL2](#key-aim-linux-and-wsl2-users) section).
464
+
**Bottom line**: Use traditional Docker (Docker Desktop or alternatives) unless your organization forbids it. Podman on Windows works but is less mature than on Linux.
0 commit comments