nginx Dynamic Module Packaging
This creates packages for a variety of dynamic modules for nginx using the official nginx pkg-oss tooling for building modules.
We currently support the following OSes:
- CentOS/RHEL 8 (x86_64)
- CentOS/RHEL 7 (x86_64)
This set of modules was originally based on the customised nginx build from https://github.com/jcu-eresearch/nginx-custom-build.
- Ability to manipulate request and response headers, including at low levels.
- Directory listings that are more visually appealing and customisable.
- Shibboleth authentication support for applications; effectively
- LDAP authentication with support for multiple servers.
- Updated for dynamic module compatibility.
- ngx_replace_filter - Streaming regular expression replacement in response bodies.
Run the following:
git clone https://github.com/jcu-eresearch/nginx-dynamic-modules.git cd nginx-dynamic-modules make
Enjoy your new RPMs, available in the
Push to repository hosting and update the shared-salt-states version details.
If you're not into Docker, then you can manually run
on your own EL machine, ensuring that you set up your build environment
first. You can follow the respective
Dockerfile in the
RUN commands. Beyond that, the build script is self-contained and
will automatically clone the latest patches from this GitHub repository if you
just run the script itself.
The configuration in
master builds packages for the latest stable
and mainline versions of nginx and will build for all OSes by default.
Note that versions may be slightly out-of-date as we update the code base.
It is also possible to select a specific version of nginx to build against by
setting the environment variable
_NGINX_VERSION (such as
export _NGINX_VERSION=1.99.9), which is used within the build script.
From Docker Compose, you can use the following:
docker-compose run -e _NGINX_VERSION=1.99.9 nginx-dynamic-modules-centos-8
_NGINX_MODULE_VERSION can also be set as well, representing the
version and release of the given module (such as
1.0-1). By convention,
this will follow the release version of packaged nginx versions but can be set
separately to handle situations where multiple releases of a module are
If you want to test the modules, you can do so by launching a Docker container with the appropriate OS, installing the built packages and testing. To do so:
make make test
The latter command will launch you into the Docker container. Now, inside this running container, call:
dnf install /app/build/centos-8/RPMS/x86_64/*.rpm
To run a basic smoke test with all current modules, call nginx like so:
nginx -t -c /app/configs/nginx-test.conf
Unless you're just performing basic tests without hitting nginx, you'll need
to map ports. The
Makefile is providing the
-p flag to
docker-compose which maps your host port
80 inside the
container. This menas you can launch nginx with the following command and
access it from your host on
localhost:8080 to perform further tests:
nginx -c /app/configs/nginx-test.conf
Note that nginx will daemonise by default.
Updating Docker images
To update the Docker images themselves to their latest versions, do the following:
Updating for future Nginx versions
Edit Nginx versions within
.travis.ymlto match the latest versions. In the build script, we use Nginx stable by default and for Travis, we test on CI for both stable and mainline.
Rebuild and test the results:
Many types of failures can occur at this point. Some of the most common are:
pkg-ossnot updated (yet) with files for this Nginx version: be patient and check back later.
- Specific module fails to build and/or is no longer compatible with this Nginx version: look for module updates or report issues to the respective maintainers.
pkg-ossbuild process has changed: review changes in
pkg-ossis no longer applying: create a new patch for forcing
pkg-ossto use HTTPS to download and build.