166 lines
5.6 KiB
Markdown
166 lines
5.6 KiB
Markdown
# Release Builds
|
|
|
|
The release workflow in `.github/workflows/release.yml` builds two artifact
|
|
tiers:
|
|
|
|
- production-oriented `.deb` packages against Ubuntu and Debian Nginx source
|
|
packages
|
|
- generic `.tar.gz` packages against upstream `nginx.org` source versions
|
|
|
|
## Why Distro Builds
|
|
|
|
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.
|
|
|
|
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`: push the demo Docker image to GHCR
|
|
|
|
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.
|
|
|
|
## 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
|
|
libnginx-mod-http-monitoring_<module-version>-1+<distro>.nginx<source-version>_<deb-arch>.deb
|
|
```
|
|
|
|
Manual fallback asset:
|
|
|
|
```text
|
|
ngx_http_monitoring_module-<tag>-<distro>-nginx-<source-version>-<deb-arch>.tar.gz
|
|
```
|
|
|
|
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 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 a self-contained demo image:
|
|
|
|
```text
|
|
ghcr.io/<owner>/<repo>:<tag>
|
|
ghcr.io/<owner>/<repo>:latest
|
|
```
|
|
|
|
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.
|