Nginx 1.14Deprecated

Description

End of life notice: The rhel8/nginx-114 container image reaches its end of life in May 2021. Update to rhel8/nginx-116 or rhel8/nginx-118 prior to this date. See the Application Streams Life Cycle for Red Hat Enterprise Linux 8 at https://access.redhat.com/support/policy/updates/rhel8-app-streams-life-cycle.

Nginx is a web server and a reverse proxy server for HTTP, SMTP, POP3 and IMAP protocols, with a strong focus on high concurrency, performance and low memory usage. The container image provides a containerized packaging of the nginx 1.14 daemon. The image can be used as a base image for other applications based on nginx 1.14 web server. Nginx server image can be extended using Openshift's Source build feature.

Usage in OpenShift

In this example, we assume that you are using the rhel8/nginx-114 image, available through the nginx:1.14 imagestream tag in Openshift. To build a simple test-app application in Openshift:

oc new-app nginx:1.14~https://github.com/sclorg/nginx-container.git --context-dir=1.14/test/test-app/

To access the application:

$ oc get pods
$ oc exec <pod> -- curl 127.0.0.1:8080

Source-to-Image framework and scripts

This image supports the Source-to-Image (S2I) strategy in OpenShift. The Source-to-Image is an OpenShift framework which makes it easy to write images that take application source code as an input, use a builder image like this Nginx container image, and produce a new image that runs the assembled application as an output.

In case of Nginx container image, the application source code is typically either static HTML pages or configuration files.

To support the Source-to-Image framework, important scripts are included in the builder image:

• The /usr/libexec/s2i/run script is set as the default command in the resulting container image (the new image with the application artifacts).

• The /usr/libexec/s2i/assemble script inside the image is run to produce a new image with the application artifacts. The script takes sources of a given application (HTML pages), Nginx configuration files, and places them into appropriate directories inside the image. The structure of nginx-app can look like this:

./nginx.conf-- The main nginx configuration file

./nginx-cfg/*.conf Should contain all nginx configuration we want to include into image

./nginx-default-cfg/*.conf Contains any nginx config snippets to include in the default server block

./nginx-start/*.sh Contains shell scripts that are sourced right before nginx is launched

./nginx-perl/*.pm Contains perl modules to be use by perl_modules and perl_require directives

./ Should contain nginx application source code

Build an application using a Dockerfile

Compared to the Source-to-Image strategy, using a Dockerfile is a more flexible way to build an Nginx container image with an application. Use a Dockerfile when Source-to-Image is not sufficiently flexible for you or when you build the image outside of the OpenShift environment.

To use the Nginx image in a Dockerfile, follow these steps:

1. Pull a base builder image to build on

podman pull rhel8/nginx-114

2. Pull an application code

An example application available at https://github.com/sclorg/nginx-container.git is used here. To adjust the example application, clone the repository.

git clone https://github.com/sclorg/nginx-container.git nginx-container
cd nginx-container/examples/1.14/

3. Prepare an application inside a container

This step usually consists of at least these parts:

• putting the application source into the container
• moving configuration files to the correct place (if available in the application source code)
• setting the default command in the resulting image

For all these three parts, you can either set up all manually and use the nginx command explicitly in the Dockerfile (3.1.), or you can use the Source-to-Image scripts inside the image (3.2.. For more information about these scripts, which enable you to set-up and run the nginx daemon, see the "Source-to-Image framework and scripts" section above.

3.1. To use your own setup, create a Dockerfile with this content:

FROM registry.access.redhat.com/ubi8/nginx-114

# Add application sources
ADD test-app/nginx.conf "${NGINX_CONF_PATH}"
ADD test-app/nginx-default-cfg/*.conf "${NGINX_DEFAULT_CONF_PATH}"
ADD test-app/nginx-cfg/*.conf "${NGINX_CONFIGURATION_PATH}"
ADD test-app/*.html .

# Run script uses standard ways to run the application
CMD nginx -g "daemon off;"

3.2. To use the Source-to-Image scripts and build an image using a Dockerfile, create a Dockerfile with this content:

FROM registry.access.redhat.com/ubi8/nginx-114

# Add application sources to a directory that the assemble script expects them
# and set permissions so that the container runs without root access
USER 0
ADD test-app /tmp/src/
RUN chown -R 1001:0 /tmp/src
USER 1001

# Let the assemble script to install the dependencies
RUN /usr/libexec/s2i/assemble

# Run script uses standard ways to run the application
CMD /usr/libexec/s2i/run

4. Build a new image from a Dockerfile prepared in the previous step

podman build -t nginx-app .

5. Run the resulting image with the final application

podman run -d nginx-app

Direct usage with a mounted directory

An example of the data on the host for the following example:

$ ls -lZ /wwwdata/html
-rw-r--r--. 1 1001 1001 54321 Jan 01 12:34 index.html
-rw-r--r--. 1 1001 1001  5678 Jan 01 12:34 page.html

If you want to run the image directly and mount the static pages available in the /wwwdata/ directory on the host as a container volume, execute the following command:

$ podman run -d --name nginx -p 8080:8080 -v /wwwdata:/opt/app-root/src:Z rhel8/nginx-114 nginx -g "daemon off;"

This creates a container named nginx running the Nginx server, serving data from the /wwwdata/ directory. Port 8080 is exposed and mapped to the host. You can pull the data from the nginx container using this command:

$ curl -Lk 127.0.0.1:8080

You can replace /wwwdata/ with location of your web root. Please note that this has to be an absolute path, due to podman requirements.

Environment variables and volumes

The nginx container image supports the following configuration variable, which can be set by using the -e option with the podman run command:

NGINX_LOG_TO_VOLUME When NGINX_LOG_TO_VOLUME is set, nginx logs into /var/log/nginx/. In case of RHEL-7 and CentOS-7 images, this is a symlink to /var/opt/rh/rh-nginx114/log/nginx/.

Troubleshooting

By default, nginx access logs are written to standard output and error logs are written to standard error, so both are available in the container log. The log can be examined by running:

podman logs <container>

If NGINX_LOG_TO_VOLUME variable is set, nginx logs into /var/log/nginx/. In case of RHEL-7 and CentOS-7 images, this is a symlink to /var/opt/rh/rh-nginx114/log/nginx/, which can be mounted to host system using the container volumes.

See also

Dockerfile and other sources for this container image are available on https://github.com/sclorg/nginx-container. In that repository you also can find another versions of Python environment Dockerfiles. Dockerfile for CentOS is called Dockerfile, Dockerfile for RHEL7 is called Dockerfile.rhel7, for RHEL8 it's Dockerfile.rhel8 and the Fedora Dockerfile is called Dockerfile.fedora.