11.1 Running Containers as Non-Root

Why Non‑Root Matters in Containers

In most base images the default user inside the container is root. This user has full control over the container’s filesystem and processes. Inside a single container this can feel convenient, but it has important security implications.

If an attacker exploits a vulnerability in your application while it runs as root inside the container, that attacker can potentially use container escape vulnerabilities or misconfigurations to impact the host. Even when isolation holds, root in one container might cause damage to shared resources such as volumes, or interfere with other containers that share parts of the filesystem.

Running your containers as a non‑root user is a core hardening technique. It limits what an attacker can do if they gain code execution inside the container, and helps enforce the principle of least privilege for your application.

The `USER` Instruction in Dockerfiles

The primary mechanism to run containers as non‑root is the USER instruction in your Dockerfile. This instruction changes the default user for all subsequent instructions in the build, and for the final container at runtime, unless overridden by docker run.

A typical pattern is to create a dedicated user and group, adjust ownership and permissions on application files, then switch to that user near the end of the Dockerfile. For example, a Dockerfile might start as root so it can install packages, then later switch to a restricted user to run the application.

Once USER is set, every process started by CMD or ENTRYPOINT runs as that user. Inside the container tools such as whoami or id would then show the non‑root identity.

Creating Users and Groups Inside Images

Before you can use a non‑root user, you usually need to create it. In Linux based images this is typically done with system utilities such as useradd, adduser, groupadd, or their distribution specific variants.

A common production pattern is to create a dedicated application user with:

• A fixed numeric user ID, so that permission behavior with mounted volumes is predictable.
• No login shell, and sometimes a non‑existent or restricted home directory, to reduce interactive capabilities.
• Minimal group memberships.

You might create a group first, then the user, and then set the correct ownership for application directories. This preparation is done while the Dockerfile still runs as root, because only root can add users and change ownership broadly.

Once the user exists and the filesystem is ready, you can switch to that user with the USER instruction.

Dealing with File Permissions

Running as non‑root brings permission challenges. Many base images and third party images assume root and therefore do not set restrictive file permissions. When you change to a non‑root user, you must ensure that all directories your application needs to write into are accessible.

For application code, you often want the non‑root user to have read and maybe execute permissions, but not write permissions, to protect code from modification. For log directories, temporary directories, cache directories, and data folders, the non‑root user typically needs write permissions.

A common sequence is:

Create the directory if it does not exist. Change its ownership to the dedicated user and group. Optionally restrict the mode bits so only that user or group can write. This way, when the container starts under the non‑root user, it can write where needed without having broad privileges.

If your image uses a fixed user ID, this can also simplify permission management when you use volumes, because the host filesystem can be configured to give that UID exactly the needed rights.

Overriding the User at Runtime

Even if the Dockerfile defines a default user, Docker lets you override it when running a container. The docker run command accepts a user specification with the --user flag. This flag can take a username, a numeric user ID, or a user:group pair. If you choose numeric IDs, Docker does not need to resolve names from /etc/passwd or /etc/group inside the container.

Runtime override is useful in several cases. You might need to run administrative tasks as root temporarily while the default is non‑root, for example to perform database migrations. In that case you would intentionally start a short lived container with --user root and an explicit command. Conversely, you might not control the Dockerfile for an image that defaults to root, so you can enforce a lower privilege user from the outside using --user.

When you use --user, you must still respect filesystem permissions. If the container process runs as a user that does not have write permission to the needed directories, your application will fail, even if the Dockerfile appears correct.

Base Images and Non‑Root Defaults

Some security focused or language specific base images already define a non‑root default user. For example, some official images for languages such as Node.js or Java create an application user during build and set it as the default. In these images, running whoami inside a normal container session will already show a non‑root identity.

When you build on top of such an image, you should be aware of its default user. If your Dockerfile assumes root and tries to run privileged operations like package installation, your build might fail because it no longer has the required permissions. In that case, you may temporarily switch back to root with USER root, perform the administrative steps, and then restore the non‑root user, or better, choose a base variant that is designed for modification.

Understanding the base image’s user model is important if you want consistent behavior around permissions, especially when combining your Dockerfile with volumes and orchestration tools.

Limitations of Non‑Root Inside Containers

Running as non‑root is an important defense, but it is not a complete isolation mechanism by itself. The user model inside a container still maps to the kernel’s user model on the host. In the default configuration, user ID 0 in the container is the same as user ID 0 on the host. User ID 1000 in the container is the same as user ID 1000 on the host, and so on.

Because of this mapping, non‑root users inside a container may still have meaningful permissions on files that are mounted from the host, depending on ownership and mode bits. Conversely, if the host filesystem uses restrictive permissions, a container user might be unable to access necessary files even if the container itself is configured correctly.

For stronger isolation you can combine non‑root users with other mechanisms such as user namespaces, read only filesystems, or additional access controls. These are addressed in other security related chapters, but it is useful to remember that non‑root is one layer among several.

Integrating Non‑Root into Your Workflow

To consistently run containers as non‑root, it is helpful to make it part of your regular development and build practices. When you write Dockerfiles, consider creating the dedicated user and switching to it as a standard step. When you choose base images, prefer those that are designed for non‑root operation, or that document clearly which users they provide.

During local development, you might be tempted to run as root to avoid permission issues. However, subtle permission differences between development and production can cause surprises later. Aligning your development containers with your production security posture, including non‑root users, will reveal configuration problems earlier.

Finally, in environments that use Compose or orchestration systems, you can encode user requirements in configuration files, for example by specifying a user in service definitions. This provides a visible contract that services are intended to run with restricted privileges, and helps prevent accidental regressions to root operation when images are updated or replaced.