Last changed
docker pull cgr.dev/chainguard/nginx
Need access to a specific version? Contact us.
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
Chainguard Images are regularly-updated, minimal container images with low-to-zero CVEs.
This image is available on cgr.dev
:
Be sure to replace the ORGANIZATION
placeholder with the name used for your organization's private repository within the Chainguard registry.
The nginx
Chainguard Image provides a secure basis for serving static content, running a reverse proxy, or performing other common server tasks.
We have two image variants available:
nginx:latest-dev
variant that contains the apk
package manager and the bash
, ash
, and sh
shells.To pull the minimal runtime variant from cgr.dev
:
To pull the dev variant:
To try out the image, run:
After starting the container, navigate to localhost:8080
in your web browser. You should find the default nginx welcome page.
You can also use the nginx Image to serve your own custom content. As an example, first create a folder to contain static HTML that will be served by nginx:
Next, create a file called index.html
in the html
folder:
You can then instruct the nginx Image to serve the index.html
file:
If you navigate to localhost:8080
in your web browser, it will return our custom HTML: Hello World from Nginx!
.
The default nginx configuration file checks for custom server blocks as files with a .conf
extension within the /etc/nginx/conf.d
folder. As an example, let's create a minimal server block that will serve the index.html
file in the html
folder created above from a new location (/www/data
) and from a new port (4000
).
Create a folder to hold our block configuration:
Create a new server block configuration file within this folder:
The above is a server block that will be loaded within the default nginx configuration file. Static files will be served from the /www/data
location at port 4000
.
The following command runs an nginx container, adding our html
folder and the conf.d
configuration folder as volumes
The above will serve our HTML from the /www/data
folder on port 4000
using the additional settings defined in the default nginx.conf
file.
To replace the main nginx configuration file, you can mount a folder containing a configuration file named nginx.conf
at /etc/nginx/
within the container.
First create a folder to contain our replacement configuration:
Create a configuration file inside this folder:
Start a container with our created html
and nginx-config
folders as volumes.
You should be able to view the contents of the index.html
file in the html
folder at localhost:4000
. For more on nginx configuration, refer to the documentation at nginx.org.
If you want to serve files using a read-only filesystem, you will need to mount the /var/run
and /var/lib/nginx/tmp
directories. You can do this with the --tmpfs
option:
Starting the container gives the following warning:
This warning tells us that the container is already running as the user nginx
, meaning that the directive has no effect because the default user is already nginx
. If the container is run as root, it would switch to the nginx
user to run the nginx
process. We've included this directive in the default configuration for those running the container with a different user using the --user
flag or equivalent.
Wherever possible, the Chainguard nginx Image tries to follow the same configuration as the official version hosted on Docker Hub. However, Chainguard Images are built to be as minimal as possible, requiring a specific set of changes. 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 as a less privileged user named nginx
and no forking is required.
Also note that the default nginx
configuration file includes a user directive that will run the nginx
process as the nginx
user. See the above section on custom server blocks for more information.
The default port for the nginx
Chainguard Image is 8080
, rather than 80
.
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 similar to the following:
Note that the default configuration file in the Chainguard nginx Image includes 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.
If you have a Zendesk account (typically set up for you by your Customer Success Manager) you can reach out to Chainguard's Customer Success team through our Zendesk portal.
Chainguard Images are a collection of container images designed for security and minimalism.
Many Chainguard Images are distroless; they contain only an open-source application and its runtime dependencies. These images do not even contain a shell or package manager. Chainguard Images are built with Wolfi, our Linux undistro designed to produce container images that meet the requirements of a secure software supply chain.
The main features of Chainguard Images include:
-dev
VariantsAs mentioned previously, Chainguard’s distroless Images have no shell or package manager by default. This is great for security, but sometimes you need these things, especially in builder images. For those cases, most (but not all) Chainguard Images come paired with a -dev
variant which does include a shell and package manager.
Although the -dev
image variants have similar security features as their distroless versions, such as complete SBOMs and signatures, they feature additional software that is typically not necessary in production environments. The general recommendation is to use the -dev
variants only to build the application and then copy all application artifacts into a distroless image, which will result in a final container image that has a minimal attack surface and won’t allow package installations or logins.
That being said, it’s worth noting that -dev
variants of Chainguard Images are completely fine to run in production environments. After all, the -dev
variants are still more secure than many popular container images based on fully-featured operating systems such as Debian and Ubuntu since they carry less software, follow a more frequent patch cadence, and offer attestations for what they include.
To better understand how to work with Chainguard Images, we encourage you to visit Chainguard Academy, our documentation and education platform.
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 agreementA FIPS validated version of this image is available for FedRAMP compliance. STIG is included with FIPS image.