The Correct Way to Create Users in Dockerfile: A Comprehensive Guide from useradd to USER Instruction

Fundamentals of User Management in Dockerfile

In Docker container environments, user management is a critical component of both security and functionality. Many developers encounter issues related to user creation when first using Dockerfile, particularly confusing the functions of the useradd command and the USER instruction. This article will analyze in detail how to correctly create and use users in Dockerfile through a specific case study.

Case Study Analysis

Consider the following Dockerfile snippet, which represents a common error pattern among developers:

FROM alpine:3.4
RUN apk update && apk add curl unzip
RUN useradd -ms /bin/bash vault

USER vault
WORKDIR /usr/local/bin/vault
ADD /vault.hcl /etc/vault/vault.hcl

RUN curl -SL https://releases.hashicorp.com/vault/0.5.0/vault_0.5.0_linux_amd64.zip > vault.zip
RUN unzip vault.zip -d /usr/local/bin && rm vault.zip

This Dockerfile attempts to create a user named "vault", but the developer finds that the USER vault instruction doesn't seem to work. The core issue lies in misunderstanding the function of the USER instruction.

Difference Between useradd and USER Instruction

useradd is a Linux system command used to create new users in the system. In Dockerfile, it's executed through the RUN instruction:

RUN useradd -ms /bin/bash vault

The parameters here mean: -m creates the user's home directory, -s specifies the default shell as /bin/bash. This command does create a user named "vault" in the container.

The USER instruction serves a completely different purpose. According to Docker official documentation, the USER instruction sets the runtime user, not creates a user. It specifies which user identity subsequent RUN, CMD, and ENTRYPOINT instructions should execute as.

Correct User Creation Process

To correctly create and use users in Dockerfile, follow these steps:

1. Create User: Use RUN useradd command to create the user
2. Set Working Directory: Use WORKDIR to set the user's working directory
3. Switch User: Use USER instruction to switch to the newly created user
4. Execute Subsequent Operations: All subsequent commands will execute as the new user

Complete Example Code

Here's the corrected Dockerfile example:

FROM alpine:3.4

# Update package manager and install necessary tools
RUN apk update && apk add curl unzip

# Ensure bash is the default shell
RUN ln -sf /bin/bash /bin/sh

# Create vault user
RUN useradd -ms /bin/bash vault

# Set working directory
WORKDIR /usr/local/bin/vault

# Switch to vault user
USER vault

# Add configuration file
ADD /vault.hcl /etc/vault/vault.hcl

# Download and install vault
RUN curl -SL https://releases.hashicorp.com/vault/0.5.0/vault_0.5.0_linux_amd64.zip > vault.zip
RUN unzip vault.zip -d /usr/local/bin && rm vault.zip

Importance of Shell Configuration

In lightweight distributions like Alpine Linux, the default shell is typically /bin/sh, which may not be compatible with the -s parameter of the useradd command. The solution is:

RUN ln -sf /bin/bash /bin/sh
RUN useradd -ms /bin/bash vault

This command creates a symbolic link from /bin/sh to /bin/bash, ensuring bash becomes the default shell.

Security Best Practices

In production environments, it's recommended to follow these security best practices:

• Run container applications with non-root users
• Create dedicated users for different services
• Limit user permissions to the minimum necessary scope
• Regularly review and update user configurations

Common Errors and Solutions

1. Error: Using USER directly without creating the user first
Solution: Ensure the user has been created via useradd before using the USER instruction

2. Error: Shell incompatibility causing user creation failure
Solution: Check and set the correct default shell

3. Error: Permission issues causing file operation failures
Solution: Ensure all privileged operations are completed before switching users

Conclusion

Correctly understanding the difference between the useradd command and the USER instruction is key to user management in Dockerfile. useradd is used to create users, while USER is used to switch runtime user identity. By following the correct creation sequence and considering shell compatibility, common user management issues can be avoided, resulting in more secure and reliable Docker images.