ngx_http_monitoring_module/docs/RELEASES.md

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:

1.24.0-2ubuntu7.9 -> 1.24.0-2ubuntu7.10

The safer production rule is:

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:

libnginx-mod-http-monitoring_<module-version>-1+<distro>.nginx<source-version>_<deb-arch>.deb

Manual fallback asset:

ngx_http_monitoring_module-<tag>-<distro>-nginx-<source-version>-<deb-arch>.tar.gz

Upstream nginx.org source asset:

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:

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.