Document restyrepo flavor (#305)

Signed-off-by: Evan Wies <evan@neomantra.net>

Author: neomantra

BUILDING.md

@@ -28,6 +28,7 @@ Dockerfiles are provided for the following base systems, selecting the Dockerfil
  * [Ubuntu Jammy](https://github.com/openresty/docker-openresty/blob/master/jammy/Dockerfile) (`jammy/Dockerfile`)
  * [Ubuntu Noble](https://github.com/openresty/docker-openresty/blob/master/noble/Dockerfile) (`noble/Dockerfile`)
  * [Ubuntu Resolute](https://github.com/openresty/docker-openresty/blob/master/resolute/Dockerfile) (`resolute/Dockerfile`)
+ * [RestyRepo](https://github.com/openresty/docker-openresty/blob/master/restyrepo/Dockerfile) (`restyrepo/Dockerfile`)
 
 We used to support more build flavors but have trimmed that down.  Older Dockerfiles are archived in the [`archive`](https://github.com/openresty/docker-openresty/tree/master/archive) folder.
 
@@ -38,11 +39,22 @@ The following are the available build-time options. They can be set using the `-
 docker build --build-arg RESTY_J=4 -f jammy/Dockerfile .
 ```
 
+The `restyrepo` flavor is different from the other source builds: it clones `RESTY_SOURCE_REPO`, checks out `RESTY_VERSION` as a branch or tag, runs the OpenResty source repository's `make` target to generate an OpenResty source tarball, and then builds from that tarball.  Use it when you need to test an OpenResty source branch or fork before it is published as a release tarball or upstream package:
+
+```
+docker build -t myopenresty-restyrepo -f restyrepo/Dockerfile .
+docker build -t myopenresty-restyrepo \
+  --build-arg RESTY_VERSION=v1.31.1.1 \
+  --build-arg RESTY_SOURCE_REPO=https://github.com/openresty/openresty.git \
+  -f restyrepo/Dockerfile .
+```
+
 | Key                                     | Default | Description |
 |:-----------------------------------------| :-----: |:----------- |
-| RESTY_IMAGE_BASE                        | "ubuntu" / "alpine" | The Debian or Alpine Docker image base to build `FROM`. |
-| RESTY_IMAGE_TAG                         | "noble" / "3.22.3" | The Debian or Alpine Docker image tag to build `FROM`. |
-| RESTY_VERSION                           | 1.27.1.2 | The version of OpenResty to use. |
+| RESTY_IMAGE_BASE                        | "ubuntu" / "alpine" / "debian" for `restyrepo` | The Ubuntu, Alpine, or Debian Docker image base to build `FROM`. |
+| RESTY_IMAGE_TAG                         | "noble" / "3.22.3" / "trixie-slim" for `restyrepo` | The Ubuntu, Alpine, or Debian Docker image tag to build `FROM`. |
+| RESTY_VERSION                           | 1.27.1.2 / v1.31.1.1 for `restyrepo` | The version of OpenResty to use. For `restyrepo`, this is the branch or tag checked out from `RESTY_SOURCE_REPO` and should include the full ref name, such as `v1.31.1.1`. |
+| RESTY_SOURCE_REPO                       | "https://github.com/openresty/openresty.git" | The OpenResty source repository to clone. Used by `restyrepo`. |
 | RESTY_LUAROCKS_VERSION                  | 3.13.0 | The version of LuaRocks to use. |
 | RESTY_OPENSSL_VERSION                   | 3.5.7 | The version of OpenSSL to use. |
 | RESTY_OPENSSL_PATCH_VERSION             | 3.5.5 | The version of OpenSSL to use when patching. |
@@ -238,4 +250,3 @@ End-To-End Tests
 ================
 
 The script [`./tests/e2e/run-test.sh`](./tests/e2e/run-test.sh) will stand up two local container registries and attempt to build all the images.
-

README.md

@@ -47,6 +47,7 @@ It is best practice to pin your images to an explicit image tag.  The [next sect
 | `openresty/openresty:1.29.2.4-1-bookworm-fat` | Built-from-upstream Debian Bookworm |
 | `openresty/openresty:1.29.2.4-1-alpine` | Built-from-source Alpine |
 | `openresty/openresty:1.29.2.4-1-alpine-apk` | Built-from-upstream Alpine |
+| `openresty/openresty:1.31.1.1-1-restyrepo` | Built-from-source OpenResty GitHub branch on Debian Trixie |
 | `openresty/openresty:1.31-alpine` | Latest Alpine image in the OpenResty 1.31 release series |
 
 These are examples of untagged image names, for reference:
@@ -57,6 +58,7 @@ These are examples of untagged image names, for reference:
 | `openresty/openresty:noble` | Latest Ubuntu Noble |
 | `openresty/openresty:jammy` | Latest Ubuntu Jammy |
 | `openresty/openresty:alpine` | Latest Alpine |
+| `openresty/openresty:restyrepo` | Latest OpenResty GitHub source branch build |
 
 There are also specific tags for [Debug](https://openresty.org/en/deb-packages.html#openresty-debug) and [Valgrind](https://openresty.org/en/deb-packages.html#openresty-valgrind) OpenResty variants:
 | Image | Description |
@@ -117,6 +119,7 @@ The following "flavors" are built from source and are intended for more advanced
 - [`alpine-slim`, (*alpine/Dockerfile*](https://github.com/openresty/docker-openresty/blob/master/alpine/Dockerfile), stripped Alpine image)
 - [`jammy`, (*jammy/Dockerfile*)](https://github.com/openresty/docker-openresty/blob/master/jammy/Dockerfile)
 - [`noble`, (*noble/Dockerfile*)](https://github.com/openresty/docker-openresty/blob/master/noble/Dockerfile)
+- [`restyrepo`, (*restyrepo/Dockerfile*)](https://github.com/openresty/docker-openresty/blob/master/restyrepo/Dockerfile)
 
 The `openresty/openresty:latest` tag points to the latest `bookworm` image.
 
@@ -130,6 +133,8 @@ OpenResty supports SSE 4.2 optimizations.  Starting with the `1.19.3.1` series,
 
 It is *highly recommended* that you use the upstream-based images for best support.  For best stability, pin your images to the full tag, for example `1.21.4.1-0-bionic`.
 
+The `restyrepo` flavor is a built-from-source image that clones the OpenResty GitHub repository, builds the OpenResty source tarball from the selected branch or tag, and then builds OpenResty from that generated tarball.  It uses Debian Trixie as its base image and is published for `amd64` and `arm64`.
+
 `-fat` images are ones that have [LuaRocks and OPM](#opm) installed in them. `-buildpack` images are based on [`buildpack-deps` images](https://hub.docker.com/_/buildpack-deps#what-is-buildpack-deps); they might be useful when more build scaffolding is required in your application.