How to Add Users to a Docker Container

Docker containers run as root by default, which poses security risks. Creating and managing users in containers is essential for following security best practices and implementing proper access control.

This guide covers three main approaches:

1. Creating users in Dockerfile - Build-time user creation
2. Runtime user creation - Adding users to running containers
3. User mapping - Mapping host users to container users

Let’s explore each method with practical examples.

Why Add Users to Docker Containers?

Running containers as root creates significant security vulnerabilities. Here’s why user management matters:

Security Benefits

• Principle of least privilege: Users get only necessary permissions
• Attack surface reduction: Limited access reduces potential damage
• Process isolation: Separate users can’t interfere with each other

Operational Benefits

• Better resource control: Set per-user resource limits
• Improved auditing: Track actions to specific users
• Easier collaboration: Multiple users without sharing credentials

Key Point: Never run production containers as root unless absolutely necessary.

Method 1: Creating Users in Dockerfile

The most common approach is creating users during the image build process.

Basic User Creation

FROM ubuntu:20.04

# Create a non-root user
RUN useradd -m -s /bin/bash appuser

# Switch to the new user
USER appuser

# Set working directory
WORKDIR /home/appuser

Advanced User Setup

FROM ubuntu:20.04

# Update package list
RUN apt-get update && apt-get install -y sudo

# Create user with specific UID/GID
RUN groupadd -r appgroup --gid=1001 && \
    useradd -r -g appgroup --uid=1001 --shell=/bin/bash --create-home appuser

# Add user to sudo group (if needed)
RUN usermod -aG sudo appuser

# Set password (for development only)
RUN echo 'appuser:password' | chpasswd

# Switch to non-root user
USER appuser

WORKDIR /home/appuser

Key Commands Explained

Command	Purpose	Example
useradd -m	Create user with home directory	useradd -m john
groupadd	Create user group	groupadd developers
usermod -aG	Add user to group	usermod -aG sudo john
USER	Set default user for container	USER appuser

Some other docker articles that can help you in your docker journey:

• Copy Multiple Files in One Layer Using a Dockerfile
• Install Docker & Docker-compose for Ubuntu ARM
• Redirect Docker Logs to a Single File
• Environment Variables ARG and ENV in Docker

Method 2: Runtime User Creation

You can also create users in running containers for temporary or testing purposes.

Create User in Running Container

# Enter the container
docker exec -it container_name bash

# Create user inside container
useradd -m -s /bin/bash newuser

# Set password
passwd newuser

# Add to sudo group (if needed)
usermod -aG sudo newuser

# Switch to new user
su - newuser

Using Docker Exec with Specific User

# Run commands as specific user
docker exec -it --user newuser container_name bash

# Or run single commands
docker exec --user newuser container_name whoami

Method 3: User and Group Mapping

Map host users to container users for better security and file permissions.

User ID/Group ID Mapping

FROM ubuntu:20.04

# Create user with specific UID/GID that matches host user
ARG USER_ID=1000
ARG GROUP_ID=1000

RUN groupadd -g $GROUP_ID appgroup && \
    useradd -u $USER_ID -g $GROUP_ID -m -s /bin/bash appuser

USER appuser

Build with host user IDs:

docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t myapp .

Docker Compose User Mapping

version: '3.8'
services:
  app:
    build: .
    user: "${UID}:${GID}"
    volumes:
      - .:/app
    environment:
      - USER_ID=${UID}
      - GROUP_ID=${GID}

Run with:

UID=$(id -u) GID=$(id -g) docker-compose up

Best Practices for Docker User Management

1. Always Use Non-Root Users

# Good - Create and use non-root user
FROM ubuntu:20.04
RUN useradd -m appuser
USER appuser

# Bad - Running as root (default)
FROM ubuntu:20.04
# No USER instruction = runs as root

2. Set Specific UID/GID

# Prevents permission issues with mounted volumes
RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m appuser
USER appuser

3. Use Multi-Stage Builds for User Setup

# Build stage - can use root for installations
FROM ubuntu:20.04 as builder
RUN apt-get update && apt-get install -y build-essential
COPY . /src
WORKDIR /src
RUN make build

# Runtime stage - use non-root user
FROM ubuntu:20.04
RUN useradd -m appuser
USER appuser
COPY --from=builder /src/app /home/appuser/app
WORKDIR /home/appuser

4. Handle File Permissions Correctly

# Set proper ownership for application files
COPY --chown=appuser:appuser app/ /home/appuser/app/
USER appuser

5. Security Checklist

✅ Do	❌ Don’t
Create dedicated users	Run as root in production
Use specific UID/GID	Use random UIDs
Set proper file ownership	Give 777 permissions
Test user permissions	Assume permissions work
Use USER instruction	Rely on runtime user switching

6. Testing User Setup

# Test user creation
docker run --rm -it myapp whoami

# Test file permissions
docker run --rm -it myapp ls -la /home/appuser

# Test application functionality
docker run --rm -it myapp /home/appuser/app/test.sh

Quick Reference

Common User Creation Commands

# Create user with home directory
useradd -m -s /bin/bash username

# Create user with specific UID/GID
useradd -u 1001 -g 1001 -m username

# Add user to group
usermod -aG groupname username

# Change file ownership
chown -R username:groupname /path/to/files

Dockerfile User Examples

# Simple non-root user
FROM ubuntu:20.04
RUN useradd -m appuser
USER appuser

# User with sudo access
FROM ubuntu:20.04
RUN apt-get update && apt-get install -y sudo
RUN useradd -m -s /bin/bash appuser
RUN usermod -aG sudo appuser
USER appuser

# User with specific UID/GID
FROM ubuntu:20.04
RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m appuser
USER appuser

Key Takeaways

1. Never run production containers as root - Create dedicated users
2. Use consistent UID/GID - Prevents permission issues with volumes
3. Test user permissions - Verify everything works before deployment
4. Set proper file ownership - Use COPY --chown in Dockerfiles
5. Follow least privilege principle - Give users only necessary permissions

Implementing proper user management in Docker containers significantly improves security. Start with basic non-root users and gradually implement more advanced features like user namespaces as needed.