Step 01 of 06
Understand the idea
By default, a program in a container may run as the root user. If it does not need extra permissions, run it as a regular user instead. This reduces the damage it could cause if the program or container is compromised.
Key technical ideas
Root is a bundle of privileges, not a vibe
UID 0 bypasses normal Unix permission checks and may hold Linux capabilities such as CAP_NET_RAW or CAP_CHOWN. Container runtimes drop many capabilities by default, but not all risk disappears. Running as a numeric non-root UID means ordinary file permissions work against an attacker who only controls the Beacon process.
Kubernetes prefers numbers because names lie
A username like app is resolved through files inside the image. Some minimal images have no /etc/passwd, and different images can map the same name to different IDs. A numeric UID such as 65532 is unambiguous. It also maps cleanly to Kubernetes runAsUser, runAsGroup, and fsGroup later.
Read-only root makes writes visible by design
If the root filesystem is read-only, the process cannot casually write logs, temp files, or SQLite databases into random paths. That sounds annoying because it is doing its job. Beacon should log to stdout and write its database only under a mounted directory such as /var/lib/beacon.
Volumes are permission contracts
A mounted directory is not automatically writable. The UID inside the container must have permission on the mounted path. In local Docker, a named volume is usually easy. Bind mounts from macOS or Linux hosts can expose UID mismatches. The fix is not USER root; it is owning the data path deliberately.
docker run --rm --user 65532:65532 --read-only alpine:3.20 sh -c 'id; touch /root/nope'
# touch: /root/nope: Read-only file systemThe exact Alpine error can vary, but the mechanism does not: a non-root user on a read-only filesystem cannot write wherever it feels like writing.
Security knobs that get confused
| Knob | Controls | Does not control |
|---|---|---|
| Default UID and GID | Kernel capabilities by itself |
Capabilities | Special kernel privileges | Filesystem ownership |
Read-only root | Writes to image layer | Mounted volume writes |
Volume | Durable writable path | Application correctness |
Technical terms used at work
UID — The numeric user identity the kernel uses for permission checks.
Capability — A slice of root privilege, such as binding low ports or changing ownership.
Read-only root — A runtime setting that prevents writes to the image filesystem layer.
