updated documentation

README.md

@@ -54,7 +54,7 @@ A version labeled `latest` always exists.
 | `X.Y`    | The latest version within the specified minor version `X.Y`. |
 | `X.Y.Z`  | A specific version. |
 
-## Configuration
+## Runtime Configuration
 
 ### Environment Variables
 
@@ -91,7 +91,7 @@ curl --config ${CURL_CONFIG_DIR}/biz1.cfg ...
 curl --config ${CURL_CONFIG_DIR}/biz2.cfg ...
 ```
 
-## Usage
+## Recommended Uses
 
 This is expected to be extended or used directly for simple CI/CD runners.
 
@@ -101,6 +101,10 @@ You are welcome to copy the repository, but please open an issue first to avoid
 
 - [Open Issue](https://git.inteligr8.com/inteligr8/base-runner-image/issues)
 
+### Development
+
+- [Documentation](docs/build.md)
+
 ## References
 
 - [Debian Slim](https://github.com/linuxcontainers/debian-slim)

docs/build.md

@@ -0,0 +1,44 @@
+
+# Building
+
+Because this project consumes itself, when there was no `base-runner` image, there was no `containerd-runner` image, which makes this project unable to build using GitHub/Gitea workflows.  For that reason, there is a separately maintained set of build scripts under `cicd/`.  It serves as the original template for the Gitea workflow (`.gitea/workflows/`).
+
+## Environment Variables
+
+Whether executing the build via `cicd/` shell scripts or through Gitea workflows, there are several variables to consider.
+
+### Public
+
+These are the variables you are expected to tweak.
+
+| Name                         | Required | Default                | Purpose |
+| ---------------------------- |:--------:| ---------------------- | ------- |
+| `CONTAINERD_REGISTRY_HOST`   | No       | `docker.inteligr8.com` | The containerd registry to publish the built container image. |
+| `CONTAINERD_DEBUG`           | No       |                        | Set to any value to enable debug mode. |
+| `DEBIAN_VERSION`             | No       | `stable-20260824`      | The base version of Debian to use.  The `slim` variant is automatically selected. |
+
+### Private
+
+These are the variables you are not expected to tweak.
+
+| Name                         | Required | Default                | Purpose |
+| ---------------------------- |:--------:| ---------------------- | ------- |
+| `CONTAINERD_IMAGE_NAMESPACE` | No       | `inteligr8/`           | A prefix for the containerd image name. |
+| `CONTAINERD_IMAGE_NAME`      | No       | `base-runner`          | The containerd image name. |
+| `CONTAINERD_CMD`             | No       | `buildah`              | The CLI tool to use to build the containerd image name.  (e.g. `buildah`, `podman`, or `docker`) |
+| `CONTAINERD_BUILD_FORMAT`    | No       | `docker`               | The containerd build format for the CLI tool to use. (e.g. `oci` or `docker`) |
+| `SKOPEO_OPTS`                | No       |                        | Extra options to pass the `skopeo` CLI tool. |
+| `CONTAINERD_CMD_OPTS`        | No       |                        | Extra options to pass the containerd CLI build tool. |
+
+## Shell Execution
+
+The shell script will build the container and name it according to the variables above.  By default, the tag will be the short SHA of the Git commit `HEAD` (current).  The tag will have the format: `sha1234567`.  This means that if you want to rebuild without any source changes, but using an updated Debian version, you should create a new commit.  However, it is not actually necessary.  However, we are using a specific version for `DEBIAN_VERSION` for the traceability.  If we didn't care, we would just use `stable`.
+
+## GitHub/Gitea Workflow Execution
+
+The workflow definition maps some variables to Inteligr8 variables:
+
+`INTELIGR8_REGISTRY_HOST` => `CONTAINERD_REGISTRY_HOST`
+`INTELIGR8_IMAGE_NAMESPACE` => `CONTAINERD_IMAGE_NAMESPACE`
+
+Those values are expected to be the same across all projects.