PUID/PGID mechanism fails to grant Docker socket permissions on Unraid

[arod20832]

Description

There appears to be a fundamental incompatibility or bug within the container's startup script that prevents the PGID environment variable from correctly adding the node user to the specified group on an Unraid OS system. This prevents the Docker widget from accessing /var/run/docker.sock due to a permissions failure, resulting in a persistent "Missing Docker" error.

This issue has been reproduced across multiple versions of the gethomepage/homepage image, including :latest, :v1.5.0, and :v1.4.6.

System Details

• Operating System: Unraid OS 7.1.4 (latest stable)
• Installation Method: Docker container via Unraid's Community Applications plugin.
• Homepage Versions Tested: latest, v1.5.0, v1.4.6

The Problem: A Permissions Mismatch

After extensive debugging, the core issue has been identified:

1. The Homepage application runs as the node user (UID 1000).
2. On Unraid, the Docker socket has restricted group permissions. In this case, it is owned by root and group 281: srw-rw---- 1 root 281.
3. The node user must be a member of group 281 to access the socket.
4. Despite correctly setting the PGID=281 environment variable, the container's startup script fails to add the node user to this group.

Steps to Reproduce

1. Install the ghcr.io/gethomepage/homepage:latest container on a standard Unraid system.
2. Map the Docker socket as a volume: -v /var/run/docker.sock:/var/run/docker.sock:ro.
3. Configure docker.yaml with a socket connection:

   unraid-docker:
     socket: /var/run/docker.sock

4. Configure widgets.yaml to display the widget:

   - docker:
       host: unraid-docker

5. Observe the "Missing Docker" error on the dashboard.
6. Determine the GID of the Docker socket on the host (in this case, 281).
7. Add the PUID=1000 and PGID=281 environment variables to the container configuration and restart the container.
8. Open a console into the container and run su node -c "id" to verify the user's groups.

Expected Behavior

After setting PGID=281, the node user (UID 1000) should be added to group 281. The output of su node -c "id" should be similar to:
uid=1000(node) gid=1000(node) groups=1000(node),281

The Docker widget should then successfully connect to the socket and display container information.

Current Behavior & Logs

The PGID variable has no effect. The node user is never added to the specified group, regardless of the image version used.

Verification from inside the container:

# Check socket permissions
/app # ls -l /var/run/docker.sock
srw-rw----    1 root     281              0 Oct  4 16:20 /var/run/docker.sock

# Verify the application user's groups (the crucial command)
/app # su node -c "id"
uid=1000(node) gid=1000(node) groups=1000(node),1000(node)

As shown, the groups list for the node user is missing 281.

Additional Troubleshooting Steps Taken

• Confirmed all YAML configuration files (docker.yaml, widgets.yaml) are syntactically correct and use matching hostnames.
• Attempted to use the Docker --group-add 281 parameter. This correctly added the root shell user to group 281 but had no effect on the node user that the application process runs as.
• Changed the Docker socket volume mount from ro (read-only) to rw (read/write).
• Tested three separate image versions (latest, v1.5.0, v1.4.6) with the same negative result, indicating this is not a recent regression.

It seems the entrypoint script responsible for handling user/group permissions is not functioning as intended in this specific environment. Thank you for looking into this.

homepage version

v1.5.0

Installation method

Docker

Configuration

/app/config # cat docker.yaml 
unraid-docker:
  socket: /var/run/docker.sock

/app/config # cat widgets.yaml 
- docker:
    host: unraid-docker

Container Logs

/app/config already owned by correct UID/GID, skipping chown
Fixing ownership of /app/.next
▲ Next.js 15.4.5

• Local: http://localhost:3000
• Network: http://0.0.0.0:3000

✓ Starting...
✓ Ready in 398ms

Browser Logs

No response

Troubleshooting

Additional Troubleshooting Steps Taken

• Confirmed all YAML configuration files (docker.yaml, widgets.yaml) are syntactically correct and use matching hostnames.
• Attempted to use the Docker --group-add 281 parameter. This correctly added the root shell user to group 281 but had no effect on the node user that the application process runs as.
• Changed the Docker socket volume mount from ro (read-only) to rw (read/write).
• Tested three separate image versions (latest, v1.5.0, v1.4.6) with the same negative result, indicating this is not a recent regression.

[shamoon]

Appreciate the AI generated thorough report, but this isn’t actually a bug in Homepage.

The container doesn’t (and shouldn’t) modify system group memberships at runtime — PUID and PGID simply set the process’s primary user and group IDs. They don’t automatically add users to arbitrary host groups, and that behavior is completely normal for Node-based containers.

In other words, everything here is working exactly as expected. It looks like the “root cause” is just a misunderstanding of how Linux permissions and Docker user mapping work.

[arod20832]

Fair enough. I was able to get things working with the docker socket-proxy.

However, what is the point of the PGID parameter if not to have the node process run under this group? Currently, if I pass a PGID parameter to this container, then the root user of the container is added to that group id. However this doesn't help me since the node process which the dashboard is running under is not part of that group and therefore has no access to the docker socket.

[github-actions[bot]]

This discussion has been automatically closed due to inactivity. See our contributing guidelines for more details.

[github-actions[bot]]

This discussion has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion for related concerns. See our contributing guidelines for more details.