Deploy using Docker Compose

Overview

This guide shows you how to run NGINX Instance Manager using Docker Compose.

You can deploy it in two ways:

  • Standard mode includes full metrics and dashboards. This setup runs ClickHouse in a separate container.
  • Lightweight mode (new in 2.20.0) skips ClickHouse entirely. It’s ideal if you don’t need monitoring data or want a simpler setup. This reduces system requirements and avoids the work of managing a metrics database. You can add ClickHouse later if your needs change.

Both modes use a pre-built Docker image that includes NGINX Instance Manager, Security Monitoring, and the latest NGINX App Protect compilers.

If you use the standard setup, ClickHouse runs in its own container. This helps with fault tolerance and keeps data separate. You can also use persistent storage.

What you need

Before you begin, make sure you have the following:

Note: If you’re not sure which one to use, start with lightweight mode. You can always switch later by changing the Compose file and setting ENABLE_METRICS: "true".

Minimum requirements

Your system needs enough resources to run NGINX Instance Manager based on the mode you choose:

Deployment mode CPU cores Memory ClickHouse required
Standard 4 4 GB Yes
Lightweight (Lower) (Lower) No

Standard mode requires a minimum of 4 CPU cores and 4 GB of memory. This setup includes ClickHouse, which handles metrics and dashboards. Depending on your NGINX footprint, you may need more resources, especially for environments with many configuration files or NGINX App Protect enabled.

Lightweight mode removes ClickHouse, which lowers memory and CPU usage. While there’s no official minimum, users with basic instance management needs may see success with fewer resources. Test in your environment before committing to a smaller footprint.

Note: If you’re not sure which mode to use, start with lightweight mode. It’s easier to set up, and you can switch to standard mode later by reintroducing ClickHouse.

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.

Log in to the NGINX container registry

Both standard and lightweight deployments use a private image hosted at private-registry.nginx.com. You need to log in before running Docker Compose.

To set up Docker to communicate with the NGINX container registry:

  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

Deploy NGINX Instance Manager

If you’re using a forward proxy, update the Compose file before deploying. Follow the steps in the Forward Proxy Configuration Guide.

Go to the directory where you downloaded your docker-compose.yaml file, and run the following commands:

docker login private-registry.nginx.com --username=<JWT_CONTENTS> --password=none
echo "admin" > admin_password.txt
docker compose up -d

The deployment output will vary depending on the mode:

Standard mode (with metrics) 

[+] Running 6/6
 ✔ Network nim_clickhouse        Created
 ✔ Network nim_external_network  Created
 ✔ Network nim_default           Created
 ✔ Container nim-precheck-1      Started
 ✔ Container nim-clickhouse-1    Healthy
 ✔ Container nim-nim-1           Started

Lightweight mode (no ClickHouse) 

[+] Running 3/3
 ✔ Network nim_default           Created
 ✔ Network nim_external_network  Created
 ✔ Container nim-nim-1           Started

In lightweight mode, only the NGINX Instance Manager service runs. ClickHouse and related containers are removed by design.

Supported environment variables

You can control Instance Manager behavior by setting environment variables in the docker-compose.yaml file. Here’s a summary of commonly used variables:

Variable Category Description
ENABLE_METRICS General Enables or disables metrics collection and storage. Set to false to run in lightweight mode without ClickHouse. Defaults to true.
NIM_MAINTENANCE General Enables maintenance mode for backup, restore, and troubleshooting (true or false).
NIM_LICENSE_MODE_OF_OPERATION General Sets the license mode to either connected (default) or disconnected.
NIM_LOG_LEVEL General Sets the logging level for NGINX Instance Manager.
NIM_METRICS_TTL General Specifies the number of days to retain metrics.
NIM_EVENTS_TTL General Specifies the number of days to retain event logs.
NIM_SECURITY_TTL General Specifies the number of days to retain security violation logs.
NIM_WATCHDOG_TIMEOUT General Sets the timeout (in seconds) for the Data Plane Monitoring (DPM) watchdog.
PROXY_ENABLE Forward Proxy Enables or disables the use of a forward proxy (true or false).
PROXY_HOST Forward Proxy The IP address or hostname of the proxy server.
PROXY_PORT Forward Proxy The port number of the proxy server.
PROXY_PROTOCOL Forward Proxy The proxy protocol (http or https).
PROXY_AUTH_REQUIRED Forward Proxy Specifies whether authentication is required for the proxy (true or false).
PROXY_USERNAME Forward Proxy (Required if PROXY_AUTH_REQUIRED=true) The username for proxy authentication.
PROXY_PASSWORD Forward Proxy (Required if PROXY_AUTH_REQUIRED=true) The password for proxy authentication.
PROXY_SSL_VERIFY Forward Proxy Enables or disables SSL verification when PROXY_PROTOCOL=https. Default is true, meaning the proxy must have a valid certificate issued by a trusted Certificate Authority (CA). Set to false to allow self-signed or untrusted certificates (not recommended).

Stop or remove services

To stop NGINX Instance Manager, go to the directory where you downloaded your docker-compose.yaml file.

If you used docker compose up -d to start services:

  • Run docker compose stop to pause the containers
  • Run docker compose down to remove them completely
docker compose down

The shutdown output will vary depending on the mode:

Standard mode (with metrics) 

[+] Running 6/6
 ✔ Container nim-nim-1           Removed
 ✔ Container nim-clickhouse-1    Removed
 ✔ Container nim-precheck-1      Removed
 ✔ Network nim_default           Removed
 ✔ Network nim_external_network  Removed
 ✔ Network nim_clickhouse        Removed

Lightweight mode (no ClickHouse) 

[+] Running 3/3
 ✔ Container nim-nim-1           Removed
 ✔ Network nim_default           Removed
 ✔ Network nim_external_network  Removed

In lightweight mode, only the core service and networks are removed. ClickHouse and precheck containers aren’t present.

Secrets

You can define secrets in the docker-compose.yaml file to set the admin password, optional access credentials, and TLS certificates.

Required

Set the admin password:

secrets:
  nim_admin_password:
    file: admin_password.txt

Optional

Use a custom .htpasswd file to control access to the user interface:

secrets:
  nim_credential_file:
    file: nim_creds.txt

Use your own TLS certificate, key, and CA file for the 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

You can create a backup of NGINX Instance Manager at any time using the built-in nim-backup command. This works for both standard and lightweight deployments.

Run the following command from your Docker host:

docker exec nim-nim-1 nim-backup

If successful, you’ll see a message like:

Backup has been successfully created: /data/backup/nim-backup-<date>.tgz

To locate the backup file:

  • If using named volumes

    Inspect the volume to find its mount point:

    docker inspect volume nim_nim-data | jq '.[0].Mountpoint'

    Then list the backup directory:

    sudo ls -l /var/lib/docker/volumes/nim_nim-data/_data/backup

    Example output:

    -rw-r--r-- 1 root root 5786953 Sep 27 02:03 nim-backup-2024-06-11.tgz

  • If using NFS

    Check the mount path directly, such as:

    ls -l /mnt/nfs_share/data/backup

Restore

To restore a backup, follow these steps:

  1. Enable maintenance mode:

    In your docker-compose.yaml file, set the following:

    environment:
  NIM_MAINTENANCE: "true"

  2. Run the restore command:

    docker exec nim-nim-1 nim-restore /data/backup/nim-backup-<date>.tgz

  3. After the restore process finishes, disable maintenance mode.

    In docker-compose.yaml, change the value back:

    environment:
  NIM_MAINTENANCE: "false"

  4. Restart the container:

    docker compose up -d

Storage

NGINX Instance Manager uses named Docker volumes by default to persist data. You can also configure NFS or other storage backends using driver_opts.

Default volumes

The standard docker-compose.yaml file defines these named volumes:

  • nim-data: stores configuration and state for Instance Manager
  • clickhouse-data: used only in standard mode to persist metrics

In lightweight mode, clickhouse-data is not needed and should be removed from the Compose file.

Example: use NFS for storage

Before you run docker compose up -d, make sure your NFS volumes are mounted:

sudo mount -t nfs <<nfs-ip>>:/mnt/nfs_share/data /mnt/nfs_share/data
sudo mount -t nfs <<nfs-ip>>:/mnt/nfs_share/clickhouse /mnt/nfs_share/clickhouse

Update the volumes section in your Compose file:

volumes:
  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"

If you’re using lightweight mode, omit the clickhouse-data section entirely.

Gather support data

If you contact support, it’s helpful to include logs and a current backup. These commands capture useful diagnostic data.

Get recent logs

Save logs from the past 24 hours:

docker compose logs --since 24h > my-logs-$(date +%Y-%m-%d).txt

Create a fresh backup

Run the backup command to capture the current state:

docker exec nim-nim-1 nim-backup

This creates a .tgz file inside the container under /data/backup/, which you can extract as described in the Backup section.