NGINX Documentation

Installing NGINX Controller

Thank you for purchasing NGINX Controller! This guide will help you download, install and run the system. The installation will result in a configured, working system ready to use to monitor and manage your NGINX Plus instances.


NGINX Controller is a web application, composed from a number of Docker containers, and an agent that runs next to your NGINX Plus instances.

To get started you will download and run the installer. This 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
  • Launch NGINX Controller

Open Source Software Dependencies

NGINX Controller uses a number of open source software packages in the product. The full list and the license for each package can be found on the Tech Spec page.


  • The controller-installer-<version>.tar.gz package, downloaded via the NGINX Customer Portal.
  • A license file for NGINX Controller, accessible at the NGINX Customer Portal.
  • A dedicated instance on which to install the NGINX Controller
    • Supported Operating Systems and recommended specifications can be found at specs:
    • Docker Community Edition (CE) 17.12.0 or later. For links to OS-specific installation instructions, see the Docker CE installation overview.
    • Docker Compose 1.18.0 or later. For OS-specific installation instructions, see the table in the Install Compose section of the Compose overview.
    • bash 4.0 or later
  • PostgreSQL 9.5
    • Database should be accessible from the controller server. You can use a DNS-resolvable name or IP address to connect to the database server (names in /etc/hosts are now allowed)
    • Create the user and database naas. User naas requires the Create DB permission.
  • The following Linux utilities are required by the installation script:
    • dig, grep, sed, wget, awk, curl, head, host, less, sort, sudo, tee

Installing NGINX Controller

To install the NGINX Controller, perform the following steps.

  1. After downloading the NGINX Controller installer package from NGINX Customer Portal, extract the files.

    $ tar xzf controller-installer-<version>.tar.gz
  2. Run the installer.

    cd controller-installer

    The install script will walk through a series of steps prompting you for input.

    • Acceptance of the terms of use (type q to finish reading it, then y to accept)
    • Database settings (you should configure your own Postgres 9.5 database and add the connection credentials in this step)
    • SMTP settings (used to invite new users via email)
    • Fully qualified domain name (FQDN) - a resolvable domain name for your NGINX Controller server, used to access NGINX Controller in the browser after installation
    • Admin email, password, organization name, first name, and last name
    • SSL/TLS certificates for running the web app over HTTPS; the installer can generate self-signed certs if you wish

    After a couple of minutes the system will be installed.

    Note: Please keep the NGINX Controller instance running.

  3. Log in to NGINX Controller at https://FQDN/login using the admin credentials you defined during the installation process.


    Documentation for NGINX Controller is embedded with the product, accessible at https://FQDN/docs


  4. Upload the NGINX Controller license provided by NGINX, Inc. It is accessible at the NGINX Customer Portal.

    Navigate to https://FQDN/account/license and click the Upload button to add your license file.


  5. Add the first NGINX Plus instance to monitor and manage, by installing the NGINX Controller agent software on the host where NGINX Plus is running.

    Click the New Instance button and follow the instructions in the pop-up window to connect to the NGINX Plus instance and run the provided command. After the agent is installed and initialized, it immediately starts sending metrics back to NGINX Controller, usually within a minute.


  6. API Documentation

    The REST API for NGINX Controller is documented at https://<your-controller>:5003/1.0/

  1. Cleanup

    You are free to delete the installer package that you downloaded and extracted

Managing the NGINX Controller Process

To start, stop, and restart the NGINX Controller process, use the script found at /opt/nginx-controller/:

./ start
./ stop
./ restart

Updating the NGINX Controller and Agent Software

To update the NGINX Controller software, download and run the corresponding installer package. You also need to update the agent software on each monitored NGINX Plus instance.

  1. Create a backup of the NGINX Controller database.

  2. Download the installer package through the NGINX Customer Portal

  3. Extract the installer files.

    $ tar xzf controller-installer-<version>.tar.gz
  4. Run the update script.

    $ cd controller-installer
    $ ./

    Like the installation script, the update script performs a series of steps.

    The script will prompt you to confirm that you have backed up the NGINX Controller database. Type the specified phrase.


    The update script downloads and starts the updated NGINX Controller software.


  5. If you are currently logged in to the NGINX Controller GUI in a browser, sign out and log in again. (To sign out, click on your username in the upper right‑hand corner and select Sign Out from the drop‑down menu.) For optimal performance, also flush your browser cache.

  6. Nginx Controller Agent:

    If using Ubuntu 18.04(bionic) run the following before starting the update:

    curl -fs -k http://<controller-server-FQDN>/packages-repository/nginx-signing.key | sudo apt-key add - &&  sudo apt-get --allow-releaseinfo-change update  

    Follow the same instructions as if you were installing a new agent, getting the install script from the Controller UI. If asked about replacing the current configuration file answer:

    N or O  : keep your currently-installed version


To uninstall run /opt/nginx-controller/



If NGINX Controller is not performing as you expect, verify the following:

  • The following configuration files are in in /opt/nginx-controller:

    • .controller.env
    • docker-compose.yml
    • controller-nginx.conf
    • certs/ (for the web app to run over HTTPS)
  • The output from the sudo docker ps command shows the following Docker containers:


In addition, the following log files for components of NGINX Controller are in /var/log/nginx-controller/:


For example, the coreapi files are for the main NGINX Controller API. The receiver files are logs from the agent.