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 user traffic.

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

Deploy NGINX Instance Manager 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
This pre-configured docker-compose.yaml file:
- Download docker-compose.yaml file .

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:

Download your NGINX Instance Manager subscription’s JSON Web Token from MyF5:
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.
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.

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

Usage

Navigate to the directory where you downloaded docker-compose.yaml. Run docker login and then docker compose up.

~$ 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

Alternatively, run docker login and then run the following make target command: make nim-compose-up.

~$ docker login private-registry.nginx.com --username=<JWT_CONTENTS> --password=none
~$ make nim-compose-up
Building nim bundled image in pipeline...
Building nim standalone image in pipeline...
Running nms-docker-images publish...
starting NIM via compose for development...
[+] 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 NIM 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 NIM license mode of operation to either connected or disconnected. Default is connected.

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:

    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