Skip to content

DEVELOPMENT.md

Overview

The complexity of building and testing the native module stems from navigating the overlapping matrix of Nginx version lines, Open Source (nginx.org) vs Commercial (nginx.com Plus) variants, and our actively supported host operating systems.

For local development loop agility, engineering efforts focus on compiling binaries and executing integration testing validation suites against a singular, targeted version-and-OS combination.

Build a Specific Nginx Version and Architecture

To compile a native shared object (.so) for local feature validation or hot patching, pass the explicit target version to the build framework:

shell make -e NGX_VERSION=1.31.2 glibc

The builder outputs compiled module layers into structured workspace directory targets: * GLIBC Subsystems: out/release-1.31.2/glibc/[build-name]/ngx_sigsci_module.so (Compatible with Ubuntu, Debian, RHEL/CentOS, and Amazon Linux). * MUSL Subsystems: out/release-1.31.2/musl/[build-name]/ngx_sigsci_module.so (Compatible with native Alpine environments and Kubernetes Ingress Controller setups).

Build Local Packages for a Targeted Test Release

The central Go utility make_pkgs.go manages package compilation and wrapping via NFPM automatically behind the scenes. To trigger package construction locally across all engine profiles parsed in the configuration code, run:

make pkgs

NFPM evaluates the active lines and distributes output packages using updated naming conventions: * Nginx.org Mainline Releases: out/release-<VERSION>/glibc/nginx-module-fastly-nxm*.{apk|deb|rpm} * Nginx.org Stable Releases: out/release-<VERSION>/glibc/nginx-module-fastly-nxs*.{apk|deb|rpm} * Nginx.com Plus Commercial Releases: out/release-<VERSION>/glibc/nginx-module-fastly-nxp*.{apk|deb|rpm} * Distribution-Native Ensembles: out/dist/<os>/<code>/nginx-module-fastly-nxd*.{apk|deb|rpm}

Executing Local Functional & Installation Testing

A local artifact package repository and metadata index are automatically initialized inside out/dist/<os>/<code>/ whenever local package loops are built.

1. Validate Installation & Package Dependency Trees

To verify that your newly compiled NFPM package structures install and bind correctly against native distribution package managers (apt, yum, or apk), use the target installer harness:

make pkgs test-install

2. Running Localized Multi-Target Tests (run_tests.sh)

Whenever you execute compilation sequences locally via make_pkgs.go, the Go utility automatically generates a convenience script named run_tests.sh at the root of the workspace directory.

This shell script maps out individual, line-by-line sequential test targets calculated from your active shouldBuild gates and dists array filters, standardizing package indexing before firing isolated test configurations.

To execute the full matrix of targeted tests sequentially on a development machine:

# Audit the generated test matrix paths
cat run_tests.sh

# Make executable and run the sequential suite
chmod +x run_tests.sh
./run_tests.sh

A generated run_tests.sh file maps environment scopes explicitly:

#!/usr/bin/env bash

make repo

(export OS_VERSION="3.21" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh alpine)
(export OS_VERSION="3.21" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh alpine)
(export OS_VERSION="3.22" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh alpine)
(export OS_VERSION="3.22" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh alpine)
(export OS_VERSION="3.23" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh alpine)
(export OS_VERSION="3.23" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh alpine)
(export OS_VERSION="2" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh amazon2)
(export OS_VERSION="2" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh amazon2)
(export OS_VERSION="2023" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh amazon2023)
(export OS_VERSION="2023" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh amazon2023)
(export OS_VERSION="el10" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh centos)
(export OS_VERSION="el10" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh centos)
(export OS_VERSION="el8" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh centos)
(export OS_VERSION="el8" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh centos)
(export OS_VERSION="el9" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh centos)
(export OS_VERSION="el9" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh centos)
(export OS_VERSION="bookworm" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh debian)
(export OS_VERSION="bookworm" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh debian)
(export OS_VERSION="bullseye" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh debian)
(export OS_VERSION="bullseye" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh debian)
(export OS_VERSION="trixie" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh debian)
(export OS_VERSION="trixie" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh debian)
(export OS_VERSION="22.04" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh ubuntu)
(export OS_VERSION="22.04" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh ubuntu)
(export OS_VERSION="24.04" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh ubuntu)
(export OS_VERSION="24.04" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh ubuntu)
(export OS_VERSION="26.04" BRANCH="mainline" NGINX_VERSION="1.31.2"; ./install_testing/test.sh ubuntu)
(export OS_VERSION="26.04" BRANCH="stable" NGINX_VERSION="1.30.3"; ./install_testing/test.sh ubuntu)

Build and Test Module for Nginx Plus

Compiling for Nginx Plus uses the same underlying Go toolchain pathways as open-source variants. However, testing commercial runs locally requires valid developer entitlements, client repository keys, and explicit certificates.

  1. Obtain a current developer workspace key package from Release Engineering.
  2. Drop your assigned credentials into the proper local certification directories:
    • Certificate destination: certify/nginx-repo.crt
    • Private Key destination: certify/nginx-repo.key
  3. Execute the matching local target string directly: shell make test-nxp-1.29.8

Review runtime execution parameters using the generated test log streams: * agent.log — Core agent registration and module protocol tracking. * nxp_error.log / nxp_access.log — Dedicated commercial Nginx Plus environment logging logs.

Upstream Tuning for New Releases

To guarantee total structural ABI binary compatibility, our compilation parameters must mirror the precise configuration layout of the target distribution's upstream engine.

  1. To audit flag constraints on a newly launched platform variant, spin up an interactive shell inside a stock base container and query the engine directly: shell docker run -it --rm ubuntu:noble nginx -V
  2. Extract the returned configure arguments string (inspecting for parameters like --with-compat, --with-threads, or hardcoded compiler string definitions).
  3. If structural variances are discovered, navigate to make_pkgs.go and locate the inline template blocks (buildTmpl). Modify the custom compilation arguments under the specific GLIBC or MUSL definition block to maintain synchronization.

References