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.

Overview

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
  • Prompt you to enter your Docker login credentials you received from the NGINX Customer Portal
  • Ask you for a series of parameters including Database, SMTP, Admin user, and FQDN settings
  • Download the Docker images that make up NGINX Controller
  • 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 page.

Prerequisites

  • A license file for NGINX Controller, accessible at the NGINX Customer Portal
  • Docker login credentials for downloading the containers from the NGINX Docker registry, also 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
  • 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. Download the installer package to the location of your choosing.

    $ wget http://installer.ctrl.nginx.com/controller-installer-1.0.0.tar.gz
    
  2. Extract the installer files.

    $ tar xzf controller-installer-1.0.0.tar.gz
    
  3. Run the installer.

    cd controller-installer
    ./install.sh
    

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

    • Docker login username and password
    • Acceptance of the terms of use (type q to finish reading it, then y to accept)
    • Database settings
    • 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

    install prompt

    After a couple of minutes the system will be installed.

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

    login

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

    docs

  5. 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.

    license

  6. 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.

    instance

  7. API Documentation

    The REST API for NGINX Controller is documented at https://: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 helper.sh script found at /opt/nginx-controller/:

./helper.sh start
./helper.sh stop
./helper.sh restart

Updating

To update the NGINX Controller you download the new installer package when you have been notified there is an update available. It is important to ensure you have taken a backup of your database before performing an update.

e.g. To update to 1.0.1 from a previous version (e.g. 1.0.0), you download the new version and then update from that script

$ wget http://installer.ctrl.nginx.com/controller-installer-1.0.1.tar.gz

You then extract the package and run the update script

$ tar xzf controller-installer-1.0.1
$ cd controller-installer
$ ./update.sh

update

You will be prompted for your Docker login credentials again and prompted to remember to have backed up your database.

update_docker

The update script will then download and start the new version of the NGINX Controller.

update_download

Uninstalling

To uninstall run /opt/nginx-controller/uninstall.sh

uninstall

Troubleshooting

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:

    docker

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

logs

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