0
0
Dockerdevops~5 mins

Running containers as non-root in Docker - Commands & Configuration

Choose your learning style9 modes available
LearnWhyDeepVisualTryChallengeProjectRecallTime
Introduction
Running containers as non-root means the software inside the container does not run with administrator rights. This improves security by limiting what the container can do if it is compromised.
When you want to reduce the risk of a container escaping and affecting the host system.
When running applications that do not need full administrator access inside the container.
When following security best practices for production environments.
When deploying containers in shared environments where multiple users run containers.
When compliance rules require least privilege access for running software.
Config File - Dockerfile
Dockerfile
FROM nginx:1.23.3-alpine

# Create a user and group with a specific ID
RUN addgroup -S appgroup && adduser -S -G appgroup appuser

# Change ownership of the nginx html directory
RUN chown -R appuser:appgroup /usr/share/nginx/html

# Switch to the non-root user
USER appuser

CMD ["nginx", "-g", "daemon off;"]

This Dockerfile starts from the official nginx image.

It creates a new user and group named appuser and appgroup without root privileges.

It changes ownership of the web content directory to this user so nginx can serve files.

Finally, it switches the container to run as appuser instead of root.

Commands
Builds the Docker image named nginx-nonroot using the Dockerfile in the current directory. This image runs nginx as a non-root user.
Terminal
docker build -t nginx-nonroot .
Expected OutputExpected
Sending build context to Docker daemon 2.56kB Step 1/7 : FROM nginx:1.23.3-alpine ---> 3f8a4339aadd Step 2/7 : RUN addgroup -S appgroup && adduser -S -G appgroup appuser ---> Running in 1a2b3c4d5e6f Removing intermediate container 1a2b3c4d5e6f ---> 7f8e9d0c1b2a Step 3/7 : RUN chown -R appuser:appgroup /usr/share/nginx/html ---> Running in 2b3c4d5e6f7g Removing intermediate container 2b3c4d5e6f7g ---> 8a9b0c1d2e3f Step 4/7 : USER appuser ---> Running in 3c4d5e6f7g8h Removing intermediate container 3c4d5e6f7g8h ---> 9b0c1d2e3f4g Step 5/7 : CMD ["nginx", "-g", "daemon off;"] ---> Running in 4d5e6f7g8h9i Removing intermediate container 4d5e6f7g8h9i ---> a0b1c2d3e4f5 Successfully built a0b1c2d3e4f5 Successfully tagged nginx-nonroot:latest
Runs the nginx-nonroot container in detached mode, mapping port 8080 on the host to port 80 in the container. This starts the nginx server as the non-root user.
Terminal
docker run -d -p 8080:80 --name my-nginx-nonroot nginx-nonroot
Expected OutputExpected
b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2
→
-d - Run container in background (detached mode)
→
-p 8080:80 - Map host port 8080 to container port 80
→
--name - Assign a name to the running container
Checks the user ID and group ID inside the running container to confirm it is running as the non-root user.
Terminal
docker exec my-nginx-nonroot id
Expected OutputExpected
uid=1000(appuser) gid=1000(appgroup) groups=1000(appgroup)
Fetches the default nginx welcome page from the container through the mapped port to verify the server is running correctly.
Terminal
curl http://localhost:8080
Expected OutputExpected
<!DOCTYPE html> <html> <head> <title>Welcome to nginx!</title> </head> <body> <h1>Welcome to nginx!</h1> <p>If you see this page, the nginx web server is successfully installed and working.</p> </body> </html>
Key Concept

If you remember nothing else from this pattern, remember: running containers as non-root improves security by limiting container permissions.

Common Mistakes
Not changing file ownership to the non-root user inside the container.
The application may fail to start or access files because the non-root user lacks permissions.
Use chown or similar commands in the Dockerfile to give the non-root user ownership of necessary files.
Forgetting to switch the user with the USER instruction in the Dockerfile.
The container will run as root by default, negating the security benefit.
Add USER appuser (or your chosen user) in the Dockerfile before the CMD or ENTRYPOINT.
Running commands that require root privileges after switching to the non-root user.
These commands will fail because the non-root user lacks permissions.
Run all root-required commands before switching users in the Dockerfile.
Summary
Create a non-root user and group inside the Dockerfile.
Change ownership of files the app needs to access to the non-root user.
Switch to the non-root user with the USER instruction before running the app.
Build and run the container, then verify it runs as the non-root user.