feat: update nginx plus image builds to use nginx plus base images #449

dekobon · 2025-09-04T20:23:35Z

This change migrates to using the official NGINX Plus Docker images as base images.

Proposed changes

This pull request refactors and streamlines the Docker build process for both OSS and Plus variants of the NGINX S3 Gateway, improves environment variable handling, and enhances script modularity and maintainability. The changes focus on updating base images, simplifying installation and configuration steps, and improving the way environment variables are set and output. Below are the most important changes grouped by theme.

Dockerfile and Build Process Updates:

The Dockerfile.oss and Dockerfile.plus now use newer, more specialized NGINX base images, removing manual installation and configuration steps for modules and dependencies. This simplifies maintenance and ensures up-to-date security and compatibility. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-27159a855b1005b6238ec88d1102a64dd367c95a56a5dd79e8fef77822da946cL1-R1), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L1-R4))
The build process for the Plus variant has been refactored to use multi-stage builds, pulling required modules and libraries from a dedicated image and removing manual GPG key and license handling. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L1-R4), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L29-R44), [[3]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-bd173a4997c5890e5dac73e8a5312c3898d8fa58212035ed6fa3ea9b59ac0b2dL1-L104))
Package installation and cleanup steps in both Dockerfiles are streamlined, reducing image size and improving reliability. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-27159a855b1005b6238ec88d1102a64dd367c95a56a5dd79e8fef77822da946cR26-R42), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L29-R44), [[3]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-f68090bbfca14523ecccbcb26652c72c11ee1dbfdd6484b1ee2282a421c32097R8-R13))

Entrypoint Script Refactoring:

The monolithic common/docker-entrypoint.sh is split into modular scripts in common/docker-entrypoint.d/, improving maintainability and clarity. The environment variable setting logic is now handled in 01-set-defaults.envsh, and output of settings is moved to 99-output-settings.sh. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L1-R1), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L18-R18), [[3]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L34-R32), [[4]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L49-R73), [[5]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L86-R89), [[6]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L98-L136), [[7]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-488413bc701efdbc3df0aa211eacf5a39ca2ac8754889b69a6d0c05c3807e480R1-R36))
Shell compatibility is improved by switching from Bash to POSIX-compliant sh in entrypoint scripts. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L1-R1), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L18-R18))

Environment Variable Handling Improvements:

Environment variable parsing and defaulting logic is made more robust and consistent, using POSIX-compatible syntax and explicit checks for unset or empty variables. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L34-R32), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L49-R73), [[3]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L86-R89), [[4]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-487a3dbccd6da77b63078fcb3ad21bf549b7c6ec3ea10204c0b7624f1f26e872L98-L136))
Output of environment settings is separated into its own script (99-output-settings.sh), making startup logs clearer and the code easier to maintain. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-72b42db75a6916ae79a70e72a888969f2fbc322a1c32836cb64aabed185277caL133-L150), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-488413bc701efdbc3df0aa211eacf5a39ca2ac8754889b69a6d0c05c3807e480R1-R36))

Module Installation and Configuration:

Installation of NGINX modules (njs, xslt) is now handled via package managers or prebuilt images, removing manual version management and reducing build complexity. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-27159a855b1005b6238ec88d1102a64dd367c95a56a5dd79e8fef77822da946cR26-R42), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L1-R4), [[3]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L29-R44))
The Plus variant now inherits supporting libraries and modules from a dedicated image, ensuring all required functionality is present. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L1-R4), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L29-R44))

Miscellaneous Improvements:

Unused or redundant code and comments are removed, and file copying instructions in Dockerfiles are updated for clarity and consistency. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-27159a855b1005b6238ec88d1102a64dd367c95a56a5dd79e8fef77822da946cR26-R42), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L29-R44))
The build scripts and Dockerfiles are updated to ensure proper file permissions and ownership for cache directories and entrypoint scripts. ([[1]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-27159a855b1005b6238ec88d1102a64dd367c95a56a5dd79e8fef77822da946cR26-R42), [[2]](https://github.com/nginx/nginx-s3-gateway/pull/449/files#diff-29fd428d7aaa2e0caf6fd3520ae4c3af291a97d312f2279cbe3d439aef7dad55L29-R44))

These changes collectively make the build process more reliable, secure, and maintainable, and improve the clarity and modularity of the startup configuration logic.

This pull request refactors the Dockerfiles and entrypoint scripts for both the OSS and Plus NGINX S3 Gateway images. The main goals are to modernize the build process, improve maintainability, and enhance compatibility with best practices for multi-stage Docker builds. The changes include switching to official NGINX Plus base images, restructuring build steps, simplifying environment variable handling, and improving script robustness.

Dockerfile and Build Process Refactoring:

Switched the OSS (Dockerfile.oss) and Plus (Dockerfile.plus) images to use official NGINX and NGINX Plus base images, removing custom build logic and simplifying module installation. The Plus image now uses a multi-stage build to avoid embedding sensitive license files in the final image. [1] [2] [3]
Removed the now-obsolete Dockerfile.buildkit.plus as its logic is replaced by the new multi-stage approach.
Updated the NJS module installation and related environment variables to match the new base images and simplify version management. [1] [2]

Entrypoint Script Improvements:

Switched to using the inherited container's main entrypoint script: docker-entrypoint.sh
Improved logic for setting and exporting environment variables, especially for DNS resolvers and CORS-related settings, making the script more robust and predictable. [1] [2] [3]

Other Notable Changes:

Removed verbose S3 backend environment logging from the entrypoint for cleaner container startup output.
Improved file permissions and copying logic for configuration and entrypoint scripts, ensuring proper initialization and execution in the container. [1] [2]

These changes collectively modernize the build and runtime environment for the NGINX S3 Gateway images, making them easier to maintain and more secure.

Base Image and Versioning Updates:

Dockerfile.plus now uses the official NGINX Plus base image from the private registry instead of the public Debian image, ensuring compliance and improved support. [1] [2]
Environment variables for NGINX and module versions have been updated to use explicit Plus and OSS versions, and package release variables have been clarified for njs and xslt modules. [1] [2]
The installation logic for NGINX Plus modules now uses the correct version variables, ensuring that the built images contain the intended module versions. [1] [2]

Entrypoint and Startup Script Cleanup:

Legacy entrypoint scripts 10-listen-on-ipv6-by-default.sh and 20-envsubst-on-templates.sh have been removed from plus/docker-entrypoint.d, simplifying container startup and reducing maintenance overhead. [1] [2]
Dockerfile instructions for copying entrypoint scripts have been adjusted, removing redundant or unnecessary script copies to the image. [1] [2]

Documentation Improvements:

The build instructions in docs/getting_started.md have been updated to clarify the process for building the NGINX Plus image, including the need to set up access to the official Plus Docker image repository and the steps for handling repository keys.

Checklist

Before creating a pull request (PR), run through this checklist and mark each as complete:

I have read the contributing guidelines.
I have signed the F5 Contributor License Agreement (CLA).
The PR title follows the Conventional Commits specification.
If applicable, I have added tests that prove my fix is effective or that my feature works.
If applicable, I have checked that any relevant tests pass after adding my changes.
I have updated any relevant documentation (e.g. README.md).

Copilot

Pull Request Overview

This PR migrates NGINX Plus container builds from using a public Debian base image to the official NGINX Plus Docker base image, improving compliance and support. It also removes legacy entrypoint scripts that are now redundant with the official base image.

Updates both Dockerfiles to use the official NGINX Plus base image from the private registry
Removes legacy entrypoint scripts (10-listen-on-ipv6-by-default.sh and 20-envsubst-on-templates.sh)
Updates environment variables and module installation logic to use explicit Plus and OSS versions

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Dockerfile.plus	Updates base image to official NGINX Plus and removes redundant user creation and container configuration
Dockerfile.buildkit.plus	Same base image and configuration updates as standard Dockerfile
plus/docker-entrypoint.d/10-listen-on-ipv6-by-default.sh	Removes legacy IPv6 configuration script
plus/docker-entrypoint.d/20-envsubst-on-templates.sh	Removes legacy template substitution script
docs/getting_started.md	Updates build instructions to clarify NGINX Plus image repository setup requirements

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Dockerfile.plus

Dockerfile.buildkit.plus

4141done

Changes look good to me - the copilot suggestion around chmod commands on directories that are not explicitly copied in any long are worth looking at but perhaps we are not just dealing with those directories as they are inherited from the new base image?

oxpa · 2025-09-05T19:35:37Z

nginx plus has entrypoint scripts copied from docker-nginx of OSS images. Are we sure we want to do any changes to entrypoint.sh?
Is it important to have specific njs version? nginx-plus has /modules from where you can copy files into your image.

dekobon · 2025-09-09T00:56:41Z

@oxpa I've incorporated your suggestions and redone this PR. Thank you for them. It helped me clarify what was needed.

dekobon · 2025-09-09T00:57:12Z

Dockerfile.oss

@@ -1,9 +1,5 @@
 FROM nginx:1.29.0@sha256:f5c017fb33c6db484545793ffb67db51cdd7daebee472104612f73a85063f889

-# NJS env vars


We no longer hard-code NJS versions.

dekobon · 2025-09-09T00:58:49Z

Dockerfile.oss

-COPY oss/etc /etc
+COPY oss/etc/nginx /etc/nginx
 COPY common/etc /etc
-COPY common/docker-entrypoint.sh /docker-entrypoint.sh


We no longer need a custom entry point script.

dekobon · 2025-09-09T00:59:35Z

Dockerfile.oss

    && mkdir -p /var/cache/nginx/s3_proxy \
    && chown nginx:nginx /var/cache/nginx/s3_proxy \
-    && chmod -R -v +x /docker-entrypoint.sh /docker-entrypoint.d/*.sh;
+    && find /docker-entrypoint.d -type f \( -name '*.sh' -or -name '*.envsh' \) -exec chmod -v +x {} \;


This find command ensures all the files in the entry point directory are executable.

dekobon · 2025-09-09T01:01:20Z

Dockerfile.plus

-    && chmod -R -v +x /docker-entrypoint.sh /docker-entrypoint.d/*.sh;

-ENTRYPOINT ["/docker-entrypoint.sh"]
+RUN set -eux \


We now append the commented out default E+V blocks into the nginx.conf, so that the entry point substitution script can replace values from it.

dekobon · 2025-09-09T16:12:38Z

Dockerfile.plus

 # startup is the same.
+COPY --from=build /etc/nginx/modules/ngx_http_xslt_filter_module*.so /etc/nginx/modules/
+COPY --from=build /etc/nginx/modules/ngx_http_js_module*.s /etc/nginx/modules/
+COPY --from=build /lib/aarch64-linux-gnu/libxslt.so.1 /lib/aarch64-linux-gnu/


It looks like I hard coded architecture here, so this will need to be fixed.

Copilot

Pull Request Overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-19T15:45:07Z

test.sh

-      docker build -f Dockerfile.${nginx_type} \
-        --tag nginx-s3-gateway --tag nginx-s3-gateway:${nginx_type} .
+      e "Only BuildKit builds are supported with NGINX Plus image"
+      exit ${}


Empty variable expansion in exit statement. This should be exit ${build_dep_exit_code} to properly exit with the defined error code.

Suggested change

exit ${}

exit ${build_dep_exit_code}

docs/getting_started.md

common/docker-entrypoint.d/01-set-defaults.envsh

Copilot

Pull Request Overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Dockerfile.latest-njs

4141done

👍 This looks great. One copilot comment looks like it could be legit flagging package names ending in a dash?

This change does the following: * Migrates to using the official NGINX Plus Docker images as base images * Removes the distinction between BuildKit and non-BuildKit builds for Plus images (OSS never had this) * Adds support for license validation for Plus images * Introduces a multi-stage build for Plus images Signed-off-by: Elijah Zupancic <e.zupancic@f5.com>

Signed-off-by: Elijah Zupancic <e.zupancic@f5.com>

By using the version reported by NGINX rather than the environment variable it allows for a more reliable setting and less complexity. Signed-off-by: Elijah Zupancic <e.zupancic@f5.com>

dekobon · 2025-09-29T17:51:53Z

👍 This looks great. One copilot comment looks like it could be legit flagging package names ending in a dash?

I added a comment to clarify what trailing dashes are doing.

Copilot

Pull Request Overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

common/docker-entrypoint.d/01-set-defaults.envsh

dekobon requested review from 4141done and Copilot September 4, 2025 20:23

dekobon requested a review from a team as a code owner September 4, 2025 20:23

Copilot AI reviewed Sep 4, 2025

View reviewed changes

Dockerfile.plus Outdated Show resolved Hide resolved

Dockerfile.plus Outdated Show resolved Hide resolved

Dockerfile.buildkit.plus Outdated Show resolved Hide resolved

Dockerfile.buildkit.plus Outdated Show resolved Hide resolved

4141done previously approved these changes Sep 4, 2025

View reviewed changes

dekobon dismissed 4141done’s stale review via 3fb3c55 September 4, 2025 22:48

dekobon force-pushed the nginx-plus-base-image branch from 3fb3c55 to 62504e6 Compare September 5, 2025 16:21

dekobon force-pushed the nginx-plus-base-image branch from e928452 to 8c80096 Compare September 9, 2025 00:55

dekobon requested a review from oxpa September 9, 2025 00:55

dekobon commented Sep 9, 2025

View reviewed changes

dekobon force-pushed the nginx-plus-base-image branch 2 times, most recently from ce18e42 to 9c8763f Compare September 16, 2025 22:35

dekobon force-pushed the nginx-plus-base-image branch from 9c8763f to 16aff32 Compare September 18, 2025 15:44

dekobon requested review from Copilot and 4141done September 19, 2025 15:44

Copilot AI reviewed Sep 19, 2025

View reviewed changes

dekobon force-pushed the nginx-plus-base-image branch from 16aff32 to e8138d2 Compare September 19, 2025 21:41

dekobon requested a review from Copilot September 19, 2025 21:42

Copilot AI reviewed Sep 19, 2025

View reviewed changes

Dockerfile.latest-njs Show resolved Hide resolved

4141done previously approved these changes Sep 19, 2025

View reviewed changes

dekobon added 3 commits September 29, 2025 10:51

chore: remove deprecated version parameter from docker-compose.yaml

d53ee83

Signed-off-by: Elijah Zupancic <e.zupancic@f5.com>

fix: use nginx version reported by binary instead of env var

1207c58

By using the version reported by NGINX rather than the environment variable it allows for a more reliable setting and less complexity. Signed-off-by: Elijah Zupancic <e.zupancic@f5.com>

dekobon dismissed 4141done’s stale review via 1207c58 September 29, 2025 17:51

dekobon force-pushed the nginx-plus-base-image branch from e8138d2 to 1207c58 Compare September 29, 2025 17:51

dekobon requested review from Copilot and 4141done September 29, 2025 17:52

Copilot AI reviewed Sep 29, 2025

View reviewed changes

common/docker-entrypoint.d/01-set-defaults.envsh Show resolved Hide resolved

		@@ -1,9 +1,5 @@
		FROM nginx:1.29.0@sha256:f5c017fb33c6db484545793ffb67db51cdd7daebee472104612f73a85063f889

		# NJS env vars

feat: update nginx plus image builds to use nginx plus base images #449

Are you sure you want to change the base?

feat: update nginx plus image builds to use nginx plus base images #449

Uh oh!

Conversation

dekobon commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

4141done left a comment

Choose a reason for hiding this comment

Uh oh!

oxpa commented Sep 5, 2025

Uh oh!

dekobon commented Sep 9, 2025

Uh oh!

dekobon Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

dekobon Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

dekobon Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

dekobon Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

dekobon Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Sep 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

4141done left a comment

Choose a reason for hiding this comment

Uh oh!

dekobon commented Sep 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

dekobon commented Sep 4, 2025 •

edited

Loading