Debugging Docker Permission Issues: My Journey Through Container User Management
The Challenge Begins
While working on a data science containerization homework assignment, I encountered a series of permission-related challenges that taught me valuable lessons about Docker's user management and file ownership mechanisms. What started as a straightforward homework assignment to create a Docker container for data science projects turned into a deep dive into Linux permissions, Docker's layering system, and the intricacies of running containers with non-root users.
First Encounter: The Permission Denied Error
My initial Dockerfile seemed reasonable enough. I had installed the uv package manager as root, created a non-root user named 'app', and then attempted to run uv sync as that user. The build process came to an abrupt halt with this error:
$ docker build -t hw1-data-science .
...
> [7/8] RUN /root/.cargo/bin/uv sync:
0.363 /bin/sh: 1: /root/.cargo/bin/uv: Permission denied
ERROR: failed to build: process "/bin/sh -c /root/.cargo/bin/uv sync" did not complete successfully: exit code: 126
Investigation Process
To understand what was happening, I needed to trace through the Docker build process step by step. The error message revealed that the 'app' user couldn't execute a binary located in root's home directory. This made perfect sense from a Linux security perspective - normal users shouldn't have access to root's personal files.
My first debugging step was to verify where the uv installer was actually placing the binary:
$ docker run --rm -it python:3.11-slim-bookworm bash -c "curl -LsSf https://astral.sh/uv/install.sh | sh && ls -la /root/.cargo/bin/"
This exploratory command showed me that the installer was indeed placing uv in /root/.cargo/bin/, which explained why my non-root user couldn't access it.
Second Discovery: Installation Path Changes
When I attempted to fix the issue by moving the binary to a system-wide location, I encountered another surprise:
$ docker build -t hw1-data-science .
...
installing to /root/.local/bin
uv
uvx
everything's installed!
mv: cannot stat '/root/.cargo/bin/uv': No such file or directory
The installer had changed its behavior! It was now installing to /root/.local/bin instead of /root/.cargo/bin. This discovery taught me an important lesson: external tools can change their installation paths between versions, and I need to verify assumptions rather than hardcoding paths.
Adapting to the Change
I modified my Dockerfile to use the correct path:
RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
mv /root/.local/bin/uv /usr/local/bin/uv && \
chmod 755 /usr/local/bin/uv
This approach moved the binary to /usr/local/bin/, a standard location for system-wide executables that all users can access.
Third Challenge: Directory Ownership
With the uv binary now accessible, I thought my problems were solved. But Docker had another lesson for me:
$ docker build -t hw1-data-science .
...
> [7/8] RUN uv sync:
0.576 Creating virtual environment at: .venv
0.576 error: failed to create directory `/app/.venv`: Permission denied (os error 13)
Understanding Docker's Directory Creation
This error revealed a subtle but critical aspect of how Docker handles directory ownership. When I set WORKDIR /app in my Dockerfile, Docker automatically created that directory - but it created it as root, since I hadn't switched users yet. Even though I later switched to the 'app' user, that user didn't own the directory it was trying to write to.
To investigate this, I created a test container to examine the directory permissions:
$ docker run --rm -it python:3.11-slim-bookworm bash -c "mkdir /app && ls -ld /app"
drwxr-xr-x 2 root root 4096 Sep 24 07:00 /app
This confirmed my suspicion - directories created by Docker's WORKDIR instruction are owned by root by default.
The Solution
The fix required explicitly creating the directory and setting its ownership before switching users:
# Create the working directory and set ownership to app user
RUN mkdir -p /app && chown -R app:app /app
# Set the working directory
WORKDIR /app
# Switch to the app user for all subsequent operations
USER app
This sequence ensures that when the 'app' user tries to create the virtual environment, it's writing to a directory it owns.
Verification and Success
After implementing these fixes, I verified the complete build:
$ docker build -t hw1-data-science .
...
=> [8/9] RUN uv sync 5.5s
=> [9/9] COPY --chown=app:app regression.py test.py ./ 0.1s
=> exporting to image 12.5s
=> naming to docker.io/library/hw1-data-science:latest 0.0s
Success! The container built without errors. To verify everything was working correctly, I tested the container interactively:
$ docker run -it --rm hw1-data-science
app@89e36d060d44:/app$ which python
/app/.venv/bin/python
app@89e36d060d44:/app$ python test.py
# Silent success - tests passed
app@89e36d060d44:/app$ python regression.py
Linear Regression Predictions for Diabetes Dataset:
==================================================
Number of test samples: 89
First 10 predictions: [139.54, 179.51, 134.03, ...]
Key Lessons Learned
Through this debugging journey, I gained deep insights into Docker's permission model:
User Context Matters: Commands in a Dockerfile execute in the context of the current user. When I install something as root, only root can access it unless I explicitly make it available to others.
Directory Ownership Is Set at Creation: Docker creates directories at the moment they're first referenced, using the permissions of the current user at that time. This timing is crucial when working with non-root users.
Verification Over Assumption: External tools can change their behavior. Rather than assuming installation paths, I learned to verify and adapt.
Systematic Debugging: Each error message provided clues about the underlying issue. By investigating systematically rather than making random changes, I could identify and fix the root causes.
The Value of Minimal Fixes
Throughout this process, I resisted the temptation to take shortcuts like running everything as root. Instead, I made minimal, targeted fixes that maintained security best practices while solving the immediate problems. This approach resulted in a Dockerfile that not only works but also demonstrates proper containerization patterns.
Reflection
This experience reinforced my belief that debugging is as much about understanding systems as it is about fixing problems. Each permission error taught me something new about how Docker layers work, how Linux manages file ownership, and how different components of a containerized application interact.
The most satisfying moment wasn't just when the build succeeded, but when I understood why it succeeded. That understanding means I can now anticipate and prevent similar issues in future projects, and I can help others navigate these same challenges.
CLI Commands Reference
Here's a compilation of the debugging commands I found most useful during this journey:
Investigation Commands
# Check current directory contents with permissions
ls -la
# View Docker build output with detailed error messages
docker build -t image-name .
# Test commands in a temporary container
docker run --rm -it base-image bash -c "command"
# Examine file permissions inside a container
docker run --rm image-name ls -ld /path
# Check which user owns a process
docker run --rm image-name whoami
# Verify binary locations
which command-name
# Check if files match between directories
diff -q file1 file2
Diagnostic Commands
# List Docker images
docker images | grep image-name
# View file with line numbers for debugging
cat -n filename
# Search for specific patterns in files
grep -n "pattern" filename
# Compare file contents
diff -u file1 file2
# Check archive contents without extracting
unzip -l archive.zip
# View first N lines of a file
head -n 20 filename
Verification Commands
# Run container interactively
docker run -it --rm image-name
# Test Python environment
python -c "import sys; print(sys.version)"
# Verify package installation
python -c "import package_name"
# Check virtual environment activation
which python
# Silent test execution (Unix philosophy)
python test.py
These commands became my toolkit for understanding and resolving containerization issues. Each serves a specific purpose in the debugging workflow, from initial investigation through to final verification.
If you enjoyed this article, you can also find it published on LinkedIn and Medium.