fix user group setting for git-cache-rs, add documentation

[crasbe]

Currently, the user group of the user in the Docker container is set to 0 = root. This leads to issues when the Docker container commands are accessing outside files, such as the gitcache because the user groups mismatch and git-cache-rs will refetch the files.

docker run -it --rm --user $(id -u) docker.io/riot/riotbuild@sha256:028d9267e715e992d9b47bb8738685c6cc96b1a3bc3924489e7e543a333e8486 id
uid=30037(riotbuild) gid=0(root) groups=0(root)

buechse@skyleaf:~/RIOTstuff/riot-vanillaice/RIOT$ ls ~/.gitcache/github.com/ -l
total 24
drwxr-xr-x 3 buechse root    4096 Apr 22 17:25 ARM-software
drwxrwxr-x 3 buechse buechse 4096 Mar 12 10:51 laurencelundblade
drwxr-xr-x 3 buechse root    4096 Apr 22 17:25 mpaland
drwxrwxr-x 3 buechse buechse 4096 Mar 12 10:51 nasa
drwxr-xr-x 3 buechse root    4096 Apr 22 17:25 NordicSemiconductor
drwxrwxr-x 3 buechse buechse 4096 Apr  8 01:04 RIOT-OS

Adding the ID to the docker call will lead to an error message about permissions of create_user:

ocker run -it --rm --user $(id -u):$(id -g) docker.io/riot/riotbuild@sha256:028d9267e715e992d9b47bb8738685c6cc96b1a3bc3924489e7e543a333e8486 id
/run.sh: line 32: /usr/local/bin/create_user: Permission denied
uid=30037 gid=30037 groups=30037

The first reason for this is that the chmod settings in riotdocker-base/Dockerfile did not allow users from other groups (riotbuild != root) to execute the command.
The second reason is that the user group did not exist yet.
The third reason is that useradd created a system user, which is always in the root group AND it explicitly set the group to 0 = root.

Perhaps @kaspar030 remembers why, but I don't see an advantage here.

Testing

To test this locally, you have to build riotdocker-base first:

riotdocker/riotdocker-base$ docker build --pull -t riotdocker-base .

Then you have to build static-test-tools:

riotdocker/static-test-tools$ docker build --build-arg DOCKER_REGISTRY=docker.io/library -t static-test-tools .

Then you have to build riotbuild:

riotdocker/riotbuild$ docker build --build-arg DOCKER_REGISTRY=docker.io/library -t riotbuild .

Then you can get the Image ID:

riotdocker$ docker image list riotbuild
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
riotbuild    latest    f610ef8e4bbd   19 minutes ago   14.9GB

And build your favorite application:

RIOT$ BUILD_IN_DOCKER=1 DOCKER_IMAGE=f610ef8e4bbd BOARD=nrf52840dk make -C tests/sys/shell
make: Entering directory '/home/buechse/RIOTstuff/riot-vanillaice/RIOT/tests/sys/shell'
Launching build container using image "f610ef8e4bbd".
docker run --rm --tty --user $(id -u) --platform linux/amd64 -v '/home/buechse/RIOTstuff/riot-vanillaice/RIOT:/data/riotbuild/riotbase:delegated' -v '/home/buechse/.cargo/registry:/data/riotbuild/.cargo/registry:delegated' -v '/home/buechse/.cargo/git:/data/riotbuild/.cargo/git:delegated' -e 'TZ=Europe/Berlin' -e 'RIOTBASE=/data/riotbuild/riotbase' -e 'CCACHE_BASEDIR=/data/riotbuild/riotbase' -e 'BUILD_DIR=/data/riotbuild/riotbase/build' -e 'BUILD_IN_DOCKER=0' -e 'RIOTPROJECT=/data/riotbuild/riotbase' -e 'RIOTCPU=/data/riotbuild/riotbase/cpu' -e 'RIOTBOARD=/data/riotbuild/riotbase/boards' -e 'RIOTMAKE=/data/riotbuild/riotbase/makefiles' -v '/home/buechse/.gitcache:/data/riotbuild/gitcache:delegated' -e 'GIT_CACHE_DIR=/data/riotbuild/gitcache'    -e 'BOARD=nrf52840dk' -e 'DISABLE_MODULE=' -e 'DEFAULT_MODULE=test_utils_interactive_sync test_utils_print_stack_usage' -e 'FEATURES_REQUIRED=' -e 'FEATURES_BLACKLIST=' -e 'FEATURES_OPTIONAL=' -e 'USEMODULE=app_metadata ps shell_builtin_cmd_help_json shell_cmds_default ztimer_msec' -e 'USEPKG='  -w '/data/riotbuild/riotbase/tests/sys/shell/' 'f610ef8e4bbd' make 
Building application "tests_shell" for "nrf52840dk" with CPU "nrf52".

git-cache: cloning https://github.com/NordicSemiconductor/nrfx into cache...
Cloning into bare repository '/data/riotbuild/gitcache/github.com/NordicSemiconductor/nrfx.git'...
...

You should see that it clones the repos and the directories in your .gitcache folder belong to the root group:

buechse@skyleaf:~/RIOTstuff/riot-vanillaice/RIOT$ ls -l ~/.gitcache/github.com/
total 24
drwxr-xr-x 3 buechse root    4096 Apr 22 20:32 ARM-software
drwxrwxr-x 3 buechse buechse 4096 Mar 12 10:51 laurencelundblade
drwxr-xr-x 3 buechse root    4096 Apr 22 20:32 mpaland
drwxrwxr-x 3 buechse buechse 4096 Mar 12 10:51 nasa
drwxr-xr-x 3 buechse root    4096 Apr 22 20:32 NordicSemiconductor
drwxrwxr-x 3 buechse buechse 4096 Apr  8 01:04 RIOT-OS

Now delete the RIOT/build directory and the archives in .gitcache.

What we're really interested here is the docker call only, and we modify the --user command to --user $(id -u):$(id -g):

docker run --rm --tty --user $(id -u) --platform linux/amd64 -v '/home/buechse/RIOTstuff/riot-vanillaice/RIOT:/data/riotbuild/riotbase:delegated' -v '/home/buechse/.cargo/registry:/data/riotbuild/.cargo/registry:delegated' -v '/home/buechse/.cargo/git:/data/riotbuild/.cargo/git:delegated' -e 'TZ=Europe/Berlin' -e 'RIOTBASE=/data/riotbuild/riotbase' -e 'CCACHE_BASEDIR=/data/riotbuild/riotbase' -e 'BUILD_DIR=/data/riotbuild/riotbase/build' -e 'BUILD_IN_DOCKER=0' -e 'RIOTPROJECT=/data/riotbuild/riotbase' -e 'RIOTCPU=/data/riotbuild/riotbase/cpu' -e 'RIOTBOARD=/data/riotbuild/riotbase/boards' -e 'RIOTMAKE=/data/riotbuild/riotbase/makefiles' -v '/home/buechse/.gitcache:/data/riotbuild/gitcache:delegated' -e 'GIT_CACHE_DIR=/data/riotbuild/gitcache'    -e 'BOARD=nrf52840dk' -e 'DISABLE_MODULE=' -e 'DEFAULT_MODULE=test_utils_interactive_sync test_utils_print_stack_usage' -e 'FEATURES_REQUIRED=' -e 'FEATURES_BLACKLIST=' -e 'FEATURES_OPTIONAL=' -e 'USEMODULE=app_metadata ps shell_builtin_cmd_help_json shell_cmds_default ztimer_msec' -e 'USEPKG='  -w '/data/riotbuild/riotbase/tests/sys/shell/' 'f610ef8e4bbd' make 

You should see now that git-cache-rs re-fetches the archives and they belong to the correct group now:

buechse@skyleaf:~/RIOTstuff/riot-vanillaice/RIOT$ ls -l ~/.gitcache/github.com/
total 24
drwxr-xr-x 3 buechse buechse 4096 Apr 22 20:37 ARM-software
drwxrwxr-x 3 buechse buechse 4096 Mar 12 10:51 laurencelundblade
drwxr-xr-x 3 buechse buechse 4096 Apr 22 20:38 mpaland
drwxrwxr-x 3 buechse buechse 4096 Mar 12 10:51 nasa
drwxr-xr-x 3 buechse buechse 4096 Apr 22 20:38 NordicSemiconductor
drwxrwxr-x 3 buechse buechse 4096 Apr  8 01:04 RIOT-OS

[crasbe]

Instead of modifying the call, you can also set DOCKER_USER=$(id -u):$(id -g) like this:

BUILD_IN_DOCKER=1 DOCKER_IMAGE=f610ef8e4bbd DOCKER_USER=$(id -u):$(id -g) BOARD=nrf52840dk make -C tests/sys/shell

[mguetschow]

Instead of modifying the call, you can also set DOCKER_USER=$(id -u):$(id -g) like this:

BUILD_IN_DOCKER=1 DOCKER_IMAGE=f610ef8e4bbd DOCKER_USER=$(id -u):$(id -g) BOARD=nrf52840dk make -C tests/sys/shell

I guess this would need a matching PR in RIOT so that the group is automatically set when BUILD_IN_DOCKER=1?

[crasbe]

Instead of modifying the call, you can also set DOCKER_USER=$(id -u):$(id -g) like this:

BUILD_IN_DOCKER=1 DOCKER_IMAGE=f610ef8e4bbd DOCKER_USER=$(id -u):$(id -g) BOARD=nrf52840dk make -C tests/sys/shell

I guess this would need a matching PR in RIOT so that the group is automatically set when BUILD_IN_DOCKER=1?

Absolutely, but I come prepared RIOT-OS/RIOT#22212 :D

[mguetschow]

Great documentation, thanks a lot! Just some minor comments again.

[mguetschow]

Please squash!

[crasbe]

Thank you for the review :)