How to Fix DDEV and Rootless Docker Error on Ubuntu 24.04

Setting up a local development environment can sometimes present unexpected challenges. This article details a troubleshooting process for a user encountering issues with DDEV and a rootless Docker installation on Ubuntu 24.04.2 LTS. The user, attempting to create a Drupal 11 project using ddev composer create drupal/recommended-project:^11, encountered a series of permission errors originating from within the Docker container. These errors, primarily related to rsync failing due to "Operation not permitted" and "Permission denied," highlight a crucial incompatibility between DDEV and rootless Docker deployments.

The core issue stems from a fundamental conflict: DDEV, a popular tool for managing local development environments, is not compatible with Docker running in rootless mode. While running Docker without root privileges offers enhanced security, it introduces limitations that prevent DDEV from functioning correctly. The permission errors during the rsync operation, a critical step in transferring project files into the Docker container, directly reflect this incompatibility. The rsync command attempts to modify file permissions and ownership within the container’s /var/www/html directory, actions that are restricted when Docker operates in a rootless context.

Let's analyze the error messages:

rsync: [generator] chgrp "/var/www/html/." failed: Operation not permitted (1)
rsync: [receiver] mkstemp "/var/www/html/.composer.json.W5zjkY" failed: Permission denied (13)
rsync: [receiver] mkstemp "/var/www/html/.composer.lock.9V8HJC" failed: Permission denied (13)
rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1338) [sender=3.2.7]
    

These lines clearly indicate that the rsync process, responsible for transferring the newly created Drupal project from a temporary location (/tmp/GvzJue) to the designated directory within the Docker container (/var/www/html), is blocked by permission restrictions. The container’s user lacks the necessary privileges to perform these file system operations. The error codes (1 and 13) correspond to "Operation not permitted" and "Permission denied," respectively, reinforcing the permission-related nature of the problem.

The underlying cause is the rootless Docker installation. The standard DDEV workflow relies on Docker operating with root privileges to manage containers, access files, and handle permissions effectively. When running in rootless mode, Docker utilizes a different security model that restricts access to system resources, leading to the observed permission failures.

Therefore, resolving this issue requires addressing the rootless Docker configuration. The solution involves two key steps: first, uninstalling the rootless Docker installation; and second, installing the standard Docker CE version that operates with root privileges.

Uninstalling Rootless Docker: The exact commands for uninstalling rootless Docker will depend on how it was originally installed. However, a common approach involves removing the docker and associated packages through the system's package manager (apt):

      sudo apt remove docker-ce docker-ce-cli containerd.io docker-compose-plugin
    

This command removes the Docker packages. It is crucial to carefully review the packages listed to avoid inadvertently removing other important system components. Always verify the packages before proceeding with the removal.

Installing Standard Docker CE: After successfully removing the rootless Docker installation, install the standard Docker CE version. This usually involves adding the Docker repository, updating the package list, and then installing the docker-ce package:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
   

This will install the required Docker components. Post-installation, verify Docker’s functionality by running:

      sudo docker run hello-world
    

A successful execution will print a message confirming the installation and basic functionality. It's essential to run this command with sudo because the standard Docker installation requires root privileges.

After a successful installation and verification of the standard Docker CE installation, the next step involves checking the Docker context. A lingering "rootless" context, even after uninstalling rootless Docker, could still cause conflicts. Use the following command to list available Docker contexts:

      docker context ls
    

If a "rootless" context persists, remove it:

      docker context rm rootless
    

Now, set the default context to the appropriate Docker environment, usually default. The command to do this varies depending on your Docker setup, but it would typically involve switching to the default context if it exists, or creating one if needed. Consult the Docker documentation for your specific configuration.

Finally, restart your system to ensure all changes take effect. After rebooting, retry the DDEV command:

      ddev composer create drupal/recommended-project:^11
    

This should now execute without any permission errors, as DDEV will interact with Docker using the standard, root-privileged installation. The rsync operation will succeed in transferring the Drupal project files into the Docker container, enabling the successful creation of your local Drupal development environment.

Careful attention to the Docker installation and context management is key to resolving compatibility issues between DDEV and Docker. This detailed walkthrough ensures a smooth, error-free development setup. Always remember to consult the official documentation for both DDEV and Docker for the most up-to-date information and instructions specific to your system configuration.