Important: NGINX Plus R33 requires NGINX Instance Manager 2.18 or later
To ensure uninterrupted traffic processing, upgrade to NGINX Instance Manager 2.18 or later if your NGINX data plane instances are running NGINX Plus R33. This upgrade is necessary to support usage reporting.

NGINX Plus R33 instances must send usage data to the F5 licensing endpoint or NGINX Instance Manager. If they don’t, they will stop processing traffic.

For more information about usage reporting and enforcement, see About solution licenses.

Deploy using Docker Compose

Overview

This guide will show you how to deploy and use F5 NGINX Instance Manager in Docker using Docker Compose.

This NGINX Instance Manager docker compose deployment is a single Docker image containing NGINX Instance Manager, Security Monitoring, and the latest App Protect compilers, which is orchestrated using a Docker Compose docker-compose.yaml definition.

The ClickHouse database is deployed in a separate container to improve resilience and make this a fault tolerant solution. You can also configure persistent storage

What you need

  • A working version of Docker
  • Your NGINX Instance Manager subscription’s JSON Web Token from MyF5 You can use the same JSON Web Token as NGINX Plus in your MyF5 portal.
  • This pre-configured docker-compose.yaml file:

Minimum requirements

Deploying NGINX Instance Manager with docker requires a minimum of 4 CPU cores and 4 GB of memory for basic use cases. However, every environment is unique, primarily due to variations in the NGINX configurations being managed. For instance, managing NGINX instances with hundreds of configuration files or those with WAF (NGINX App Protect) enabled can significantly increase resource demands.

If your use case is limited to usage tracking without active management or agent communication, the minimum requirements should suffice. For more complex deployments, we recommend reviewing the technical specifications guide to ensure the resources allocated are sufficient to handle an increased workload, particularly for the ClickHouse database, which may need to manage a higher volume of reads and writes.

Before you start

Legacy 'nms' references
Some commands, file paths, and configuration references still use nms due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.

Set up Docker for NGINX container registry

To set up Docker to communicate with the NGINX container registry located at private-registry.nginx.com, follow these steps:

  1. Download your NGINX Instance Manager subscription’s JSON Web Token from MyF5. You can use the same JSON Web Token as NGINX Plus in your MyF5 portal.

    1. Log in to MyF5.
    2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
    3. Find your NGINX products or services subscription, and select the Subscription ID for details.
    4. Download the JSON Web Token from the subscription page.

  2. Open the JSON Web Token file you downloaded from MyF5 and copy its contents.

    Copying the JWT token
    Make sure there are no extra characters or spaces when copying the contents of the JWT token: they can invalidate the token and cause 401 errors during authentication.

  3. Log in to the Docker registry using the contents of the JSON Web Token file:

    docker login private-registry.nginx.com --username=<JWT_CONTENTS> --password=none

Compose deployment

Configuring a forward proxy:
If you are configuring a forward proxy, follow the steps in the Forward Proxy Configuration Guide to modify docker-compose.yaml with the correct proxy settings before deploying NGINX Instance Manager.

Go to the directory where you downloaded docker-compose.yaml. Use the following commands to log in to private-registry.nginx.com and deploy NGINX Instance Manager.

docker login private-registry.nginx.com --username=<JWT_CONTENTS> --password=none
echo "admin" > admin_password.txt
docker compose up -d

If the deployment succeeds, you’ll see output similar to this:

[+] Running 6/6
 ✔ Network nim_clickhouse        Created   0.1s
 ✔ Network nim_external_network  Created   0.2s
 ✔ Network nim_default           Created   0.2s
 ✔ Container nim-precheck-1      Started   0.8s
 ✔ Container nim-clickhouse-1    Healthy   6.7s
 ✔ Container nim-nim-1           Started   7.4s

Supported environment variables

Variable Category Description
NIM_LOG_LEVEL General Sets the logging level for NGINX Instance Manager.
NIM_METRICS_TTL General Specifies the number of days to retain metrics.
NIM_EVENTS_TTL General Specifies the number of days to retain event logs.
NIM_SECURITY_TTL General Specifies the number of days to retain security violation logs.
NIM_MAINTENANCE General Enables maintenance mode for backup, restore, and troubleshooting (true or false).
NIM_WATCHDOG_TIMEOUT General Sets the timeout (in seconds) for the Data Plane Monitoring (DPM) watchdog.
NIM_LICENSE_MODE_OF_OPERATION General Sets the license mode to either connected (default) or disconnected.
PROXY_ENABLE Forward Proxy Enables or disables the use of a forward proxy (true or false).
PROXY_HOST Forward Proxy The IP address or hostname of the proxy server.
PROXY_PORT Forward Proxy The port number of the proxy server.
PROXY_PROTOCOL Forward Proxy The proxy protocol (http or https).
PROXY_AUTH_REQUIRED Forward Proxy Specifies whether authentication is required for the proxy (true or false).
PROXY_USERNAME Forward Proxy (Required if PROXY_AUTH_REQUIRED=true) The username for proxy authentication.
PROXY_PASSWORD Forward Proxy (Required if PROXY_AUTH_REQUIRED=true) The password for proxy authentication.
PROXY_SSL_VERIFY Forward Proxy Enables or disables SSL verification when PROXY_PROTOCOL=https. Default is true, meaning the proxy must have a valid certificate issued by a trusted Certificate Authority (CA). Set to false to allow self-signed or untrusted certificates (not recommended).

See also:
For details on configuring a forward proxy, see the Forward Proxy Configuration Guide.

Compose stop or tear down

Navigate to the directory where you downloaded docker-compose.yaml. If you started NIM with docker compose up -d, stop NIM services once you’ve finished with them by running docker compose stop. You can bring everything down, removing the containers entirely, with the docker compose down command.

docker compose down
[+] Running 6/6
 ✔ Container nim-nim-1           Removed   30.6s
 ✔ Container nim-clickhouse-1    Removed    1.4s
 ✔ Container nim-precheck-1      Removed    0.0s
 ✔ Network nim_default           Removed    0.9s
 ✔ Network nim_external_network  Removed    0.4s
 ✔ Network nim_clickhouse        Removed    0.6s

Secrets

In the same docker-compose.yaml file, you can modify the following credentials:

Set the admin password (required)

secrets:
  nim_admin_password:
    file: admin_password.txt

Pass a custom .htpasswd file (Optional)

  nim_credential_file:
    file: nim_creds.txt

Optionally, you can also set the external SSL certificate, key, and CA files, in PEM format for the NGINX Instance Manager Ingress proxy.

secrets:
  nim_proxy_cert_file:
    file: ./certs/nim_cert.pem
  nim_proxy_cert_key:
    file: ./certs/nim_key.pem
  nim_proxy_ca_cert:
    file: ./certs/nim_ca.pem

Backup

Once you’ve set up your Docker containers, use the following command to back them up:

~$ docker exec nim-nim-1 nim-backup
...
Backup has been successfully created: /data/backup/nim-backup-<date>.tgz

If your system uses named volumes, inspect the Mountpoint. Alternatively, if you’re using a shared NFS volume, then collect the data directly from the mount point.

~/compose$ docker inspect volume nim_nim-data | jq '.[0].Mountpoint'
"/var/lib/docker/volumes/nim_nim-data/_data"
ubuntu@ip-<address>:~/compose$ sudo ls -l /var/lib/docker/volumes/nim_nim-data/_data/backup
-rw-r--r-- 1 root root 5786953 Sep 27 02:03 nim-backup-<date>.tgz

Restore

Before you can restore a backup, set your containers to maintenance mode in the same docker-compose.yaml file:

    environment:
      NIM_MAINTENANCE: "true"
~$ docker exec nim-nim-1 nim-restore /data/backup/nim-backup-<date>.tgz
...
NGINX Instance Manager has been restored.

Once the process is complete set NIM_MAINTENANCE to false and then run docker-compose up -d.

Storage

By default, the storage uses named volumes. Alternatively, you can use optional driver_opts settings to support other storage formats such as NFS. For all storage volumes, make sure to mount them, before running docker compose up -d. For a mounted NFS volume, you might use the following commands:

~$ sudo mount -t nfs <<nfs-ip>>:/mnt/nfs_share/clickhouse /mnt/nfs_share/clickhouse
~$ sudo mount -t nfs <<nfs-ip>>:/mnt/nfs_share/data /mnt/nfs_share/data
volumes:
  # By default docker compose will create a named volume 
  # Refer to https://docs.docker.com/reference/compose-file/volumes/ for additional storage options such as NFS 
  nim-data:
    driver: local
    driver_opts:
      type: "nfs"
      o: "addr=<<nfs-ip>>,rw"
      device: ":/mnt/nfs_share/data"
  clickhouse-data:
    driver: local
    driver_opts:
      type: "nfs"
      o: "addr=<<nfs-ip>>,rw"
      device: ":/mnt/nfs_share/clickhouse"

Support Data

In case of problems, it’s a good practice to:

  • Collect logs docker-compose logs --since 24h > my-logs-$(date +%Y-%m-%d).txt
  • Collect backup information docker exec nim-nim-1 nim-backup