From b9bd0b09f9764e24e946a8ed7493763539702493 Mon Sep 17 00:00:00 2001 From: Brian Long Date: Tue, 8 Sep 2026 08:52:17 -0400 Subject: [PATCH] updated documentation --- README.md | 8 ++++++-- docs/build.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 docs/build.md diff --git a/README.md b/README.md index 2649f9d..8437c16 100644 --- a/README.md +++ b/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) \ No newline at end of file diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..bdcc7fd --- /dev/null +++ b/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.