Get notified of upcoming product changes, critical vulnerability notifications and patches and more.
Sign inMinimal Wolfi-based nginx HTTP, reverse proxy, mail proxy, and a generic TCP/UDP proxy server
The image is available on cgr.dev
:
On May 3, 2023 the Chainguard nginx Image was rebuilt with several improvements, including breaking changes. You may need to take action to update your application.
Specifically, the config file was changed to bring the default configuration closer to that of the official nginx image. If you override the config with a custom configuration, you should not be affected.
The changes included:
80
to 8080
. This is required to run on Kubernetes as a non-privileged user./usr/share/nginx/html
If you are unable to update currently, you can use the last build of the previous image:
This digest corresponds to nginx version 1.24.0. This image is not updated and you should migrate to the new configuration as soon as possible.
To try out the image, run:
Following that, navigate to localhost:8080
in your web browser. There, you will find the default nginx welcome page.
You can also use the nginx Image to serve your own custom content. As an example, create a file named index.html
with the following command:
Then can instruct the the nginx Image to serve the index.html
file:
If you navigate to localhost:8080
in your web browser, it will return Hello World from Nginx!
.
To use a custom nginx.conf
you can mount the file into the container, being sure to edit the -p 8080:8080
published port(s) to match your configuration's listen
directive:
If you want to run with read-only filesystem, you will need to mount the /var/run
and /var/lib/nginx/tmp
directories. The easiest way to do this is with --tmpfs
e.g:
Starting the container gives the following warning:
The warning is telling us container is already running as the named user, so it doesn't have anything to do. If the container is run as root, it would switch to the named user. We decided to leave this configuration in despite the warning for anyone that runs with --user
switch in Docker or an equivalent.
Wherever possible, the Chainguard nginx Image tries to follow the same configuration as the official Docker version. However, Chainguard designs Images with minimalism in mind; many Chainguard Images, by default, don't include a shell or package manager. This means that it's often impossible to achieve an identical configuration as the upstream version, as is the case between Chainguard's nginx Image and the official image from Docker Hub. This section outlines the major differences between these images.
The official Docker image starts as the root user and forks to a less privileged user. By contrast, the Chainguard nginx Image starts up as a less privileged user and no forking is required. For most users this shouldn't make a difference, but note the "User Directive Warning" outlined previously.
To support the change to an unprivileged user, the default port was moved to 8080
, contrasting with port 80
used by the official image.
The official Docker image checks for the existence of /proc/net/if_inet6
and automatically listens on [::]:80
if it exists. For simplicity, we only listen on IPv4, but you can add IPv6 support by mounting a configuration file with a section like the following:
Note that the default configuration file in the Chainguard nginx Image has the relevant section at /etc/nginx/conf.d/default.conf
The Docker official image has support for setting environment variables that get substituted into the config file. Currently we do not have support for this, but are looking into options.
Chainguard Images contain software packages that are direct or transitive dependencies. The following licenses were found in the "latest" version of this image:
Apache-2.0
BSD-2-Clause
BSD-3-Clause
GCC-exception-3.1
GPL-2.0-or-later
GPL-3.0-or-later
LGPL-2.1-or-later
For a complete list of licenses, please refer to this Image's SBOM.
Software license agreementThis is a FIPS validated image for FedRAMP compliance.
This image is STIG hardened and scanned against the DISA General Purpose Operating System SRG with reports available.
Learn more about STIGsGet started with STIGsProducts
Chainguard Images© 2024 Chainguard, Inc.