From 8e1d3f8d2db5d5ab6528e7e97165b89e5319862d Mon Sep 17 00:00:00 2001 From: jamesread Date: Sun, 10 May 2026 23:22:24 +0100 Subject: [PATCH] doc: How to control docker without root olivetin/docs.olivetin.app#40 --- .../ROOT/pages/install/docker_compose.adoc | 42 ++++++++++++++----- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/docs/modules/ROOT/pages/install/docker_compose.adoc b/docs/modules/ROOT/pages/install/docker_compose.adoc index 6ed4bf1..b4a5c52 100644 --- a/docs/modules/ROOT/pages/install/docker_compose.adoc +++ b/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 <> instead of `user: root`. NOTE: xref:troubleshooting/puid-pgid.adoc[PUID and PGID are not used] by the official OliveTin container image.