Deploy NGINX Instance Manager in a Single Docker Container

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

Before You Start

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 and license from MyF5.
- Log in to the MyF5 customer portal.
- Go to My Products and Plans > Subscriptions.
- Select the product subscription.
- Download the JSON Web Token and license files.
Open the JSON Web Token file you downloaded from MyF5 and copy its contents.

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, use https://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.
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 a 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, use https://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.
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