Chainguard Container for nginx-fips

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-fips:latest

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

Description

The nginx-fips Chainguard Image provides a secure, FIPS-enabled basis for serving static content, running a reverse proxy, or performing other common server tasks.

Compatibility Notes

Where possible, the nginx-fips Chainguard Image is built for compatibility with the Docker official image for nginx. This section outlines the major differences between the nginx-fips Chainguard Images and the Docker official image.

FIPS Support

The nginx-fips Chainguard Image ships with a validated redistribution of the OpenSSL's FIPS provider module. For more on FIPS support in Chainguard Images, consult the guide on FIPS-enabled Chainguard Images on Chainguard Academy.

Default port

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

Environment Variable Substitution

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.

Users

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 section on custom server blocks for more information.

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-fips Chainguard Image 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.

Variants

We have two image variants available:

• A minimal runtime variant that removes shells and package managers for additional security.
• An nginx-fips: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:

docker pull cgr.dev/ORGANIZATION/nginx-fips:latest

To pull the dev variant:

docker pull cgr.dev/ORGANIZATION/nginx-fips:latest-dev

Getting Started

When running the below examples, first set the ORGANIZATION environmental variable as follows:

ORGANIZATION=my-organization

Alternatively, manually replace each occurance of ORGANIZATION with the name of your organization.

Test FIPS Compliance

To test the image's compliance with the FIPS framework, you can run a provided test script with the following command:

docker run -it \
 --user root --entrypoint openssl-fips-test \
 cgr.dev/chainguard-private/nginx-fips

You should see output similar to the following:

Checking OpenSSL lifecycle assurance.
*** Running check: FIPS module is available...
    HMAC : (Module_Integrity) : Pass
    SHA1 : (KAT_Digest) : Pass
    SHA2 : (KAT_Digest) : Pass
    SHA3 : (KAT_Digest) : Pass
    TDES : (KAT_Cipher) : Pass
    AES_GCM : (KAT_Cipher) : Pass
    AES_ECB_Decrypt : (KAT_Cipher) : Pass
    RSA : (KAT_Signature) :     RNG : (Continuous_RNG_Test) : Pass
...

You can review the output for detailed information on OpenSSL module and cipher availability.

Serve Content Using Default Configuration

To test the functionality of the image, run:

docker run -p 8080:8080 cgr.dev/$ORGANIZATION/nginx-fips: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 Image 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/$ORGANIZATION/nginx-fips:latest

If you navigate to localhost:8080 in your web browser, it will return our custom HTML: Hello World from Nginx!. You may need to refresh the page to see the changed message.

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/$ORGANIZATION/nginx-fips: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/$ORGANIZATION/nginx-fips: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.

Configuration

IPv6 Support

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:

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

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

Running 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/$ORGANIZATION/nginx-fips

Make sure to replace $ORGANIZATION with the name of your organization if you have not already set the ORGANIZATION environmental variable to your organization name.

Replacing the Default Configuration or Server Block Configuration

See examples under Getting Started for detailed instructions on replacing a server block or the default nginx.conf configuration file.

Documentation and Resources

• Chainguard Academy: FIPS-enabled Chainguard Images
• Chainguard Academy: Getting Started with the nginx Chainguard Image
• Video: Getting Started with the nginx Chainguard Image

What are Chainguard Containers?

Chainguard Containers are minimal container images that are secure by default.

In many cases, the Chainguard Containers tagged as :latest contain only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager. Chainguard Containers are built with Wolfi, our Linux undistro 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 -dev variant.

Although the -dev container image variants have similar security features as their more minimal versions, they feature additional software that is typically not necessary in production environments. We recommend using multi-stage builds to leverage the -dev variants, copying application artifacts into a final minimal container that offers a reduced attack surface that won’t allow package installations or logins.

Learn More

To better understand how to work with Chainguard Containers, please visit Chainguard Academy and Chainguard Courses.

In addition to Containers, Chainguard offers VMs and Libraries. Contact Chainguard to access additional products.

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.