chore: refactor release workflow for modular distro and upstream builds
This commit is contained in:
186
docs/RELEASES.md
186
docs/RELEASES.md
@@ -1,83 +1,165 @@
|
||||
# Release Builds
|
||||
|
||||
The GitHub Actions workflow in `.github/workflows/release.yml` builds ready-to-use Linux dynamic module packages for x86_64 and ARM targets. Release binaries are built in Ubuntu Bionic 18.04 containers, giving the module artifacts a `ubuntu-bionic-glibc-2.27` libc baseline.
|
||||
The release workflow in `.github/workflows/release.yml` builds two artifact
|
||||
tiers:
|
||||
|
||||
## Manual Release Only
|
||||
- production-oriented `.deb` packages against Ubuntu and Debian Nginx source
|
||||
packages
|
||||
- generic `.tar.gz` packages against upstream `nginx.org` source versions
|
||||
|
||||
The workflow runs only through GitHub Actions `workflow_dispatch`. It does not run on pushes, pull requests, or tag pushes.
|
||||
## Why Distro Builds
|
||||
|
||||
Open the workflow in GitHub Actions and choose:
|
||||
Nginx dynamic modules are ABI-sensitive. `--with-compat` relaxes some module
|
||||
signature checks, but it does not make a module independent from the Nginx
|
||||
source package, distro patchset, compiler flags, configure arguments, or module
|
||||
ABI selected by a Debian or Ubuntu package maintainer.
|
||||
|
||||
- `nginx_versions`: space-separated versions, for example `1.24.0 1.26.3 1.28.0`
|
||||
- `target_arches`: space-separated targets, default `linux-x86_64 linux-arm64 linux-armv7`
|
||||
An upstream `nginx-1.24.0` build can load into an Ubuntu `nginx` package and
|
||||
still behave incorrectly at runtime after a package rebuild such as:
|
||||
|
||||
```text
|
||||
1.24.0-2ubuntu7.9 -> 1.24.0-2ubuntu7.10
|
||||
```
|
||||
|
||||
The safer production rule is:
|
||||
|
||||
```text
|
||||
build from the distro source package that produced the nginx binary you run
|
||||
```
|
||||
|
||||
## Manual Release
|
||||
|
||||
The workflow runs through GitHub Actions `workflow_dispatch`.
|
||||
|
||||
Inputs:
|
||||
|
||||
- `distro_targets`: space-separated container images, default
|
||||
`ubuntu:24.04 debian:12 debian:13`
|
||||
- `upstream_nginx_versions`: space-separated upstream source versions, default
|
||||
`1.22.1 1.24.0 1.26.3 1.28.0 1.30.0`
|
||||
- `target_arches`: `linux-x86_64`, `linux-arm64`, and `linux-armv7`
|
||||
- `version_bump`: `patch`, `minor`, or `major`
|
||||
- `push_image`: whether to push the multi-platform Docker image to GHCR
|
||||
- `push_image`: push the demo Docker image to GHCR
|
||||
|
||||
The workflow fetches existing `vMAJOR.MINOR.PATCH` tags, computes the next semantic version, creates an annotated tag, pushes it, and publishes the GitHub release.
|
||||
The workflow fetches existing `vMAJOR.MINOR.PATCH` tags, computes the next tag,
|
||||
builds all release artifacts, creates an annotated tag, pushes it, and publishes
|
||||
the GitHub release.
|
||||
|
||||
Examples:
|
||||
## Distro Build Strategy
|
||||
|
||||
For every distro and architecture, the workflow:
|
||||
|
||||
1. Starts the target distro container for the target CPU platform.
|
||||
2. Enables `deb-src` repositories.
|
||||
3. Installs the distro `nginx` package.
|
||||
4. Downloads the exact matching `apt source nginx` package version.
|
||||
5. Installs the Nginx source package build dependencies.
|
||||
6. Replays the packaged `nginx -V` configure arguments, rewriting distro module
|
||||
source paths into the downloaded source tree when needed.
|
||||
7. Adds this repository as a dynamic module and builds with the distro Nginx
|
||||
source package.
|
||||
8. Builds a `.deb` package and a manual `.tar.gz` package.
|
||||
9. Installs the `.deb` package in the same container.
|
||||
10. Validates the installed module with packaged `nginx -t` and live endpoint
|
||||
checks for `/monitor`, `/monitor/api`, `/monitor/health`,
|
||||
`/monitor/metrics`, and `/monitor/live`.
|
||||
|
||||
## nginx.org Build Strategy
|
||||
|
||||
For every requested upstream Nginx version and architecture, the workflow:
|
||||
|
||||
1. Starts the baseline `ubuntu:18.04` build container for the target CPU
|
||||
platform.
|
||||
2. Downloads the requested `https://nginx.org/download/nginx-<version>.tar.gz`
|
||||
source archive.
|
||||
3. Configures Nginx with the repository's compatibility build flags and this
|
||||
module as a dynamic module.
|
||||
4. Builds the Nginx binary and module.
|
||||
5. Validates the module with the just-built Nginx binary and live endpoint
|
||||
checks for `/monitor`, `/monitor/api`, `/monitor/health`,
|
||||
`/monitor/metrics`, and `/monitor/live`.
|
||||
6. Publishes a tarball plus sidecar compatibility metadata.
|
||||
|
||||
These artifacts preserve upstream version coverage for users who run Nginx
|
||||
built from nginx.org source. They are not the recommended artifact for Ubuntu or
|
||||
Debian packaged Nginx.
|
||||
|
||||
## Release Assets
|
||||
|
||||
Recommended production asset:
|
||||
|
||||
```text
|
||||
latest v1.2.3 + patch = v1.2.4
|
||||
latest v1.2.3 + minor = v1.3.0
|
||||
latest v1.2.3 + major = v2.0.0
|
||||
no existing tag + patch = v0.0.1
|
||||
libnginx-mod-http-monitoring_<module-version>-1+<distro>.nginx<source-version>_<deb-arch>.deb
|
||||
```
|
||||
|
||||
## Built Nginx Versions
|
||||
|
||||
By default, the workflow builds packages for:
|
||||
|
||||
- Nginx 1.22.1
|
||||
- Nginx 1.24.0
|
||||
- Nginx 1.26.3
|
||||
- Nginx 1.28.0
|
||||
- Nginx 1.30.0
|
||||
|
||||
## Built CPU Targets
|
||||
|
||||
By default, the workflow builds module packages for:
|
||||
|
||||
- `linux-x86_64`
|
||||
- `linux-arm64`
|
||||
- `linux-armv7`
|
||||
|
||||
Aliases such as `amd64`, `arm64`, `aarch64`, `armv7`, and `armhf` are normalized by the workflow.
|
||||
|
||||
Each release asset is named like:
|
||||
Manual fallback asset:
|
||||
|
||||
```text
|
||||
ngx_http_monitoring_module-v1.0.0-nginx-1.28.0-linux-x86_64.tar.gz
|
||||
ngx_http_monitoring_module-v1.0.0-nginx-1.28.0-linux-arm64.tar.gz
|
||||
ngx_http_monitoring_module-<tag>-<distro>-nginx-<source-version>-<deb-arch>.tar.gz
|
||||
```
|
||||
|
||||
Each package contains:
|
||||
Upstream nginx.org source asset:
|
||||
|
||||
```text
|
||||
ngx_http_monitoring_module-<tag>-nginxorg-<nginx-version>-<target-arch>.tar.gz
|
||||
```
|
||||
|
||||
Metadata assets:
|
||||
|
||||
- `*.compatibility.json`: compatibility metadata for one artifact target
|
||||
- `COMPATIBILITY-MATRIX.json`: combined release compatibility matrix
|
||||
- `SHA256SUMS.txt`: checksums for release assets
|
||||
|
||||
Each tarball contains:
|
||||
|
||||
- `modules/ngx_http_monitoring_module.so`
|
||||
- `INSTALL.md`
|
||||
- `COMPATIBILITY.json`
|
||||
- `METADATA.txt`
|
||||
- `NGINX-V.txt`
|
||||
- `SHA256SUMS`
|
||||
- example config
|
||||
- API/config/performance docs
|
||||
- example config and docs
|
||||
|
||||
## ABI Guard
|
||||
|
||||
The `.deb` package depends on the distro `nginx-abi-*` virtual package when the
|
||||
distribution exposes it and always pins the exact Nginx binary package version
|
||||
used for the build. If a later Nginx package update changes either the ABI or
|
||||
the package revision, apt cannot silently keep the old module installed against
|
||||
the new Nginx binary.
|
||||
|
||||
This is stricter than ABI-only packaging and can require rebuilding the module
|
||||
for routine distro Nginx updates. That is intentional: it favors explicit
|
||||
release artifacts over a module that loads and then fails at runtime.
|
||||
|
||||
## Tarball Warning
|
||||
|
||||
Tarballs are useful for inspection, non-dpkg deployments, upstream nginx.org
|
||||
source builds, and emergency manual installs. They do not give apt a dependency
|
||||
edge, so they cannot protect a host from an ABI-changing Nginx update.
|
||||
|
||||
Use a distro tarball only when all fields in `COMPATIBILITY.json` match the
|
||||
target host:
|
||||
|
||||
- OS ID and version
|
||||
- CPU architecture
|
||||
- Nginx binary package and version
|
||||
- Nginx source package and version
|
||||
- Nginx ABI, when present
|
||||
|
||||
Use an nginx.org tarball only when your target Nginx binary was built from the
|
||||
same upstream Nginx source version and materially compatible configure options.
|
||||
For Ubuntu/Debian packaged Nginx, use the `.deb` artifacts instead.
|
||||
|
||||
## Docker Image
|
||||
|
||||
When `push_image` is true, the workflow also builds and pushes:
|
||||
When `push_image` is true, the workflow also builds a self-contained demo image:
|
||||
|
||||
```text
|
||||
ghcr.io/<owner>/<repo>:<tag>
|
||||
ghcr.io/<owner>/<repo>:latest
|
||||
```
|
||||
|
||||
The image is built with Docker Buildx for the same normalized target platforms requested by `target_arches`.
|
||||
|
||||
The release image build passes:
|
||||
|
||||
```text
|
||||
BASE_IMAGE=ubuntu:18.04
|
||||
OPENSSL_RUNTIME_PACKAGE=libssl1.1
|
||||
```
|
||||
|
||||
## Compatibility Warning
|
||||
|
||||
Nginx dynamic modules are ABI-sensitive. The release packages are built with `--with-compat` on Ubuntu Bionic 18.04 against the Nginx version and CPU architecture in the filename. Use the matching Nginx version, CPU architecture, and a Linux/glibc runtime compatible with `ubuntu-bionic-glibc-2.27`. Rebuild locally when using a vendor Nginx package with materially different module ABI or hardening options.
|
||||
The image is not the recommended artifact for installing the module into
|
||||
distribution-packaged Nginx. It is a runnable demo image with Nginx and the
|
||||
module built together.
|
||||
|
||||
Reference in New Issue
Block a user