USER Non Root Runtime

USER non-root runtime is the practice of explicitly configuring a container's main process to run as an unprivileged user rather than root, significantly limiting what a compromised application process could do even if it were successfully exploited.

Creating a Dedicated Non-Root User

A common pattern creates a dedicated user specifically for running the application, rather than relying on whatever non-root users a base image might already include.

FROM python:3.12-slim
RUN useradd --create-home --shell /bin/bash appuser
WORKDIR /app
COPY --chown=appuser:appuser . .
USER appuser
CMD ["python", "app.py"]

Why Many Official Images Already Provide a Non-Root User

Several official runtime images include a pre-created, conventionally named non-root user specifically to make this pattern easier to adopt without needing to create one manually.

FROM node:20-alpine
USER node

The node image conventionally provides a user also named node, making this a one-line addition rather than requiring explicit user creation.

Verifying the Container Actually Runs as Non-Root

After configuring USER, confirming the container's main process actually runs as the intended unprivileged user is a useful verification step.

docker run --rm myapp whoami
docker run --rm myapp id

Handling File Permission Issues

Running as a non-root user can sometimes surface permission errors if files or directories the application needs to write to are not owned by, or writable by, that user — using --chown on relevant COPY instructions, or explicitly adjusting permissions, addresses this.

COPY --chown=appuser:appuser . /app
RUN mkdir -p /app/logs && chown appuser:appuser /app/logs

Why Non-Root Runtime Matters

Running as a non-root user is one of the most effective, low-cost security improvements available for a containerized application — it does not prevent every possible attack, but it meaningfully reduces what a successful one could actually accomplish, which is a significant improvement over the unrestricted default of running as root.