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
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.
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.
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 agreement