docs: --user is only required when docker run as root

The --user argument attempts to map the uid of the user inside the
container to the user in the host. This works if docker is running as
root, but is docker is running as the current user, then the uid in the
container is mapped to a surrogate uid on the host, and this surrogate
user does not have permissions to complete the build process.

Clarify that the --user flag is only required when running docker as
root. It is also likely not required by users using podman as a docker
drop-in replacement, since podman always runs in rootless mode.

1 files changed, 12 insertions, 4 deletions

diff --git a/doc/buildWithDocker.md b/doc/buildWithDocker.md
index 04787b26..db9bfcfc 100644
--- a/doc/buildWithDocker.md
+++ b/doc/buildWithDocker.md
@@ -65,12 +65,20 @@ Outputs will be written to **<project_root>/build/output**:
 
 ```sh
 cd <project_root> # e.g. cd ./work/Pinetime
-docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build
+docker run --rm -it -v ${PWD}:/sources infinitime-build
 ```
 
-By default, the container runs as `root`, which is not convenient as all the files generated by the build will also belong to `root`.
-The parameter `--user` overrides that default behavior.
-The command above will run as your current user.
+If the docker service is running as `root`, the build process inside the
+container also runs as `root`, which is not convenient as all the files
+generated by the build will also belong to `root`. The parameter `--user`
+overrides this behaviour. The command below ensures that all files are created
+as your current user:
+
+
+```sh
+cd <project_root> # e.g. cd ./work/Pinetime
+docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build
+```
 
 If you only want to build a single CMake target, you can pass it in as the first parameter to the build script.
 This means calling the script explicitly as it will override the `CMD`.