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:

```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.