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

Navigate to the directory where you downloaded docker-compose.yaml. With the following commands, use docker to log in to private-registry.nginx.com and then run docker compose up -d.

~$ docker login private-registry.nginx.com --username=<JWT_CONTENTS> --password=none
~$ echo "admin" > admin_password.txt
~$ docker compose up -d
[+] 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

You may modify the following variables in the docker-compose.yaml file:

  • NIM_LOG_LEVEL - set the NGINX Instance Manager logging level.
  • NIM_METRICS_TTL - set a custom time-to-live in days value for metrics retention.
  • NIM_EVENTS_TTL - set a custom time-to-live in days value for events retention.
  • NIM_SECURITY_TTL - set a custom time-to-live in days value for security violation retention.
  • NIM_MAINTENANCE - enable maintenance mode to preform backup, restore and troubleshooting.
  • NIM_WATCHDOG_TIMEOUT - set a custom dpm watchdog timeout in seconds.
  • NIM_LICENSE_MODE_OF_OPERATION - set the NGINX Instance Manager license mode of operation to either connected or disconnected. Default is connected.

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