Docker php-fpm running as www-data

Docker php-fpm running as www-data

  1. Blog
  2. 15 November 2026
  3. 5 min read

Stefan Bogdanescu

Founder & Senior Architect

The Docker PHP-FPM User Mismatch Problem

When deploying a Laravel application in a Docker environment, specifically using the php:7.3-fpm image alongside Nginx, developers frequently encounter permission errors during runtime. This issue stems from a fundamental mismatch between the user running the web server process inside the container and the user owning the files on the host machine.

By default, the official PHP FPM Docker images are built with --with-fpm-user=www-data and --with-fpm-group=www-data. Inside the container, the application runs as this system user. However, when you map your local development directory (e.g., - ./code:/var/www) to the container, the files retain their original ownership from your host machine. If you are developing on Ubuntu or macOS, these files typically belong to your specific system user and group (for example, phil:phil).

When Laravel attempts to write error logs to the storage directory, it fails with a "permission denied" error. This happens because the PHP-FPM process running as www-data lacks write permissions on the directory owned by phil. While the standard solution for production is often to fix ownership inside the container or use Docker volumes that handle this automatically, local development requires a different approach due to IDE integration needs.

Why Changing Host Ownership Fails

A common first step is to recursively change the owner and group of your project directory on the host machine to match the container's user: www-data:www-data. While this resolves the runtime permission error, it introduces a significant workflow blocker. Your development environment relies on your IDE (such as PHPStorm) writing files directly to the source code. Since PHPStorm runs under your standard user account, it cannot write to directories owned by www-data without explicit group permissions or sudo privileges, which is cumbersome and often breaks version control hooks or file watcher plugins.

Another attempted workaround involves adding your host user (e.g., phil) to the www-data group on the host and granting write permissions via chmod -R g+w ./code. While this allows both the application and your IDE to function, it creates a stability issue. Every time you save a file in PHPStorm, the file ownership reverts to phil:phil. When the container restarts or if the directory is remapped, the strict permission model of the FPM process can break again.

The Correct Solution: Volume Mounting and Group Configuration

The most robust solution involves configuring your host directory permissions correctly from the start and ensuring the Docker volume mount respects these settings without requiring root access for every file change.

You should not change the ownership of your entire project folder to www-data. Instead, you need to ensure that the specific directories Laravel needs to write to (like storage and bootstrap/cache) have appropriate permissions for the current user while allowing the web server process to read and execute them.

However, in a Dockerized environment where you are mounting the host directory directly into the container as the primary volume, the cleanest approach is often to ensure your host directories are owned by a group that both your user and the www-data user can access, or to utilize the specific behavior of how Docker handles file ownership on mount points.

The recommended practice for development environments using official PHP images is to configure the host directory permissions so that the user inside the container (who is often mapped to UID 33 in Alpine-based PHP images) has read and execute access, while your host user owns the files. Laravel’s default configuration usually creates directories with 775 or 770 permissions, which should be sufficient if your host user and group IDs align or if the directory is owned by a super-user equivalent group.

If you are starting fresh, create your project structure with your current user:

mkdir -p code/storage code/bootstrap/cache
chown -R $(whoami):$(whoami) code
chmod -R 775 code/storage code/bootstrap/cache

Then, ensure your docker-compose.yml mounts the directory correctly. The key is that you do not need to change the ownership of the entire source tree to www-data. You only need to ensure writeable directories have permissions that allow the running process to access them. If your host user ID matches the UID of the www-data user in the container (which varies by base image, e.g., 33 for Alpine, or your local UID if you map it), you can simplify this further.

Why Custom Images Are Not Required

The frustration with trying to override --with-fpm-user=phil via environment variables is valid but often misunderstood. As noted in the Docker PHP library issues, build-time arguments like ARG are used during the image build process, while ENV variables set at runtime do not alter the pre-configured FPM user settings defined in the base image's entrypoint. Attempting to change this via a simple custom image without rebuilding the entire OS layer or using complex entrypoint scripts is unnecessary overhead.

The maintainers of the official PHP images use www-data because it is a standard Linux group name that exists on most servers. By adjusting permissions on your host machine to allow cross-user access or ensuring the specific directories Laravel touches are writable by the current user, you avoid the need for complex custom base images or running IDEs as non-standard system users.

For local development, the goal is to keep the file ownership with your human-readable username for IDE compatibility while granting the containerized process sufficient permissions through standard Unix groups and directory modes, rather than forcing a global ownership change that breaks your workflow.

Our network