Run containers as a non-root user

The fixDockerfile

RUN addgroup -g 10001 app && adduser -u 10001 -G app -D app
USER 10001:10001

Or at runtime, for images you don’t control:

docker run --user 10001:10001 someimage

services:
  app:
    user: "10001:10001"

Why it matters

Containers run as root unless you say otherwise. UID 0 inside the container is UID 0 outside it — the kernel sees one number. Namespaces change what a process can see, not who it is.

That matters the moment anything is shared:

docker run -v /srv/data:/data myimage       # container root owns /srv/data

Root in that container can chown, chmod and rewrite everything under /srv/data on the host, because it is the same UID 0 the host uses. Add a careless mount — -v /etc:/etc in a debugging session — and it edits your passwd file.

It also raises the value of every other bug. A remote code execution in your app gives an attacker root inside the container, which means capabilities to work with and a much shorter path to a container escape. Running as UID 10001 means the same RCE lands as a user with nothing.

Pick a high, explicit UID

USER 10001:10001

Two details that matter:

Use a number, not a name. USER app requires the name to resolve inside the container, and Kubernetes’ runAsNonRoot check cannot verify a name — it needs a numeric UID to know the container isn’t root. A numeric USER works everywhere.

Use a high one. Low UIDs collide with real host accounts, so a container running as UID 100 writes files owned by whatever host user is 100 — often systemd-network or similar. Something in the 10000+ range collides with nothing.

userns-remap is the real fix, and it has real costs

Docker can map container UIDs to unprivileged host UIDs, so container root becomes an ordinary host user:

/etc/docker/daemon.json

{
  "userns-remap": "default"
}

Container UID 0 then maps to something like host UID 296608. Root in the container becomes root over nothing.

Be honest about the cost, because it’s why adoption is low:

• Existing volumes break. Files owned by real UID 0 become unreadable to the remapped root. Every existing named volume and bind mount needs its ownership fixed.
• --privileged, --pid=host, --network=host are incompatible with it and will fail.
• It’s daemon-wide. Every container is remapped or none is; there’s no per-container opt-out.

For a new deployment it’s excellent. For an existing one it is a migration, not a setting. Rootless mode achieves more and is often the better place to spend the same effort.

Verify it worked

Find every container running as root right now:

docker ps -q | xargs -r docker inspect \
  --format '{{.Name}}: user="{{.Config.User}}"' | grep 'user=""'

An empty user means root. That’s the finding — and it will be most of them on a first run.

Check what a container is actually running as, rather than what the config says:

docker exec <container> id

Expect uid=10001, not uid=0(root).

Check the daemon for user namespace remapping:

docker info --format '{{.SecurityOptions}}'

Look for name=userns. Its absence means container root is host root.

And prove the consequence, which is the part that convinces people — with a bind-mounted directory:

docker run --rm -v /tmp/demo:/data alpine sh -c 'touch /data/owned-by-root'
ls -l /tmp/demo/owned-by-root

That file is owned by root on your host, written by a container. That is the whole argument.

Before you apply this

Setting USER breaks images that expect to be root, and the failures are mundane rather than dramatic: permission denied writing a pidfile, binding port 80, or writing to a directory the Dockerfile created as root.

The three common breakages and their fixes:

Ports below 1024. A non-root process can’t bind port 80. Don’t add CAP_NET_BIND_SERVICE reflexively — change the container to listen on 8080 and publish it as -p 80:8080. The host side of a port mapping is done by the daemon, which is root, so this costs nothing.

Directories owned by root. Anything the Dockerfile created before USER is root-owned. Fix it in the image, at build time:

RUN mkdir -p /app/data && chown -R 10001:10001 /app/data
USER 10001:10001

Bind-mounted host directories. The host directory’s ownership decides access, and the container’s UID must match:

sudo chown -R 10001:10001 /srv/data

This is the one that bites in production, because it works in dev (where the directory happened to be world-writable) and fails on the server.

Do not enable userns-remap casually on a host with existing containers. Every volume’s ownership becomes wrong at once, and the recovery is manual chown of each. Test it on a fresh host first, and read the incompatibility list above — if anything you run uses --network=host, it stops working immediately.

Related

• Rootless mode — solves this more completely.
• Drop capabilities — narrow what root-in-container could do anyway.