How to Configure Container User IDs Across Multiple NAS Shares

Configure container user IDs across multiple NAS shares by mapping the actual numeric identity of each container process to the owner, group, ACL, and mount mode of every share it needs.

Do not force one UID to own every dataset and do not use chmod 777 as the integration strategy. A media server may need read-only access to photos, a downloader may need read/write access to an ingest share, and a backup container may need a different protected destination. Use ownership for primary responsibility and groups or ACLs for shared access.

Record the Three Identities Before Changing Permissions

For each service, record the NAS-side owner UID/GID, the numeric user and groups of the process inside the container, and any image-specific identity convention such as PUID/PGID. Those three values are often confused because usernames can look identical while numeric IDs differ.

A current PUID and PGID are not Docker settings makes the distinction explicit: PUID and PGID are variables interpreted by selected container images, not universal Docker settings.

Verify the running process with id inside the container and inspect host files with numeric ownership. Do not assume the values written in Compose actually control the process unless the image supports that method.

Use a Primary Owner and Shared Groups for Cross-Service Data

A share used by one application can have a dedicated owner. A share written by several services is usually easier to manage with a deliberate shared group or ACL that grants only the operations those services require.

A practical explanation of numeric UID and GID ownership shows why bind-mounted files follow host numeric ownership and why matching or deliberately mapping those IDs prevents root-owned output and permission failures.

For a media workflow, for example, the downloader can own its staging files while both downloader and organizer belong to a media group. Set directory inheritance, default ACLs, or appropriate umask behavior so new files keep the shared access automatically.

Give Each Share Only the Mount Rights the Container Needs

Identity is only one layer. A correctly mapped UID still cannot write through a read-only bind mount, and a container with broad filesystem permission can still be constrained safely by mounting a library as read-only.

A 2026 runtime user overrides explains how bind mounts use host ownership and how runtime user: settings can align process IDs, while also warning that forcing a user can break images whose startup logic expects different privileges.

Document each host path, container path, mount mode, required operations, and responsible service. Use read-only mounts for libraries a service only consumes and reserve write access for the smallest path that actually needs it.

-15% OFF

ZimaBoard 2 - Mini Home Server for Your Big Idea

Single board computer zimaboard2

$339.00 - $519.00

Buy Now

Handle Multiple NAS ACL Models Deliberately

SMB/NFSv4 ACLs, POSIX ACLs, NFS identity mapping, and simple Unix mode bits can present different views of access. A share that works through SMB as one NAS user can still reject a container process using a different numeric identity on the host.

The related ZimaSpace article on NAS permission changes shows why destination ACL inheritance, SMB identity, container UID/GID, and umask need to be diagnosed as separate layers.

When several protocols touch one dataset, choose one permission model and document it. Repeatedly mixing NAS GUI ACL changes with shell chmod and chown commands can make the next file behave differently from the last.

Test File Creation From Every Writer Before Applying Recursively

Create a disposable test directory with the intended ownership and ACL. From each container, test listing, reading, creating, renaming, and deleting only the operations that service requires. Then inspect the new file's numeric owner, group, mode, and inherited ACL from the NAS.

If old files work but newly created files fail for another service, fix the creation path: group membership, default ACL, umask, or application-specific file mode. A recursive repair of old data does not prevent the same mismatch from returning tomorrow.

Roll out to production only after every writer creates files that the next required service can use without elevated permissions. A clean UID/GID design is recoverable because the mapping is documented and repeatable, not because every container happens to run as the same user.