From 5d56fadcf8776e48d5a4450380935ef6c46df8d5 Mon Sep 17 00:00:00 2001
From: Umputun <umputun@gmail.com>
Date: Tue, 27 Jan 2026 16:13:16 -0600
Subject: [PATCH] add DOCKER_GID runtime customization for docker socket access

When mounting docker socket with a different GID on the host, the container's
default docker group (GID 999) doesn't match, causing socket access failures.

This adds DOCKER_GID env var handling to init.sh:
- If DOCKER_GID differs from default 999, reconfigure docker group
- If requested GID is used by another group, reuse that group instead
- Includes error handling for group operations

Related to https://github.com/umputun/updater/pull/48
---
 CLAUDE.md                 |  2 +-
 README.md                 | 12 ++++++++++++
 base.alpine/files/init.sh | 29 +++++++++++++++++++++++++++++
 3 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 65bbb33..f8e424e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,7 @@ make build_scratch_multi
 
 - `base.alpine/` - Alpine runtime image
   - `Dockerfile` - image definition
-  - `files/init.sh` - entrypoint script, handles timezone and UID setup, drops to app user
+  - `files/init.sh` - entrypoint script, handles timezone, UID, and docker GID setup, drops to app user
   - `files/init-root.sh` - alternative entrypoint for root execution
 - `base.scratch/` - Scratch runtime image (builds /nop wait program from C)
 - `build.go/` - Go build image
diff --git a/README.md b/README.md
index f6a0909..d03cf52 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ The container can be customized in runtime by setting environment from docker's
 
 - `TIME_ZONE` - set container's TZ, default "America/Chicago". For scratch-based `TZ` should be used instead
 - `APP_UID` - UID of internal `app` user, default 1001
+- `DOCKER_GID` - GID of the docker group, default 999. Useful when mounting docker socket with a different GID on the host
 
 ### Working with Docker from inside container
 
@@ -44,6 +45,17 @@ The `app` user is a member of the `docker` group. That allows it to interact wit
 
 Under standard usage, the Docker socket is not mounted into the container. In such cases, the docker group membership does not grant the app user any elevated privileges. The container remains secure and operates with an unprivileged user.
 
+When the host's docker group has a different GID than the container's default (999), set `DOCKER_GID` to match the host's GID:
+
+```bash
+# find your host docker GID
+stat -c %g /var/run/docker.sock  # Linux
+stat -f %g /var/run/docker.sock  # macOS
+
+# run with matching GID
+docker run -e DOCKER_GID=998 -v /var/run/docker.sock:/var/run/docker.sock <image>
+```
+
 #### Security Implications
 
 Mounting the Docker socket into a container can pose a security risk, as it effectively grants the container access to the Docker host and its containers. This is not specific to this image but is a general consideration when working with Docker.
diff --git a/base.alpine/files/init.sh b/base.alpine/files/init.sh
index a379861..a4e6e68 100644
--- a/base.alpine/files/init.sh
+++ b/base.alpine/files/init.sh
@@ -18,6 +18,35 @@ if [[ ${uid} -eq 0 ]]; then
     else
         echo "custom APP_UID not defined, using default uid=1001"
     fi
+
+    # set GID for docker group
+    if [[ "${DOCKER_GID}" -ne "999" ]]; then
+        echo "set custom DOCKER_GID=${DOCKER_GID}"
+        # check if another group already uses this GID
+        existing_group=$(getent group "${DOCKER_GID}" | cut -d: -f1)
+        if [[ -n "${existing_group}" && "${existing_group}" != "docker" ]]; then
+            # reuse existing group - add app to it for socket access
+            echo "GID ${DOCKER_GID} used by '${existing_group}', adding app to it"
+            if ! addgroup app "${existing_group}"; then
+                echo "error: failed to add app user to group '${existing_group}'"
+                exit 1
+            fi
+        else
+            # no collision - create docker group with requested GID
+            delgroup docker 2>/dev/null || true
+            if ! addgroup -g "${DOCKER_GID}" docker; then
+                echo "error: failed to create docker group with GID=${DOCKER_GID}"
+                exit 1
+            fi
+            if ! addgroup app docker; then
+                echo "error: failed to add app user to docker group"
+                exit 1
+            fi
+        fi
+    else
+        echo "custom DOCKER_GID not defined, using default gid=999"
+    fi
+
     chown -R app:app /srv /home/app
 fi