Using Instance Manager with Containers

This topic explains how to use Instance Manager with containers.

This documentation applies to NGINX Management Suite Instance Manager 2.1.0 and later.

Instance Manager utilizes the NGINX Agent, which runs as a process or binary. There are at least three methods for using Instance Manager with containers:

  • Use systemd in a container
  • Layer the NGINX Agent on top of NGINX
  • Run multiple binaries on CMD

Before You Begin

To complete this tutorial, you need the following:

  • A working knowledge of Docker and how to build and extend containers.
  • Instance Manager is installed, configured, and running.


We will use Debian (buster-slim) as an example, but other supported distributions can be used.

  1. Copy the nginx.conf and conf.d files to the same directory of your Dockerfile. If you are using open-source, add a stub_status conf to at a minimum.

  2. Create a Dockerfile similar to the following example:

    Example Dockerfile

    Download Dockerfile

    FROM debian:buster-slim
    LABEL maintainer="NGINX Agent Engineering"
    # APT non-interactive during build
    ARG DEBIAN_FRONTEND=noninteractive
    # Install NGINX Agent
    RUN apt-get update && \
        apt-get install --no-install-recommends --no-install-suggests -y \
        curl \
        gnupg \
        ca-certificates \
        apt-transport-https \
        lsb-release \
        procps \
    # NGINX is included in the dockerfile here, can be modified as needed, this adds the OSS image by default.
        nginx \
      && curl -k https://$CONTROL_PLANE_IP/install/nginx-agent | sh \
    # Forward request and error logs to docker log collector \
      && ln -sf /dev/stdout /var/log/nginx/access.log \
      && ln -sf /dev/stderr /var/log/nginx/error.log
    # Cleanup \
    RUN apt-get autoremove --purge -y \
          curl \
          gnupg \
          apt-transport-https \
          lsb-release \
      && rm -rf /root/.gnupg \
      && rm -rf /var/lib/apt/lists/*
    COPY /
    CMD bash /
  3. Add the file in the same directory:



    set -euxo pipefail
        echo "received TERM signal"
        echo "stopping nginx-agent ..."
        kill -TERM "${agent_pid}" 2>/dev/null
        echo "stopping nginx ..."
        kill -TERM "${nginx_pid}" 2>/dev/null
    trap 'handle_term' TERM
    # Launch nginx
    echo "starting nginx ..."
    /usr/sbin/nginx -g "daemon off;" &
    cat /etc/nginx-agent/nginx-agent.conf
    # start nginx-agent, pass args
    echo "starting nginx-agent ..."
    /usr/bin/nginx-agent "$@" &
        wait ${agent_pid}
        trap '' EXIT INT TERM
        kill -QUIT "${nginx_pid}" 2>/dev/null
        echo "waiting for nginx to stop..."
        wait ${nginx_pid}
        kill -TERM "${agent_pid}" 2>/dev/null
        echo "terminating nginx-agent..."
    echo "nginx-agent process has stopped, exiting."
  4. Build the Dockerfile:

    docker build \
      -t nginx-agent --build-arg CONTROL_PLANE_IP .
  5. Run the container. In this example, we mount a local version of nginx-agent.conf, which can be used in place of the one in the image, and export port 1080 to the container’s port 80. We specify the NMS host IP address, port and instance group name. See NGINX Agent Environment Variables for details on these. We also make the container a daemon and name it nginx-agent-1. Finally, we specify we want to restart the container on failure.

    docker run \
      --name nginx-agent-1 \
      --hostname nginx-agent-1 \
      -d \
      -e NMS_SERVER_HOST= \
      -e NMS_SERVER_GRPCPORT=443 \
      -e NMS_INSTANCE_GROUP='ig01' \
      --restart=unless-stopped \
      -v $PWD/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf \
      -p 1080:80 \

Next Steps

You can combine this example with certificates and advanced configurations.