Install Nginx In Docker

  1. Install Nginx In Docker Ubuntu
  2. Install Nginx Docker Ubuntu 18.04
  3. Install Nginx-extras In Docker
  4. Install Nginx In Alpine Docker

This guide explains how to install and update NGINX Controller.

Overview

NGINX Controller is NGINX’s control-plane solution that manages the NGINX data plane. Built on a modular architecture, NGINX Controller enables you to manage the entire lifecycle of NGINX Plus, whether it’s deployed as a load balancer, API gateway, or a proxy in a service mesh environment.

Docker run -name docker-nginx-new -p 8080:80 -e TERM=xterm -d nginx Now when you enter the container, you can install your editor of choice and actually work with it. Containers made easy. Install Nginx On Ubuntu Docker Container In the root of the project is a Docker Compose file that will start both our frontend and backend services. Let’s start up our application and test if the reverse proxy is working correctly. Tutorial Nginx - Testing the Docker installation Open your browser and enter the IP address of your web server. In our example, the following URL was entered in the Browser.

To get started, download and run the installer. The installer will:

  • Perform prerequisite checks on your system and prompt for any missing dependencies.
  • Prompt you to accept the terms of service agreement for NGINX Controller.
  • Ask you for a series of parameters including Database, SMTP, Admin user, and FQDN settings.
  • Place configuration and log files in appropriate file locations on your host system.
  • Add extra repositories to the default package manager like apt or yum and install required packages.
  • Launch NGINX Controller.

Open Source Software Dependencies

NGINX Controller uses a number of open source software packages in the product. You can find information about these dependencies in the NGINX Controller Technical Specifications.

Before You Begin

Before installing NGINX Controller, review the following prerequisites.

Important:
NGINX Controller should be deployed on a secure, internal network only. We strongly recommend against exposing the NGINX Controller API to the internet.

Things you’ll need before installing NGINX Controller:

  • The controller-installer-<version>.tar.gz package, downloaded from the MyF5 Customer Portal;

  • A license file for NGINX Controller, accessible via the MyF5 Customer Portal;

  • A dedicated environment (bare metal, VM, or cloud-hosted instance) on which to install NGINX Controller. For the supported Operating Systems and recommended specifications, see the NGINX Controller Technical Specifications guide;

Install NGINX Controller Prerequisites

You can use the NGINX Controller helper.sh prereqs command to install the required system packages and Docker CE.

OptionsDescription
baseInstall the required Linux utilities.
dockerInstall Docker CE.
nfsInstall NFS system packages.

To install all of the NGINX Controller prerequisites for your system at the same time, take the following steps:

  1. Download the NGINX Controller installer package from the MyF5 Customer Portal.

  2. Extract the installer package files:

  3. Run the helper script with the prereqs option:

Note:

After you’ve installed NGINX Controller, you can install any of the prerequisites by running the following command:

Linux Utilities

The following Linux utilities are required by the installation script. The script will let you know if any of the utilities are missing.

  • awk
  • bash (4.0 or later)
  • conntrack
  • coreutils: base64, basename, cat, comm, dirname, head, id, mkdir, numfmt, sort, tee
  • curl or wget
  • ebtables
  • envsubst (provided by the gettext package)
  • ethtool
  • getent
  • grep
  • gunzip (provided by the gzip package)
  • iproute
  • iptables
  • jq (1.5 or later)
  • less
  • openssl
  • sed
  • socat
  • tar
  • util-linux
  • yum-plugin-versionlock on RedHat/CentOS

Docker Requirements

If you have Internet access, NGINX Controller will install Docker for you as part of the installation process.

If you prefer to install Docker on the host yourself, install the following:

  • Docker Community Edition (CE) 18.09
  • Containerd.io 1.2.10

If you are using Ubuntu-20.04 and want to install Docker on your own, choose the following versions instead:

  • Docker Community Edition (CE) 19.03
  • Containerd.io 1.2.13
See Also:
For instructions on installing Docker in offline scenarios on CentOS/RHEL 7, refer to the AskF5 K84431427 knowledge base article.
Important:
You need to enable Docker log rotation to ensure that the logs don’t consume all the free disk space on the server. For instructions on how to enable Docker log rotation, see the Docker guides How to set up log rotation post installation and JSON File logging driver.

Red Hat Enterprise Linux

To create container images on Red Hat Enterprise Linux, Red Hat requires you to register and entitle the host computer on which you’ll build them. In this case, the host is where you’re installing NGINX Controller. Once the host is registered with Red Hat, you can install Docker from the Red Hat Enterprise Linux Extras repository. See the Red Hat “Getting Started with Containers” guide for instructions.

Install Nginx In Docker Ubuntu

Kubernetes Requirements

NGINX Controller ships with a required version of Kubernetes and will install Kubernetes for you. Be sure to install NGINX Controller on a dedicated node that does not already have Kubernetes configured.

The following table lists the Kubernetes versions that are installed by NGINX Controller:

NGINX ControllerKubernetes
v3.xv1.15.5

The Kubernetes Pod DNS config has a limit of six configured DNS search domain names. This is also the glibc limit.

In NGINX Controller, Core-DNS creates three search domains that are determined at run-time and not in /etc/resolv.conf:

  • <namespace>.svc.cluster.local
  • svc.cluster.local
  • cluster.local <any host resolv.conf search paths>

In general, changing the settings in NGINX Controller’s underlying Kubernetes cluster is not recommended. However, if you do change the cluster’s Pod config to allow additional search domains, you should not add more than three domains.

PostgreSQL (Optional)

When installing NGINX Controller, you can choose to have NGINX Controller install and manage a self-hosted – also known as “embedded” – PostgreSQL config database for you; this is the recommended implementation. If you choose to use the embedded, self-hosted config database, you can skip this section.

Alternatively, you can install your own PostgreSQL database for the config database, which you manage; this is sometimes referred to as an “external config database” because it is externally managed by you. Continue reading if you’re providing your own PostgreSQL database.

Refer to the AskF5 KB article K49481224 for instructions on how to install PostgreSQL on CentOS 7 and Ubuntu 18.04 for use with NGINX Controller.

  • NGINX Controller supports the following versions of PostgreSQL:

    • PostgreSQL 12.x – works with NGINX Controller 3.9 and later.
    • PostgreSQL 9.5 – works with NGINX Controller 3.0 and later.
  • The PostgreSQL database must be accessible from the NGINX Controller server. You can use a DNS-resolvable name or an IP address to connect to the database server (names in /etc/hosts are not allowed).

  • Create the user with the Create DB permission.

  • Configure PostgreSQL to allow SSL connections; client certificates should also be used for user authentication.

    We strongly discourage disabling SSL for PostgreSQL for security reasons. Consult the Secure TCP/IP Connections with SSL topic in the PostgreSQL manual for instructions and details:

  • When installed on external NFS or EFS volumes, the config database should support a throughput of 2 MiB/s or greater.

Install NGINX Controller

Install NGINX Controller on a dedicated node that does not already have Kubernetes configured. NGINX Controller does not support pre-configured Kubernetes implementations at this time. The installer for NGINX Controller will install and configure Kubernetes for you.

Important:
Before installing NGINX Controller, you must disable swap on the host; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article K82655201 and the kubeadm installation guide in the Kubernetes documentation.

To install NGINX Controller, take the following steps:

  1. Download the NGINX Controller installer package from the MyF5 Customer Portal.

  2. Extract the installer package files:

  3. Run the install script:

    Note:
    Installing NGINX Controller as root is not allowed. Run install script as a non-root user with sudo privileges.
    Note:
    If an HTTPS proxy is configured for the whole system, you should disable the proxy for the IP address and hostname of the host that you’re running the NGINX Controller install script on.For example, run the command export NO_PROXY=<current_ip>,<current_hostname>.

    The installation script walks through a series of steps and asks for the following input:

    • Config database configuration. Specify whether to use an embedded, self-hosted PostgreSQL database for the config database, or if you want to provide your own external PostgreSQL database. If you choose to provide your own database, make sure you’ve reviewed the PostgreSQL prerequisites.

    • Config database volume type: Specify the type of volume to use to store the config database: local, NFS, or AWS. We recommend choosing local only for demo and trial purposes.

      See Also:
      Refer to the NGINX Controller Technical Specifications Guide for more information about the volume options and requirements.
    • Analytics database volume type: Specify the type of volume to use to store the analytics database: local, NFS, or AWS. We recommend choosing local for demo and trial purposes.

    • EULA: Read the end-user license agreement. Type either y to accept or n to exit.

    • SMTP

      • SMTP Host: Provide the host name or IP address of an SMTP server. This is used to send password recovery emails. For trial purposes, if you don’t need to receive these communications, you can enter a value of “example.com” or something similar.
      • SMTP Port: The port of the SMTP server.
      • SMTP Authentication: Select y or n to authenticate when connecting to the SMTP server.
      • Use TLS for SMTP Communication: Select y or n to use SSL for SMTP server connections.
      • Do not reply email address: The sender’s email address. For example, [email protected].
    • Admin

      • First name: The first name for the initial admin user.
      • Last name: The last name for the initial admin user.
      • Email address: The contact email address for the initial admin user.
      • Password: The initial admin’s password. Passwords must be 6-64 characters long and must include letters and digits.
    • FQDN: Fully qualified domain name (FQDN) – a resolvable domain name for the NGINX Controller server. The FQDN is used by Controller Agents when connecting to NGINX Controller.

      Note:
      We recommend setting the FQDN to a internal address when possible, to avoid exposing the traffic between the Agent and NGINX Controller. This also reduces the external traffic in cloud environments.
    • SSL/TLS certificates: Type y to generate and use self-signed certs for running NGINX Controller over HTTPS, or type n to provide your own certs.

      Important:
      If you provide your own SSL/TLS certificates, you’ll need a complete certificate chain file, with the intermediate CA cert appended to the server cert; the server certificate must appear before the chained certificates in the combined file.
  4. Log in to the NGINX Controller browser interface by navigating to the DNS, FQDN, or IP address of the NGINX Controller host, for example, https://<Controller-FQDN>/login. Use the admin email address and password that you provided during the installation process.

  5. Once the NGINX Controller installation has completed, you may safely delete the installer package that you downloaded and extracted.

License NGINX Controller

To add a license to NGINX Controller, take the following steps:

  1. Go to https://<Controller-FQDN>/platform/license and log in.

  2. In the Upload a license section, select an upload option:

    • Upload license file – Locate and select your license file in the file explorer.
    • Paste your Association Token or license file – Paste your customer Association Token or the contents of your NGINX Controller license file. These are available on the MyF5 Customer Portal.
  3. Select Save license.

See Also:
To add a license using the NGINX Controller REST API, send a PUT request to the /platform/license endpoint. Provide your CAT or NGINX Controller license as a base64-encoded string in the JSON request body.

Back Up Cluster Config and Encryption Keys

After installing NGINX Controller, you should back up the cluster config and encryption keys. You’ll need these if you ever need to restore the NGINX config database on top of a new NGINX Controller installation.

  • To back up the NGINX Controller cluster configuration and encryption keys:

    The file is saved to /opt/nginx-controller/cluster-config.tgz.

  • To restore the cluster’s config and encryption keys, take the following steps:

Manage the NGINX Controller Process

You can use the helper.sh script to start, stop, restart, and check the status of the NGINX Controller process.

Update NGINX Controller

To update the NGINX Controller software, take the steps below. When complete, you must also update the Controller Agent software on each monitored NGINX Plus instance.

Caution:

We strongly recommend that you make a backup of the following information before proceeding, to avoid potential data and/or configuration loss:

  • Back up the NGINX Controller databases.

  • Back up the NGINX Controller cluster configuration and encryption keys. These are required if you need to restore the config database on top of a new installation of NGINX Controller.

  • Back up the Controller Agent agent.conf file by copying it from its current location to a new location. This file is present on each NGINX Plus instance.

  1. Download the installer package from the MyF5 Customer Portal.

  2. Extract the installer package files:

  3. Before updating, check the NGINX Controller status to confirm the installation is healthy.

    Resolve any degradations before updating.

  4. Run the update script:

    Note:
    If you’re upgrading from an older version of NGINX Controller and you installed Controller as root user, use --allow-with-root flag when running an update script.
  5. If you are logged in to NGINX Controller using a web browser, sign out and log in again.

    • To sign out, select your username in the upper right-hand corner, and then select “Sign Out”. For optimal performance, also flush your browser cache.
Important:
After you upgrade NGINX Controller, you also need to update the NGINX Controller Agent to the latest version.

Uninstall NGINX Controller

To uninstall NGINX Controller, run the uninstall script:

Install NGINX Controller Agent

See Also:
If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the Install NGINX Controller Agent for Non-root User guide instead of the steps provided in this section.

Install the Controller Agent on each NGINX Plus instance that you want to manage and monitor.

Take the following steps to add an instance to NGINX Controller:

  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Infrastructure.

  3. On the Infrastructure menu, select Instances > Overview.

  4. On the Instances overview page, select Create.

  5. On the Create Instance page, select Add an existing instance.

  6. Add a name for the instance. If you don’t provide a name, the hostname of the instance is used by default.

  7. To add the instance to an existing Instance Group, select an Instance Group from the list. Or to create an Instance Group, select Create New.

  8. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select Create New.

    Important:
    Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must remove the instance from NGINX Controller, and then add it back.
  9. (Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select Allow insecure server connections to NGINX Controller using TLS. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible.

  10. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller.

  11. Run the curl or wget command that’s shown in the Installation Instructions section on the NGINX instance to download and install the Controller Agent package. When specified, the -i and -l options for the install.sh script refer to the instance name and Location, respectively.

    Note:

    Make sure you enter the commands to download and run the install.sh script on the NGINX Plus system, and not on the NGINX Controller.

    NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You’ll be prompted to install Python if it’s not installed already. Python is not required for NGINX Controller v3.7 and later.

After a few minutes, the NGINX instance will appear on the Instances overview page.

Troubleshooting

If NGINX Controller isn’t working how you expect, see the knowledge base article K03263142 for installation troubleshooting procedures.

Create a Support Package

You can create a support package for NGINX Controller that you can use to diagnose issues.

Note:
You will need to provide a support package if you open a ticket with NGINX Support via the MyF5 Customer Portal.
OptionsDescription
-o--outputSave the support package file to <file name>.
-s--skip-db-dumpDon’t include the database dump in the support package.
-t--timeseries-dump <hours>Include the last <n hours> of timeseries data in the support package (default 12 hours).

Take the following steps to create a support package:

  1. Open a secure shell (SSH) connection to the NGINX Controller host and log in as an administrator.

  2. Run the helper.sh utility with the supportpkg option:

    The support package is saved to:

    /var/tmp/supportpkg-<timestamp>.tar.gz

    For example:

    /var/tmp/supportpkg-20200127T063000PST.tar.gz

  3. Run the following command on the machine where you want to download the support package to:

Support Package Details

The support package is a tarball that includes NGINX Controller configuration information, logs, and system command output. Sensitive information, including certificate keys, is not included in the support package.

The support package gathers information from the following locations:

​ ​​​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​​

This documentation applies to the following versions of NGINX Controller: 3.0, 3.1, 3.2, 3.3, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.

​ ​​​ ​ ​ ​ ​​

This documentation applies to the following versions of NGINX Controller API Management module: 3.18, 3.18.1 and 3.19.

​ ​​​ ​ ​​

This documentation applies to the following versions of NGINX Controller App Delivery module: 3.20.

Deploy NGINX and NGINX Plus as the Docker container.

NGINX Plus, the high‑performance application delivery platform, load balancer, and web server, is available as the Docker container.

Prerequisites

  • Docker installation
  • Docker Hub account (NGINX Open Source)
  • nginx-repo.crt and nginx-repo.key files, Dockerfile for Docker image creation (NGINX Plus)

Running NGINX Open Source in a Docker Container

You can create an NGINX instance in a Docker container using the NGINX Open Source image from the Docker Hub.

  1. Launch an instance of NGINX running in a container and using the default NGINX configuration with the following command:

    where:

    • mynginx1 is the name of the created container based on the NGINX image

    • the -d option specifies that the container runs in detached mode: the container continues to run until stopped but does not respond to commands run on the command line.

    • the -p option 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, the second parameter is mapped to the port exposed in the container

    The command returns the long form of the container ID: fcd1fb01b14557c7c9d991238f2558ae2704d129cf9fb97bb4fadf673a58580d. This form of ID is used in the name of log files.

  2. Verify that the container was created and is running with the docker ps command:

This command also allows viewing the port mappings set in the previous step: the PORTS field in the output reports that port 80 on the Docker host is mapped to port 80 in the container.

Running NGINX Plus in a Docker Container

Docker can also be used with NGINX Plus. The difference between using Docker with NGINX Open Source is that you first need to create an NGINX Plus image, because as a commercial offering NGINX Plus is not available at Docker Hub.

Note: Never upload your NGINX Plus images to a public repository such as Docker Hub. Doing so violates your license agreement.

Creating NGINX Plus Docker Image

To generate an NGINX Plus image:

  1. Create the Docker build context, or a Dockerfile:

  2. As with NGINX Open Source, default NGINX Plus image has the same default settings:

    • access and error logs are linked to the Docker log collector
    • no volumes are specified: a Dockerfile can be used to create base images from which you can create new images with volumes specified, or volumes can be specified manually:
    • no files are copied from the Docker host as a container is created: you can add COPY definitions to each Dockerfile, or the image you create can be used as the basis for another image
  3. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files. For a trial of NGINX Plus, the files are provided with your trial package.

  4. Copy the files to the directory where the Dockerfile is located.

  5. Create a Docker image, for example, nginxplus (note the final period in the command).

    The --no-cache option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus. If the Dockerfile was previously used to build an image without the --no-cache option, the new image uses the version of NGINX Plus from the previously built image from the Docker cache.

  6. Verify that the nginxplus image was created successfully with the docker images command:

  7. Create a container based on this image, for example, mynginxplus container:

  8. Verify that the mynginxplus container is up and running with the docker ps command:

NGINX Plus containers are controlled and managed in the same way as NGINX Open Source containers.

Managing Content and Configuration Files

Content served by NGINX and NGINX configuration files can be managed in several ways:

  • files are maintained on the Docker host
  • files are copied from the Docker host to a container
  • files are maintained in the container

Maintaining Content and Configuration Files on the Docker Host

Install

When the container is created, you can 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 as the container’s root directory and puts configuration files in /etc/nginx. For a Docker host with content in the local directory /var/www and configuration files in /var/nginx/conf, run the command:

Any change made to the files in the local directories /var/www and /var/nginx/conf on the Docker host are reflected in the directories /usr/share/nginx/html and /etc/nginx in the container. The readonly option means these directories can be changed only on the Docker host, not from within the container.

Copying Content and Configuration Files from the Docker Host

Docker can copy the content and configuration files from a local directory on the Docker host during container creation. Once a container 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 with commands that are run during generation of a new Docker image based on the NGINX image. For the file‑copy (COPY) commands in the Dockerfile, the local directory path is relative to the build context where the Dockerfile is located.

Let’s assume that the content directory is content and the directory for configuration files is conf, both subdirectories of the directory where the Dockerfile is located. The NGINX image has the default NGINX configuration files, including default.conf, in the /etc/nginx/conf.d directory. To use the configuration files from the Docker host only, delete the default files with the RUN command:

Create NGINX image by running the command from the directory where the Dockerfile is located. The period (“.”) at the end of the command defines the current directory as the build context, which contains the Dockerfile and the directories to be copied:

Create a container mynginx3 based on the mynginx_image1 image:

To make changes to the files in the container, use a helper container as described in the next section.

Maintaining Content and Configuration Files in the Container

As SSH cannot be used to access the NGINX container, to edit the content or configuration files directly you need to create a helper container that has shell access. For the helper container to have access to the files, create a new image that has the proper Docker data volumes defined for the image:

  1. Copy nginx content and configuration files and define the volume for the image with the Dockerfile:

  2. Create the new NGINX image by running the following command:

  3. Create an NGINX container mynginx4 based on the mynginx_image2 image:

  4. Start a helper container mynginx4_files that has a shell, providing access the content and configuration directories of the mynginx4 container we just created:

    where:

    • the new mynginx4_files helper container runs in the foreground with a persistent standard input (the -i option) and a tty (the -t option). All volumes defined in mynginx4 are mounted as local directories in the helper container.
    • the debian argument means that the helper container uses the Debian image from Docker Hub. Because the NGINX image also uses Debian, it is most efficient to use Debian for the helper container, rather than having Docker load another operating system
    • the /bin/bash argument means that the bash shell runs in the helper container, presenting a shell prompt that you can use to modify files as needed

To start and stop the container, run the commands:

To exit the shell but leave the container running, press Ctrl+p followed by Ctrl+q. To regain shell access to a running container, run this command:

To exit the shell and terminate the container, run the exit command.

Managing Logging

You can use default logging or customize logging.

Using Default Logging

By default, the NGINX image is configured to send NGINX access log and error log to the Docker log collector. This is done by linking them to stdout and stderr: all messages from both logs are then written to the file /var/lib/docker/containers/container-ID/container-ID-json.log on the Docker host. The container‑ID is the long‑form ID returned when you create a container. To display the long form ID, run the command:

You can use both the Docker command line and the Docker Engine API to extract the log messages.

To extract log messages from the command line, run the command:

To extract log messages using the Docker Remote API, send a GET request using the Docker Unix sock:

To include only access log messages in the output, include only stdout=1. To limit the output to error log messages, include only stderr=1. For other available options, see Get container logs section of the Docker Engine API documentation.

Nginx

Using Customized Logging

If you want to configure logging differently for certain configuration blocks (such as server {} and location {}), define a Docker volume for the directory in which to store the log files in the container, create a helper container to access the log files, and use any logging tools. To implement this, create a new image that contains the volume or volumes for the logging files.

Install Nginx Docker Ubuntu 18.04

For example, to configure NGINX to store log files in /var/log/nginx/log, add a VOLUME definition for this directory to the Dockerfile (provided that content and configuration Files are managed in the container):

Then you can create an image and use it to create an NGINX container and a helper container that have access to the logging directory. The helper container can have any desired logging tools installed.

Install Nginx-extras In Docker

Controlling NGINX

Since there is no direct access to the command line of the NGINX container, NGINX commands cannot be sent to a container directly. Instead, signals can be sent to a container via Docker kill command.

To reload the NGINX configuration, send the HUP signal to Docker:

Install Nginx In Alpine Docker

To restart NGINX, run this command to restart the container: