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

README.md

@@ -1,2 +1,78 @@
 # riotbuild
 Dockerfiles for creating build environment for building RIOT projects.
+
+## Building your own images
+
+The RIOT build system containers are staggered. The foundation is set by
+`riotdocker-base`, which sets up the user inside of the container and
+sets traps for `SIGINT` and `SIGTERM` signals.
+
+You can build the image with the following command:
+
+```sh
+docker build --pull -t riotdocker-base ./riotdocker-base/
+```
+
+The second image, `static-test-tools`, builds upon `riotdocker-base` and
+contains all of the tools that are required to run the RIOT static tests.
+This image is also used by the `static-test` GitHub workflow in the main
+`RIOT` repository.
+
+You can build the image with the following command. Setting the
+`DOCKER_REGISTRY` argument ensures that the local copy of the container is used
+instead of the upstream version. You can omit this parameter if you haven't
+made any changes to `riotdocker-base`.
+
+***NOTE:*** If docker complains about not finding the image, you can try to
+set the `DOCKER_REGISTRY` argument to `localhost` instead.
+
+```sh
+docker build --build-arg DOCKER_REGISTRY=docker.io/library -t static-test-tools ./static-test-tools/
+```
+
+The third image, `riotbuild`, builds upon the `static-test-tools` and contains
+the full build environment required to build all platforms in `RIOT`.
+This container is rather big (>10GB) and takes a good while to build.
+
+You can run the following command to build it. Again, the `DOCKER_REGISTRY`
+command is optional if you haven't made any changes to `static-test-tools`.
+
+```sh
+docker build --build-arg DOCKER_REGISTRY=docker.io/library -t riotbuild ./riotbuild/
+```
+
+The fourth image, `murdock-worker`, builds upon `riotbuild` and contains
+everything that is used by the CI and can be built with the following command.
+Again, the `DOCKER_REGISTRY` command is optional if you haven't made any
+changes to `riotbuild`.
+
+```sh
+docker build --build-arg DOCKER_REGISTRY=docker.io/library -t murdock-worker ./murdock-worker/
+```
+
+## Testing your changes
+
+Before you can test your changes, you have to find out the Image ID of your
+freshly baked container. For example, if you want to search for `riotbuild`,
+you can have docker list all containers that match that name.
+
+```sh
+riotdocker$ docker image list riotbuild
+REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
+riotbuild    latest    f610ef8e4bbd   19 minutes ago   14.9GB
+```
+
+Depending on your changes and what you want to test, you can either start a
+shell inside of the container with the following command:
+
+```sh
+docker run --rm --user $(id -u):$(id -g) -it f610ef8e4bbd bash
+riotbuild@f610ef8e4bbd:~$
+```
+
+Or you can pass your image to the RIOT build system and build an application
+or test of your liking:
+
+```sh
+BUILD_IN_DOCKER=1 DOCKER_IMAGE=f610ef8e4bbd BOARD=nrf52840dk make -C tests/sys/shell
+```

murdock-worker/Dockerfile

@@ -1,4 +1,3 @@
-#
 # RIOT Murdock Dockerfile
 #
 # the resulting image is being used in RIOT's CI (Murdock)
@@ -29,10 +28,6 @@ RUN pip3 install hiredis
 # install testrunner dependencies
 RUN pip3 install click
 
-# get git-cache-rs binary
-COPY --from=ghcr.io/kaspar030/git-cache:0.1.5-jammy /git-cache /usr/bin/git-cache
-ENV GIT_CACHE_RS=/usr/bin/git-cache
-
 # install newer ccache package
 ARG CCACHE_TGZ=ccache-4.7.4-linux-x86_64.tar.xz
 COPY files/${CCACHE_TGZ}  /
@@ -44,6 +39,9 @@ COPY murdock_slave.sh /usr/bin/murdock_slave
 # create cache folder
 RUN mkdir -m777 /cache
 
+# remove old git-cache-rs files from before the directory structure changed
+RUN rm -rf /cache/.gitcache/*.git /cache/.gitcache/*.lock
+
 # set cache folder for Download Cache
 ENV DLCACHE_DIR=/cache/.dlcache
 

riotbuild/Dockerfile

@@ -1,24 +1,8 @@
+# `riotbuild` Dockerfile
 #
-# RIOT Dockerfile
-#
-# The resulting image will contain everything needed to build RIOT for all
-# supported platforms. This is the largest build image, it takes about 1.5 GB in
-# total.
-#
-# Setup:
-# 1. Install docker, add yourself to docker group, enable docker, relogin
-#
-# Use prebuilt image:
-# 1. Prebuilt image can be pulled from Docker Hub registry with:
-#      # docker pull riot/riotbuild
-#
-# Use own build image:
-# 1. Build own image based on latest base OS image (from the riotbuild directory):
-#      # docker build --pull -t riotbuild .
-#
-# Usage:
-# 1. cd to riot root
-# 2. # docker run -i -t -u $UID -v $(pwd):/data/riotbuild riotbuild ./dist/tools/compile_test/compile_test.py
+# This container includes the whole build toolchain required to build all
+# platforms supported by RIOT.
+
 ARG DOCKER_REGISTRY="docker.io/riot"
 FROM ${DOCKER_REGISTRY}/static-test-tools:latest
 
@@ -326,6 +310,11 @@ RUN \
 # get laze binary
 COPY --from=kaspar030/laze:0.1.20-jammy /laze /usr/bin/laze
 
+# get git-cache-rs binary and set the environment variable for
+# the RIOT package subsystem
+COPY --from=ghcr.io/kaspar030/git-cache:0.2.8-jammy /git-cache /usr/bin/git-cache
+ENV GIT_CACHE_RS=/usr/bin/git-cache
+
 # get Dockerfile version from build args
 ARG RIOTBUILD_VERSION=unknown
 ENV RIOTBUILD_VERSION=$RIOTBUILD_VERSION

riotdocker-base/Dockerfile

@@ -1,3 +1,8 @@
+# `riotdocker-base` Dockerfile
+#
+# This container sets the foundation for all subsequent containers and
+# initializes the user environment.
+
 FROM ubuntu:jammy
 
 LABEL maintainer="Kaspar Schleiser <kaspar@riot-os.org>"
@@ -20,7 +25,7 @@ RUN \
 COPY create_user.c /tmp/create_user.c
 RUN gcc -DHOMEDIR=\"/data/riotbuild\" -DUSERNAME=\"riotbuild\" /tmp/create_user.c -o /usr/local/bin/create_user \
     && chown root:root /usr/local/bin/create_user \
-    && chmod u=rws,g=x,o=- /usr/local/bin/create_user \
+    && chmod u=rws,g=x,o=x /usr/local/bin/create_user \
     && rm /tmp/create_user.c
 
 # Create working directory for mounting the RIOT sources

riotdocker-base/create_user.c

@@ -1,3 +1,21 @@
+/*
+ * Docker runs containers with local root privileges. That means, that all
+ * accesses to shared directories and files will be performed as root, leading
+ * to possibly inaccessible files and files with the wrong owner (root instead
+ * of the local user).
+ *
+ * Docker allows to set the user ID and user group with the `--user` argument
+ * when running a Docker container. That argument however only sets the
+ * respective IDs and not the user- and groupname.
+ *
+ * Therefore, this file is compiled as a binary that is executed by `run.sh`
+ * every time a Docker container (or child of the `riotdocker-base` container)
+ * is executed. It sets the home directory, user- and groupnames and UID:GID.
+ *
+ * The username and groupname is set to `riotbuild`, but they are just aliases,
+ * as the underlying rights mechanism only checks the IDs and not the names.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/types.h>
@@ -12,9 +30,16 @@ int main(int argc, char *argv[])
     setuid(0);
 
     unsigned uid = atoi(argv[1]);
+    unsigned gid = atoi(argv[2]);
     char buf[128];
 
-    sprintf(buf, "/usr/sbin/useradd -u %u -d %s -r -g 0 -N %s", uid, HOMEDIR, USERNAME);
+    /* create the usergroup */
+    sprintf(buf, "/usr/sbin/groupadd -g %u %s", gid, USERNAME);
+    system(buf);
+
+    /* set the UID, Home Directory, User Group */
+    sprintf(buf, "/usr/sbin/useradd -u %u -d %s -g %u %s", uid, HOMEDIR, gid, USERNAME);
     system(buf);
+
     return 0;
 }

riotdocker-base/run.sh

@@ -26,10 +26,20 @@ runcommand() {
     return "$retval"
 }
 
-# create passwd entry for current uid, fix HOME variable
-# only execute, if the current uid does not exist.
-if ! id $(id -u) >/dev/null 2>/dev/null; then
-    create_user $(id -u)
+# Create passwd entry with the UID and GID of the user running the
+# `riotdocker-base` container and any containers derived from it.
+# It also sets the HOME variable.
+# Only execute, if the current UID does not exist.
+if ! id "$(id -u)" >/dev/null 2>/dev/null; then
+    if [ "$(id -u)" -ne 0 ] && [ "$(id -g)" -eq 0 ]; then
+        # Fallback to UID:UID if the container is run without setting a GID
+	echo -e "\e[33mWarning: The Docker User ID is $(id -u), but the" \
+		"Group ID is 0 (root), update your RIOT repository or check" \
+		"the Docker call!\e[0m"
+        create_user "$(id -u)" "$(id -u)"
+    else
+        create_user "$(id -u)" "$(id -g)"
+    fi
 fi
 export HOME=/data/riotbuild
 

static-test-tools/Dockerfile

@@ -1,3 +1,8 @@
+# `static-test-tools` Dockerfile
+#
+# This container has all the dependencies required to execute the static tests
+# for the RIOT sources.
+
 ARG DOCKER_REGISTRY="docker.io/riot"
 FROM ${DOCKER_REGISTRY}/riotdocker-base:latest