doc: How to control docker without root olivetin/docs.olivetin.app#40

docs/modules/ROOT/pages/install/docker_compose.adoc

@@ -28,15 +28,30 @@ volumes:
 
 include::partial$install/post_container.adoc[]
 
+[#compose-docker-socket]
 == Controlling other docker containers from a Docker Compose install of OliveTin
 
-If you want to use OliveTin running in a container to control other Docker containers, you will need to pass through the Docker sock in your compose file. 
+If you want OliveTin running in a container to control other Docker containers, pass the Docker socket into the service and give the container process membership in the same numeric `docker` group that owns the socket on the host.
 
-You will need to adjust your docker-compose file to include the docker socket, like this;
+On many Linux installs, Docker Engine creates a `docker` group automatically; see https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user[Manage Docker as a non-root user] in the Docker documentation.
+
+=== Find the `docker` group GID on the host
+
+On the Docker host, read the `docker` group numeric ID (third field of the output):
+
+[source,bash]
+----
+getent group docker
+----
+
+If that command prints nothing, create the group or finish Docker post-install steps first, then retry.
+
+=== Add the socket mount and `group_add` in Compose
+
+In `docker-compose.yml`, bind-mount the socket and add `group_add` with that GID (as a string is fine). Replace the example GID with the value from your host:
 
- `docker-compose.yml` including docker socket
 [source,yaml]
-.docker-compose.yml
+.`docker-compose.yml` including Docker socket access without running as root
 ----
 services:
   olivetin:
@@ -44,26 +59,31 @@ services:
     image: jamesread/olivetin
     volumes:
       - /docker/OliveTin:/config # replace host path or volume as needed
-      - /var/run/docker.sock:/var/run/docker.sock 
-    ...
+      - /var/run/docker.sock:/var/run/docker.sock
+    group_add:
+      - "992" # <1>
 ----
+<1> Replace `992` with the GID from `getent group docker` on the machine where Compose runs. The number is not portable between hosts.
 
-You will probably need to tell this container to run as root as well, to control docker (see below).
+This keeps the default container user while allowing access to `/var/run/docker.sock`, which is usually tighter than running the whole service as `root`.
 
-== Controlling the docker user with Docker Compose
+See xref:action_examples/containers.adoc[containers] for `docker run`, `--privileged`, and other options if you cannot use a `docker` group on the host.
 
-This is the correct way to tell the OliveTin container to run as root (or any other user);
+== Running the OliveTin container as a different user in Compose
 
+If you need the service to run as a specific Unix user in Compose for reasons other than Docker socket access, set `user` explicitly, for example:
+
+[source,yaml]
 ----
 services:
   olivetin:
     container_name: olivetin
     image: jamesread/olivetin
-    user: root 
+    user: "1000:1000"
     ...
 ----
 
-See xref:action_examples/containers.adoc[containers] for alternatives to running as root.
+For Docker socket access from Compose, prefer <<compose-docker-socket,`group_add` with the host `docker` group GID>> instead of `user: root`.
 
 
 NOTE: xref:troubleshooting/puid-pgid.adoc[PUID and PGID are not used] by the official OliveTin container image.