From 6bd37a2ed41ef9c0e08cc24f9d0157ffccc4d433 Mon Sep 17 00:00:00 2001
From: rina <k@rina.fyi>
Date: Wed, 18 Dec 2024 12:09:28 +1000
Subject: [PATCH] document docker-helper variables, add DOCKER_TAG

in particular, using docker instead of podman
---
 src/test/make/docker-helper.sh | 10 +++++++--
 src/test/readme.md             | 40 ++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/src/test/make/docker-helper.sh b/src/test/make/docker-helper.sh
index ed1ce1925..56e594eca 100755
--- a/src/test/make/docker-helper.sh
+++ b/src/test/make/docker-helper.sh
@@ -31,8 +31,13 @@ fi
 # unique names depend only on DOCKER_FLAKE, allowing them to be computed without nix.
 commit=$(printf '%s' "$DOCKER_FLAKE" | grep --only-matching -E '[0-9a-fA-F]{40}' | head -c8)
 flake_hash=flake-$(printf '%s' "$DOCKER_FLAKE" | md5sum | cut -d' ' -f1 | head -c4)
-unique_image="$DOCKER_IMAGE:$flake_hash-$commit"
-unique_container=container-$flake_hash-$commit
+
+if [[ -z "${DOCKER_TAG:-}" ]]; then
+  DOCKER_TAG="$flake_hash-$commit"
+fi
+
+unique_image="$DOCKER_IMAGE:$DOCKER_TAG"
+unique_container="container-$DOCKER_TAG"
 
 # this allows the env subcommand to output syntax compatible with multiple shells
 shell=$(basename $SHELL)
@@ -124,6 +129,7 @@ elif [[ "$1" == env ]]; then
   echoexport USE_DOCKER "1"
   echoexport DOCKER_FLAKE "$DOCKER_FLAKE"
   echoexport DOCKER_IMAGE "$DOCKER_IMAGE"
+  echoexport DOCKER_TAG "$DOCKER_TAG"
   echoexport DOCKER_PLATFORM "$DOCKER_PLATFORM"
   echoexport DOCKER "$DOCKER"
   echoexport DOCKER_USER "$DOCKER_USER"
diff --git a/src/test/readme.md b/src/test/readme.md
index 6b111d927..05d45bbed 100644
--- a/src/test/readme.md
+++ b/src/test/readme.md
@@ -66,6 +66,9 @@ the lifted test cases.
    This also adds a `docker-helper.sh` alias into the current shell session.
    To de-activate this environment, use the same command with `--unset` after "env".
 
+   The environment can be configured by setting environment variables before running the "env"
+   subcommand. See the "Customising Docker behaviour" subsection below.
+
 3. After setting up the environment, to pull the Docker image [from GHCR](https://github.com/UQ-PAC/BASIL/pkgs/container/basil-tools-docker), run:
    ```bash
    docker-helper.sh pull
@@ -92,6 +95,43 @@ the lifted test cases.
 
 6. The last two steps will have to be repeated if the Docker image changes.
 
+#### Customising Docker options
+
+Before running `docker-helper.sh env`, several environment variables can be set
+to influence its behaviour:
+
+- `DOCKER` is the name of the Docker program (default: podman).
+- `DOCKER_USER` is the name/ID of a user _inside_ the container, to be used
+  to run the lifter commands (default: root).
+- `DOCKER_FLAKE` is a Nix flake reference to a streamed Docker image builder (default: read from docker-flake.txt).
+- `DOCKER_IMAGE` is name of the image, including the registry URL (default: ghcr.io/uq-pac/basil-tools-docker)
+- `DOCKER_TAG` is the tag of the image (default: hashed from DOCKER_FLAKE).
+
+The values of these variables will be printed by `eval $(docker-helper.sh env)`.
+Note that if you want to change these variables, you should first deactivate the environment,
+make the changes, then re-activate.
+This will make sure dependent variables are updated correctly.
+```bash
+eval $(docker-helper.sh env --unset)
+# set variables here
+export DOCKER=docker
+# ... etc
+eval $(docker-helper.sh env)
+```
+
+To use traditional `docker` instead of `podman`:
+- By default, the container runner is `podman`. Podman is
+  an implementation of the Docker protocol which is rootless by default.
+  Containers are run as your usual user, without needing a separate system
+  service. Change `DOCKER` to "docker" to use the original Docker program.
+- If you are using the traditional `docker` program in a _non_ rootless setup,
+  you will have to set `DOCKER_USER` to `UID:GID` where UID/GID are is the user/group ID of
+  your _outside_ user (obtain with `id -u` and `id -g`).
+  This will make sure the produced files are editable by your ordinary user.
+
+To use a custom Docker image, change `DOCKER_IMAGE` and `DOCKER_TAG` as necessary.
+Note that changing these will likely break the "build" subcommand.
+
 ### Building with Docker
 
 Now, running make commands should use compilers from Docker.