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:
Before you start
Legacy 'nms' references
Some commands, file paths, and configuration references still usenms
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. You can use the same JSON Web Token as NGINX Plus in your MyF5 portal.
- Log in to MyF5.
- Go to My Products & Plans > Subscriptions to see your active subscriptions.
- Find your NGINX products or services subscription, and select the Subscription ID for details.
- 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. -
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
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 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.
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