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 in a single container
Single container deployment not suitable for production
This single container deployment is intended for demo purposes and small-scale deployments only. It is not recommended for production environments.
Overview
This guide will show you how to deploy and use F5 NGINX Instance Manager with Docker. The NGINX Instance Manager container is a single Docker image that includes all dependencies, making it easy to quickly set up NGINX Instance Manager with NGINX Open Source.
This deployment is ideal for:
- Product demos
- Instance counting
- Small-scale environments (20 instances or fewer)
By the end of this guide, you’ll be able to:
- Perform a quick test without persistent storage.
- Persist data to a volume.
- Set the admin password with an environment variable.
- Override self-signed API gateway certificates.
- Configure user access to the container using an
.htpasswd
file.
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.
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
Data persistence
- A single volume mount is required to persist the NGINX Instance Manager databases. For example:
--volume=/myvolume/nim:/data
- An optional volume can be used to add a custom
.htpasswd
file for admin and user authentication. For example:--volume=/myvolume/pass/.htpasswd:/.htpasswd
Supported environment variables
NMS_PERSIST_DISABLE
: Do not persist data to a volume. All data will be lost after the container stops or restarts.NMS_ADMIN_PASSWORD
: Set an admin password.NMS_APIGW_CERT
: Override the API gateway self-signed certificate.NMS_APIGW_KEY
: Override the API gateway self-signed key.NMS_APIGW_CA
: Override the API gateway self-signed CA.LOG_LEVEL
: Set the logging level for NGINX Instance Manager.
Build examples
Quick test without persistent storage
-
Run the following Docker command, replacing the placeholders with the appropriate values:
<HOSTNAME>
: desired hostname<ADMIN_PASSWORD>
: password for the admin account<VERSION_TAG>
: specific release version you want to use (note:latest
is not supported)
docker run -it --rm \ --hostname=<HOSTNAME> \ -e NMS_PERSIST_DISABLE \ -e NMS_ADMIN_PASSWORD="<ADMIN_PASSWORD>" \ -p 8443:443 \ private-registry.nginx.com/nms/nim-bundle:<VERSION_TAG>
Example:
To pull the NGINX Instance Manager 2.17.0 image, set the hostname to “mynim,” and set the admin password to “abc123!@”, run:
docker run -it --rm \ --hostname=mynim \ -e NMS_PERSIST_DISABLE \ -e NMS_ADMIN_PASSWORD="abc123\!@" \ -p 8443:443 \ private-registry.nginx.com/nms/nim-bundle:2.17.0
-
Upload the license:
- In a web browser, go to
https://<YOUR_HOST_IP>:8443
and log in. Replace<YOUR_HOST_IP>
with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, usehttps://localhost:8443
. - Select the Settings gear icon.
- On the Settings menu, select Licenses.
- Select Get Started.
- Select Browse to upload the license, or simply drag and drop the license onto the form.
- Select Add.
- In a web browser, go to
-
Close the browser to completely log off.
-
Stop and restart the container.
-
Log back in and verify that the license isn’t applied.
Set up persistent storage
-
Create or mount a directory for persistent storage to keep your data if the container restarts.
-
Run the following Docker command, replacing the placeholders with the appropriate values:
<HOSTNAME>
: desired hostname<ADMIN_PASSWORD>
: password for the admin account<DATA_VOLUME>
: path to the persistent data directory on the host machine<VERSION_TAG>
: specific release version you want to use (note:latest
is not supported)
docker run -it --rm \ --hostname=<HOSTNAME> \ -e NMS_ADMIN_PASSWORD="<ADMIN_PASSWORD>" \ --volume=<DATA_VOLUME>:/data \ -p 8443:443 \ private-registry.nginx.com/nms/nim-bundle:<VERSION_TAG>
Example:
To pull the NGINX Instance Manager 2.17.0 image, set the hostname to “mynim,” set the admin password to “abc123!@”, and write data to
~/nms_storage
, run:docker run -it --rm \ --hostname=mynim \ -e NMS_ADMIN_PASSWORD="abc123\!@" \ --volume=/myvolume/nim-storage:/data \ -p 8443:443 \ private-registry.nginx.com/nms/nim-bundle:2.17.0
-
Upload the license:
- In a web browser, go to
https://<YOUR_HOST_IP>:8443
and log in. Replace<YOUR_HOST_IP>
with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, usehttps://localhost:8443
. - Select the Settings gear icon.
- On the Settings menu, select Licenses.
- Select Get Started.
- Select Browse to upload the license, or simply drag and drop the license onto the form.
- Select Add.
- Select Done.
- In a web browser, go to
-
Close the browser to completely log off.
-
Stop and restart the container.
-
Log back in and verify that the license is still applied.
Override self-signed API gateway certificates
-
Ensure you have access to the required certificates:
mycert.pem
mykey.pem
myca.pem
-
Run the following Docker command, replacing the placeholders with the appropriate values:
<HOSTNAME>
: desired hostname<ADMIN_PASSWORD>
: password for the admin account<DATA_VOLUME>
: path to the persistent data directory on the host machine<VERSION_TAG>
: specific release version you want to use (Note:latest
is not supported)
docker run -it --rm \ --hostname=<HOSTNAME> \ -e NMS_ADMIN_PASSWORD="<ADMIN_PASSWORD>" \ -e NMS_APIGW_CERT="$(cat mycert.pem)" \ -e NMS_APIGW_KEY="$(cat mykey.pem)" \ -e NMS_APIGW_CA="$(cat myca.pem)" \ --volume=<DATA_VOLUME>:/data \ -p 8443:443 private-registry.nginx.com/nms/nim-bundle:<VERSION_TAG>
Example:
To pull the NGINX Instance Manager 2.17.0 image, set the hostname to “mynim,” use the password “abc123!@”, pass in the certificates
mycert.pem
,mykey.pem
, andmyca.pem
, and write data to/myvolume/nim-storage
, run:docker run -it --rm \ --hostname=mynim \ -e NMS_ADMIN_PASSWORD="abc123\!@" \ -e NMS_APIGW_CERT="$(cat mycert.pem)" \ -e NMS_APIGW_KEY="$(cat mykey.pem)" \ -e NMS_APIGW_CA="$(cat myca.pem)" \ --volume=/myvolume/nim-storage:/data \ -p 8443:443 \ private-registry.nginx.com/nms/nim-bundle:2.17.0
-
Log in and verify that the certificates are applied correctly.
In a web browser, go to
https://<YOUR_HOST_IP>:8443
and log in. Replace<YOUR_HOST_IP>
with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, usehttps://localhost:8443
.
Create and use an .htpasswd
file
In previous examples, the admin password was set using the NMS_ADMIN_PASSWORD
environment variable. You can also set passwords for the admin and other users using an .htpasswd
file.
-
Create an
.htpasswd
file on the host machine with an admin user. You will be prompted to enter a password:htpasswd -c .htpasswd admin
-
To add more user passwords, use one of the following commands depending on the desired hashing method:
Required: Create new users in the web interface
Additional users must be created using the web interface first. If users are added only to the.htpasswd
file and not in the web interface, they will not be able to log in. The web interface creates the users but doesn’t support adding passwords, while the.htpasswd
file adds the passwords but doesn’t create the users. For instructions on adding users using the web interface, see Creating Users.-
For MD5 hash:
htpasswd -m .htpasswd user1
-
For SHA hash:
htpasswd -s .htpasswd user2
Note:
NGINX does not support bcrypt password hashing. -
-
To pass the
.htpasswd
file at runtime, run the following command, replacing the placeholders with the appropriate values:<HOSTNAME>
: desired hostname<HTPASSWD_VOLUME>
: path to the directory containing the.htpasswd
file on the host machine<DATA_VOLUME>
: path to the persistent data directory on the host machine<VERSION_TAG>
: specific release version you want to use (Note:latest
is not supported)
docker run -it --rm \ --hostname=<HOSTNAME> \ --volume=<HTPASSWD_VOLUME>/.htpasswd:/.htpasswd \ --volume=<DATA_VOLUME>:/data \ -p 8443:443 private-registry.nginx.com/nms/nim-bundle:<VERSION_TAG>
Important:
The admin user must be included in the.htpasswd
file, or the container will not start.
Example:
To pull the NGINX Instance Manager 2.17.0 image, set the hostname to “mynim,” pass in the
/myvolume/nim-auth/.htpasswd
file, and write data to/myvolume/nim-storage
, run:docker run -it --rm \ --hostname=mynim \ --volume=/myvolume/nim-auth/.htpasswd:/.htpasswd \ --volume=/myvolume/nim-storage:/data \ -p 8443:443 private-registry.nginx.com/nms/nim-bundle:2.17.0
-
To copy an updated
.htpasswd
file to a running container, use the following command, replacing the placeholders with the appropriate values:<HTPASSWD_VOLUME>
: path to the directory containing the.htpasswd
file on the host machine<CONTAINER_NAME>
: name of the running container
docker cp <HTPASSWD_VOLUME>/.htpasswd <CONTAINER_NAME>:/data/local-auth/.htpasswd
Example:
docker cp /home/ubuntu/nim-auth/.htpasswd nginx-instance:/data/local-auth/.htpasswd
Tip: How to find a container's name
To find a container’s name, use thedocker ps
command, which lists all running containers along with their names. -
Verify you can log in with the provided usernames and passwords.
In a web browser, go to
https://<YOUR_HOST_IP>:8443
and log in. Replace<YOUR_HOST_IP>
with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, usehttps://localhost:8443
.