User Namespace Remapping, UID/GID Mapping, Non-Root Images, Filesystem Ownership, and Least Privilege: Configuration, Design Choices, and Tradeoffs

1. Fixed numeric UID versus named user

2. Image-time chown versus runtime ownership initialization

COPY --chown is deterministic for files that belong in the image. It should be preferred for application code/config that is immutable at runtime. Persistent volumes are different: the data outlives containers, can be restored from backups, and may have its own lifecycle. A controlled initialization step can prepare a new volume, but that step needs explicit authority and must not silently re-own arbitrary existing data.

Do not solve a persistent-data ownership problem by recursively chowning unknown content on every startup. Record a data version, expected UID/GID, and migration step.

3. userns-remap versus rootless: same technology family, different daemon boundary

4. Volume initialization pattern: separate provisioning from steady-state runtime

A clean pattern is: provision the volume once with the minimum authority required to create the intended directory/ownership, then run the application permanently as the non-root UID. Treat provisioning as a deployment/migration action with its own logs and rollback—not as an invisible root shell in the main container.

5. Group-based shared writes

When two processes need shared write access, a shared GID plus group-write/setgid directory can be more precise than forcing a shared UID. Docker also supports supplementary groups at runtime. Record the numeric GID and verify both container processes actually carry it. The group model still must line up with userns mappings and host/volume ownership.

# Read-only evidence pattern
id
docker inspect CONTAINER --format 'User={{json .Config.User}} GroupAdd={{json .HostConfig.GroupAdd}}' 2>/dev/null || true

6. Compose user and portable application models

Compose user: overrides the user configured by the image. Use it when the environment owns the identity contract; avoid adding it reflexively when the image already has a correct non-root user and prepared filesystem. Otherwise local Compose may work while another runtime that relies on image metadata fails differently.

7. Decision table

8. Timestamped assumptions and portability checklist

• Record Engine/Compose versions and daemon security options.
• Record numeric UID/GID; do not store only usernames.
• Record subordinate ranges if user namespaces matter.
• Record mount type and host/volume ownership.
• Record whether ownership preparation occurs at image build, deployment initialization, or runtime.
• Do not assume Docker Desktop host-file semantics equal native Linux.

Knowledge check

Official references and version notes

• User namespace remapping — current prerequisites, mapping behavior, daemon configuration, limitations, and migration cautions.
• Rootless UID/GID mapping — precise difference between userns-remap and rootless host-ID translation.
• Rootless mode — daemon-level non-root execution and subordinate-ID prerequisites.
• Dockerfile reference — USER and COPY --chown semantics, including numeric versus name lookup.
• Compose services reference — service user override and user namespace configuration surface.
• Bind mounts — host-path ownership, read/write authority, and daemon-host path semantics.
• Volumes — Docker-managed persistent storage and container mount behavior.
• Docker Engine 29 release notes — current Engine baseline and user-namespace-related fixes/changes.