{"id":37008,"date":"2020-05-28T08:30:24","date_gmt":"2020-05-27T23:30:24","guid":{"rendered":"https:\/\/jirak.net\/wp\/deploying-nginx-and-nginx-plus-with-docker\/"},"modified":"2020-05-28T10:34:10","modified_gmt":"2020-05-28T01:34:10","slug":"deploying-nginx-and-nginx-plus-with-docker","status":"publish","type":"post","link":"https:\/\/jirak.net\/wp\/deploying-nginx-and-nginx-plus-with-docker\/","title":{"rendered":"Deploying NGINX and NGINX Plus with Docker"},"content":{"rendered":"

Deploying NGINX and NGINX Plus with Docker<\/p>\n

\n<\/p>\n

Note<\/strong>: This post was updated in May 2020 to make the Docker commands comply with current standards and to provide an updated NGINX Plus Dockerfile for Debian and Alpine Linux distributions.<\/em><\/p>\n

Docker<\/a>\u00a0is an\u00a0open platform for building, shipping, and running distributed applications as containers (lightweight, standalone, executable packages of software that include everything needed to run an application). Containers can in turn be deployed and orchestrated by container orchestration platforms such as Kubernetes. (In addition to the Docker container technology for NGINX Open Source and NGINX Plus discussed in this blog, NGINX provides the NGINX Open Source and NGINX Plus Ingress Controllers for Kubernetes<\/a>; for NGINX Plus subscribers, support is included at no extra cost.)<\/p>\n

As software applications, NGINX Open Source and NGINX Plus are great use cases for Docker, and we publish an\u00a0NGINX Open Source image<\/a> on\u00a0Docker Hub<\/a>, the repository of Docker images. This article describes how you can deploy NGINX Open Source using this image from Docker Hub, or create and deploy your own Docker image of NGINX Plus.<\/p>\n

Introduction<\/h2>\n

The Docker open platform includes the Docker Engine –\u00a0the open source runtime that builds, runs, and orchestrates containers –\u00a0and Docker Hub, a hosted service where Dockerized applications are distributed, shared, and collaborated on by the entire development community or within the confines of a specific organization.<\/p>\n

Docker containers enable developers to focus their efforts on application \u201ccontent\u201d by separating applications from the constraints of infrastructure. Dockerized applications are instantly portable to any infrastructure –\u00a0laptop, bare‑metal server, VM, or cloud –\u00a0making them modular components that can be readily assembled and reassembled into fully featured distributed applications and continuously innovated on in real time.<\/p>\n

For more information about Docker, see\u00a0Why Docker?<\/a> or the full Docker\u00a0documentation<\/a>.<\/p>\n

Using the NGINX Docker Image<\/h2>\n

You can create an NGINX instance in a Docker container using the NGINX image<\/a> from Docker Hub.<\/p>\n

Let’s start with a very simple example. To launch\u00a0an instance of NGINX running in a container and using the default NGINX configuration, run this command:<\/p>\n

# docker run --name mynginx1 -p 80:80 -d nginx<\/strong>\r\nfcd1fb01b14557c7c9d991238f2558ae2704d129cf9fb97bb4fadf673a58580d<\/code><\/pre>\n
This command creates a container named mynginx1<\/strong> based on the NGINX\u00a0image. The command returns the long form of the container ID, which is used in the name of log files; see Managing Logging<\/a>.<\/p>\n
The -d<\/code> option<\/span> specifies that the container runs in detached mode, which means that it continues to run until stopped but does not respond to commands run on the command line. We discuss later<\/a> how to interact with the container. <\/p>\n
The -p<\/code> option<\/span> tells Docker to map the ports exposed in the container by the NGINX image – port 80 – to the specified port on the Docker host. The first parameter specifies the port in the Docker host, while the second parameter is mapped to the port exposed in the container.<\/p>\n
To verify that the container was created and is running, and to see the port mappings, we run docker<\/code> ps<\/code><\/span>. (We’ve split the output across multiple lines here to make it easier to read.)<\/p>\n
# docker ps<\/strong>\r\nCONTAINER\u00a0ID\u00a0 IMAGE\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0  COMMAND\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 CREATED\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0  STATUS\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ...  \r\nfcd1fb01b145  nginx:latest  \"nginx -g 'daemon of  16 seconds ago  Up 15 seconds ... \r\n\r\n    ... PORTS              NAMES\r\n    ... 0.0.0.0:80->80\/tcp mynginx1<\/code><\/pre>\n
The PORTS<\/code> field in the output reports that port 80 on the Docker host is mapped to port 80 in the container. Another way to verify that NGINX is running is to make an HTTP request to that port. The code for the default NGINX welcome page appears:<\/p>\n
# curl http:\/\/localhost:49167<\/strong>\r\n<!DOCTYPE html>\r\n<html>\r\n<head>\r\n<title>Welcome to nginx!<\/title>\r\n<style>\r\n body {\r\n width: 35em;\r\n margin: 0 auto;\r\n font-family: Tahoma, Verdana, Arial, sans-serif;\r\n }\r\n<\/style>\r\n<\/head>\r\n<body>\r\n<h1>Welcome to nginx!<\/h1>\r\n<p>If you see this page, the nginx web server is successfully installed and\r\nworking. Further configuration is required.<\/p>\r\n\r\n<p>For online documentation and support please refer to\r\n<a href=\"http:\/\/nginx.org\/\">nginx.org<\/a>.<br\/>\r\nCommercial support is available at\r\n<a href=\"https:\/\/www.nginx.com\/\">nginx.com<\/a>.<\/p>\r\n\r\n<p><em>Thank you for using nginx.<\/em><\/p>\r\n<\/body>\r\n<\/html><\/code><\/pre>\n
Working with the NGINX Docker Container<\/h2>\n
So now we have a working NGINX Docker container, but how do we manage the content and the NGINX configuration? And what about logging?<\/p>\n
A Note About SSH<\/h3>\n
It is common to enable SSH access to NGINX instances, but the NGINX image does not have OpenSSH installed, because Docker containers are generally intended to be for a single purpose (in this case running NGINX), and for normal operations there is no need to have shell access directly to the NGINX container. Instead we’ll use other methods supported by Docker. For a detailed discussion of alternatives to SSH access, see Why You Don’t Need to Run SSHd in Your Docker Containers<\/a>.<\/p>\n
Managing Content and Configuration Files<\/h3>\n
There are several ways you can manage both the content served by NGINX and the NGINX configuration files. Here we cover a few of the options.<\/p>\n
Option 1 – Maintain the Content and Configuration on the Docker Host<\/h4>\n
When the container is created we\u00a0can tell Docker to mount a local directory on the Docker host to a directory in the container. The NGINX image uses the default NGINX configuration, which uses \/usr\/share\/nginx\/html<\/strong> as the container’s root directory and puts configuration files in \/etc\/nginx<\/strong>. For a Docker host with content in the local directory \/var\/www<\/strong> and configuration files in \/var\/nginx\/conf<\/strong>, run this command (which appears on multiple lines here only for legibility):<\/p>\n
# docker run --name mynginx2 --mount type=bind source=\/var\/www,target=\/usr\/share\/nginx\/html,readonly --mount type=bind,source=\/var\/nginx\/conf,target=\/etc\/nginx\/conf,readonly -p 80:80 -d nginx<\/strong><\/code><\/pre>\n
Now any change made to the files in the local directories \/var\/www<\/strong> and \/var\/nginx\/conf<\/strong> on the Docker host are reflected in the directories \/usr\/share\/nginx\/html<\/strong> and \/etc\/nginx<\/strong> in the container. The readonly<\/code> option means these directories can be changed only on the Docker host, not from within the container.<\/p>\n
Option 2 – Copy Files from the Docker Host<\/h4>\n
Another option is to have Docker copy the content and configuration files from a local directory on the Docker host during container creation. Once a\u00a0container is created, the files are maintained by creating a new container when files change or by modifying the files in the container. A simple way to copy the files is to create a Dockerfile<\/strong>\u00a0with commands that are run during generation of a new Docker image based on the NGINX image from Docker Hub. For the file‑copy (COPY<\/code>) commands in the Dockerfile<\/strong>, the local directory path is relative to the build context where the Dockerfile<\/strong>\u00a0is located.<\/p>\n
In our example, the content is in the content<\/strong> directory and the configuration files are in the conf<\/strong> directory, both subdirectories of the directory where the Dockerfile<\/strong> is located. The NGINX image includes default NGINX configuration files as \/etc\/nginx\/nginx.conf<\/strong> and \/etc\/nginx\/conf.d\/default.conf<\/strong>. Because we instead want to use the configuration files from the host, we include RUN<\/code> commands that delete the default files:<\/p>\n
FROM nginx\r\nRUN rm \/etc\/nginx\/nginx.conf \/etc\/nginx\/conf.d\/default.conf\r\nCOPY\u00a0content \/usr\/share\/nginx\/html\r\nCOPY\u00a0conf \/etc\/nginx<\/code><\/pre>\n
We create our own NGINX image by running the following command from the directory where the Dockerfile<\/strong> is located. Note the period (“.”) at the end of the command. It defines the current directory as the build context, which contains the Dockerfile<\/strong> and the directories to be copied.<\/p>\n
# docker build -t mynginx_image1 .<\/strong><\/code><\/pre>\n
Now we run this command to create a container called mynginx3<\/strong> based on the mynginx_image1<\/strong> image:<\/p>\n
# docker run --name mynginx3 -p 80:80 -d mynginx_image1<\/strong><\/code><\/pre>\n
If we want to make changes to the files in the container, we use a helper container as described in Option 3.<\/p>\n
Option 3 – Maintain Files in the Container<\/h4>\n
As mentioned in A Note About SSH<\/a>, we can’t use SSH to access the NGINX container, so if we want to edit the content or configuration files directly we have to create a helper container that\u00a0has shell access. For the helper container to have access to the files, we must create a new image that has the proper Docker data volumes<\/a> defined for the image. Assuming we want to copy files as in Option 2 while also defining volumes, we use the following Dockerfile<\/strong>:<\/p>\n
FROM nginx\r\nCOPY content \/usr\/share\/nginx\/html\r\nCOPY conf \/etc\/nginx\r\nVOLUME \/usr\/share\/nginx\/html\r\nVOLUME \/etc\/nginx<\/code><\/pre>\n
We then create the new\u00a0NGINX image by running the following command (again note the final period):<\/p>\n
# docker build -t mynginx_image2 .<\/strong><\/code><\/pre>\n
Now we run this command to create an NGINX container (mynginx4<\/strong>) based on the mynginx_image2<\/strong> image:<\/p>\n
# docker run --name mynginx4 -p 80:80 -d mynginx_image2<\/strong><\/code><\/pre>\n
We then run the following command to start a helper container mynginx4_files<\/strong> that has a shell, enabling us to access the content and configuration directories of the mynginx4<\/strong> container we just created:<\/p>\n
# docker run -i -t --volumes-from mynginx4 --name mynginx4_files debian \/bin\/bash<\/strong>\r\nroot@b1cbbad63dd1:\/#<\/code><\/pre>\n
The new\u00a0mynginx4_files<\/strong> helper container runs in the foreground with a\u00a0persistent standard input (the -i<\/code> option<\/span>) and a tty (the -t<\/code> option).<\/span> All volumes defined in mynginx4<\/strong>\u00a0are mounted as local directories in the helper container.<\/p>\n
The debian<\/code> argument means that the helper container uses the Debian image\u00a0from Docker Hub. Because the NGINX image also uses Debian (and all of our examples so far use the NGINX image), it is most efficient to use Debian for the helper container, rather than having Docker load another operating system. The \/bin\/bash<\/code> argument means that the bash<\/code> shell runs in the helper container, presenting a shell prompt that you can use to modify files as needed.<\/p>\n
To start and stop the container, run the following commands:<\/p>\n
# docker start mynginx4_files<\/strong>\r\n# docker stop mynginx4_files<\/strong><\/code><\/pre>\n
To exit the shell but leave the container running, press Ctrl+p<\/code> followed by Ctrl+q<\/code>. To regain shell access to a\u00a0running container, run this command:<\/p>\n
# docker attach mynginx4_files<\/strong><\/code><\/pre>\n
To exit the shell and terminate the container, run the exit<\/code> command.<\/p>\n
Note:<\/strong> As an alternative to the preceding commands, you can run the following command to open an interactive shell to a running NGINX container. However, we recommend this only for advanced users.<\/p>\n