nginx

Last changed

Try a starter image for free


docker pull cgr.dev/chainguard/nginx

Need access to a specific tag? Contact us.

Create your free account

Integrate Chainguard into your developer workflows, manage your image versions to stay free of CVEs, and view critical SBOM and provenance details.

Chainguard Container for nginx

Minimal Wolfi-based nginx HTTP, reverse proxy, mail proxy, and a generic TCP/UDP proxy server

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:


docker pull cgr.dev/ORGANIZATION/nginx:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Chainguard's nginx container image is comparable to both the latest and alpine versions of the official nginx image and, wherever possible, the Chainguard Container's configuration will align with the official image. However, Chainguard Images are built to be as minimal as possible, requiring a specific set of changes, which are outlined here.

Note: just as with the official nginx image, the latest tag will always be an Nginx mainline rather than stable release.

Users

The official Docker image starts as the root user and forks to a less privileged user. By contrast, the Chainguard nginx Container 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 following section on custom server blocks for more information.

Default port

The default port for the nginx Chainguard Container is 8080, rather than 80.

IPv6 Support

The official nginx image checks for the existence of /proc/net/if_inet6 and automatically listens on [::]:80 if it exists. For simplicity, Chainguard's nginx container image only listens on IPv4, but you can add IPv6 support by mounting a configuration file with a section similar to the following:


server {
    listen       8080;
    listen  [::]:8080;
    ...

Note that the default configuration file in the Chainguard nginx Container includes the relevant section at /etc/nginx/conf.d/default.conf.

Environment Variable Substitution

The official nginx image has support for setting environment variables that get substituted into the config file. Currently we do not have support for this.

User Directive Warning

Starting the container gives the following warning:


 [warn] 1#1: the "user" directive makes sense only if the master process runs with super-user privileges, ignored in /etc/nginx/nginx.conf:2

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.

Entrypoint

The entrypoint for the nginx Chainguard Container is /usr/sbin/nginx. Commands run as part of docker run or a CMD statement in a Dockerfile will be passed as arguments to nginx.

Getting Started

For a hands-on example of how to use the nginx container image, we encourage you to check out our guide on Getting Started with the nginx Chainguard Container.

The nginx Chainguard Container provides a secure basis for serving static content, running a reverse proxy, or performing other common server tasks. To try out the image, run:


docker run -p 8080:8080 cgr.dev/chainguard/nginx:latest

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 Container to serve your own custom content. As an example, first create a folder to contain static HTML that will be served by nginx:


mkdir -p ~/html

Next, create a file called index.html in the html folder:


cat > ~/html/index.html <<EOF
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>nginx</title>
</head>
<body>
  <h2>Hello World from nginx!</h2>
</body>
</html>
EOF

You can then instruct the nginx Image to serve the index.html file:


docker run \
 -v $(pwd)/html:/usr/share/nginx/html \
 -p 8080:8080 \
 cgr.dev/chainguard/nginx:latest

If you navigate to localhost:8080 in your web browser, it will return our custom HTML: Hello World from nginx!.

Adding a Custom Server Block

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:


mkdir -p ~/conf.d

Create a new server block configuration file within this folder:


cat > ~/conf.d/static.conf <<EOF
server {
  listen        4000;

  location / {
    autoindex on;
    root  /www/data;
  } 
}
EOF

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


docker run -p 4000:4000 \
 -v $(pwd)/html:/www/data \
 -v $(pwd)/conf.d:/etc/nginx/conf.d \
 cgr.dev/chainguard/nginx:latest

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.

Replacing the Default nginx Configuration

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:


mkdir -p nginx-conf

Create a configuration file inside this folder:


cat > ~/nginx-conf/nginx.conf <<EOF
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    default_type  application/octet-stream;

    sendfile        on;

    server {
      listen        4000;

        location / {
            autoindex on;
            root  /www/data;
  } 
}

}
EOF

Start a container with our created html and nginx-config folders as volumes.


docker run -p 4000:4000 \
 -v $(pwd)/html:/www/data \
 -v $(pwd)/nginx-conf:/etc/nginx \
 cgr.dev/chainguard/nginx:latest

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.

Run in a read-only File System

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:


docker run \
 --read-only \
 --tmpfs /var/lib/nginx/tmp/ --tmpfs /var/run/ \
 --cap-drop=ALL \
 -p 8080:8080 \
 cgr.dev/chainguard/nginx

You can also run the nginx container image in a read-only filesystem using Kubernetes. To do so, you could use a manifest like the following example:


apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
	matchLabels:
  	app: nginx
  template:
	metadata:
  	labels:
    	app: nginx
	spec:
  	containers:
  	- name: nginx
    	image: cgr.dev/chainguard/nginx:latest
    	ports:
    	- containerPort: 8080
    	securityContext:
      	readOnlyRootFilesystem: true
    	volumeMounts:
    	- name: run
      	mountPath: /var/run/
    	- name: tmp
      	mountPath: /var/lib/nginx/tmp/
  	volumes:
  	- name: run
    	emptyDir: {}
  	- name: tmp
    	emptyDir: {}
  	- name: conf
    	configMap:
      	name: nginx-conf

Documentation and Resources

Get this image as a Chainguard VM

This image is also available as a Chainguard VM, available to deploy on Amazon AWS EC2, Google Cloud Compute Engine, Microsoft Azure and On-Prem through VMware, KVM and QEMU virtualization. Complete our registration form to get access to Chainguard VMs and try it out for yourself.

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

Minimal design, without unnecessary software bloat
Daily builds to ensure container images are up-to-date with available security patches
High quality build-time SBOMs attesting to the provenance of all artifacts within the image
Verifiable signatures provided by Sigstore
Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.

Licenses

Chainguard container images contain software packages that are direct or transitive dependencies. The following licenses were found in the "latest" tag 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

Compliance

A FIPS validated version of this image is available for FedRAMP compliance. STIG is included with FIPS image.

Related images

nginx-fips

nginx-iamguarded

nginx-iamguarded-fips

Product

Chainguard Containers Chainguard Libraries Chainguard VMs Integrations Pricing

Solutions

FedRAMP PCI DSS Golden Images CVE Remediation Public Sector

Customers

Customer Stories Chainguard Reviews

Resources

Events & Webinars Chainguard Courses Documentation Trust Center

Company

About Us Blog Partners Newsroom Careers Legal