From adf47d94a57dd4b5f73ef8da2fc1f1ae7aab9606 Mon Sep 17 00:00:00 2001
From: Chris Evich <cevich@redhat.com>
Date: Wed, 8 May 2024 11:01:46 -0400
Subject: [PATCH] Update setup docs

* Simplify the overview, include minimum podman version.
* Clarify linger setup
* Overhaul user-namespace setup section
* Rename "registration" to "activation" (gitlab 16+)

Signed-off-by: Chris Evich <cevich@redhat.com>
---
 README.md | 79 ++++++++++++++++++++-----------------------------------
 1 file changed, 29 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index 69b47d0..7bebede 100644
--- a/README.md
+++ b/README.md
@@ -36,79 +36,55 @@ container. While it's possible to use the container with your own command-line,
 it's highly recommended to base them off of one of the labels. See the examples
 below for more information.
 
-**_Note:_** Some older versions of podman don't support the `container runlabel`
-sub-command. If this is the case, you may simulate it with the following,
-substituting `<label>` with one of the predefined values (i.e. `register`,
-`setupconfig`, etc.):
-
-```bash
-$ IMAGE="registry.gitlab.com/qontainers/pipglr:latest"
-$ eval $(podman inspect --format=json $IMAGE | jq -r .[].Labels.<label>)
-```
+*_Only podman versions 4.8.x and later are supported by pipglr._*
 
 #### Persistent Containers (step 1)
 
 By default on many distributions, regular users aren't permitted to leave
 background processes running after they log out. Since this is likely desired
 for running the pipglr container long-term, `systemd` needs to be configured to
-override this policy. For this, you (`$USER`) will need root access on the
-system.
+override this policy.  Doing so requires root or `sudo` access on the
+system.  Assuming the user `johndoe` will be executing the pipglr container,
+linger may be enabled (as the admin user or root) with a command like:
 
 ```bash
-$ sudo loginctl enable-linger $USER
+$ sudo loginctl enable-linger `johndoe`
 ```
 
-Side-effect: This will allow your user to persist other user-level systemd
-services as well. For example `podman.socket` is handy to enable for
-`podman remote` access. You could also
+Side-effect: This will allow the user (`johndoe` for example) to persist
+other user-level systemd services as well. For example `podman.socket` is
+handy to enable for `podman remote` access. You could also
 [setup quadlet](https://www.redhat.com/sysadmin/quadlet-podman) or a systemd
 unit so pipglr starts up on system boot.
 
-#### Expanded User-Namespace (step 2) **_This is probably important_**
+#### Expanded Host-system User-Namespace (step 2)
 
-As an added protection/safety measure, pipglr excludes three UID/GIDs from being
-used by job-level containers. One for `root`, another for `runner` and a third
-for `podman`. However, some container images you may want to use for jobs
-(mainly Debian/Ubuntu), assign one/more essential users a high UID/GID value
-(like `65535`).
+**_This is really important and frequently the cause of pipglr issues_**
 
-At the same time, most distributions also set `65536` as the default maximum
-number (including ID `0`) of IDs to allocate for user-namespaces (via
-`/etc/login.defs`). This creates a problem you won't realize until the runner
-actually picks up a job. The main symptom of this issue will be messages in
-the pipglr containers log, similar to (abbreviated):
-
-```text
-...cut...
-running `/usr/bin/newuidmap ...cut...`: newuidmap: write to uid_map failed: Operation not permitted
-Error: cannot set up namespace using "/usr/bin/newuidmap": exit status 1
-...cut...
-```
-
-or
-
-```text
-E: setgroups 65534 failed - setgroups (22: Invalid argument)
-```
-
-**_The good news is, working around this is relatively simple:_**
-
-As root, edit the two files `/etc/subuid` and `/etc/subgid` to expand the by 3
-IDs. For example assuming a user running the pipglr container is called
-`johndoe`, the contents of these files should be edited to allocate `65539` IDs
-like:
+On the host, as root, edit the two files `/etc/subuid` and `/etc/subgid` to
+expand the pipglr user's ID allocation by 3.  For example if the host user
+running the pipglr container is named `johndoe`, this entry in the files should
+be edited like:
 
 `johndoe:<some number>:65539`
 
-Where `<some number>` was set by your OS when the `johndoe` user was created
-(you can ignore this). Only the last number needs to be increased. This change
-will be effective on next login, or immediately by running:
+Where `<some number>` was set by the OS when the `johndoe` user was created
+(you can ignore this).  Only the last number needs to be increased by three.
+This change will be effective on the user's next login, or immediately
+by running (as the host pipglr user):
 
 `podman system migrate`
 
 _Note:_ This will stop any currently running containers.
 
-#### Runner Registration (step 3)
+_Details:_ As an added protection/safety measure, pipglr excludes three UID/GIDs
+from being used by job-level (nested) containers. One for `root`, another for
+`runner` and a third for `podman`.  This necessitates expanding the number of
+available UIDs/GIDs from the host machine, to the pipglr container.  This way,
+the full set of 65535 UIDs/GIDs may be utilized by job-level (nested)
+sub-containers.
+
+#### Runner Activation/Registration (step 3)
 
 All runners must be connected to a project or group runner configuration on your
 gitlab instance (or `gitlab.com`). This is done using a special registration
@@ -257,6 +233,9 @@ Several build arguments are available to control the output image:
   containers running in `--privileged` mode. This will affect the ability to
   build container images in CI jobs using tools like podman or buildah.
 
+Additional build-args are available as well.  See the `Containerfile` comments
+for more details.
+
 ### Environment Variables
 
 Nearly every option to every gitlab-runner sub-command may be specified via