Deploying Container Orchestration with Docker Swarm

Docker Swarm is an excellent option for container orchestration if you meet one of the following conditions:

  • Need to utilize existing hardware already procured for Metric Insights
  • Don't have a cloud service provider to take advantage of orchestration tools like:
    • AWS Kubernetes (EKS) or AWS Native Orchestration (ECS)
    • Azure Kubernetes (AKS)
    • GCP Kubernetes (GKE)
  • Don't have an on-premise Kubernetes or OpenShift cluster to deploy

In terms of hardware, for Docker Swarm to work, we would need to deploy Metric Insights across a minimum of two application servers (with each server serving as nodes for the containers to run on).*

Please see Operating system Linux package requirements for v6.1+ for host server linux package requirements.

* Note, for best fault tolerance, three application nodes are recommended.

One downside of Docker Swarm is the ability for host nodes to be auto-managed,  meaning if a host node goes down, a new replacement node is not automatically brought up for the swarm (as is typically the case with Kubernetes/OpenShift).

Also, Docker Swarm is managed via command-line (although there are third party GUIs available).


  1. Docker-CE with swarm mode enabled
  2. Connect the required list of nodes to the Docker Swarm cluster
  3. Credentials for your private Docker Registry to pull Metric Insights docker images
    • You can also pull from Metric Insights' official docker registry (contact [email protected] for credentials)
  4. NFS Share mounted to all nodes to store the Metric Insights file system
    • This ensures continuous operations where critical application and data files survive and containers across the cluster continue to run should any nodes go down.
  5. Ensure the following ports are open in the load balancer:
    • 80, 443 - HTTP and HTTPS ports for the Web UI Service (default redirection to 443)
    • 2550 - TCP port for the Data Processor cluster
    • 2551 - TCP port for the Seed Node Service
    • 3306 - MySQL port for external access
    • 8080, 8443 - HTTP and HTTPS ports for the REST API Data Processor Service
    • 8081 - TCP port for Monitoring Tool

Preparing for the Deployment

See Docker Commands Cheat Sheet to understand the Docker commands used below.

  1. Install all required packages to both application nodes to support Docker
  2. Provision a remote MySQL server database to store the application database
    • MySQL 8+ (v8.0.20 is recommended for stability)
    • MySQL root user required for the deployment
  3. Provision an NFS share to mount to all nodes to store the MI filesystem (default path is /opt/mi)
  4. Identify and label the nodes as master and slave:
    • For master node, enter the following docker command to label it as master:
      docker node update --label-add type=master node_master
    • For slave node, enter the following docker command to label it as slave:
      docker node update --label-add type=worker node_slave
  5. Download the Metric Insights installer then unpack to the master node (contact [email protected] for the installer tarball). This will create an installer directory from where we can run the installer to generate a Deployment Manifest for Docker Swarm
    • tar xf MetricInsights-Installer-v6.x.x-Full.tar.gz
    • cd MetricInsights-Installer-v6.x.x-Full
  6. Prepare Docker Secret files for each MI service
    • In the installer directory, you can find the template files to generate the secrets in ../utils/orchestration/swarm/secrets
    • Copy the *.env.example files there to your local directory and rename to *.env
    • Each template file represents a different MI service:
      • web.env
      • seed.env
      • dataprocessor.env
      • data-analyzer.env
      • monitoring.env
    • Edit each template file and update each parameter. Make sure the passwords you generate are consistent throughout the files
  7. Generate the deployment manifest to use with Docker Swarm by running the following from the installer directory:
    • If the remote DB server has the same timezone as MI app: ./ swarm --timezone <MI app timezone> -o <manifest filename>.yml
    • If the remote DB server has a different timezone than MI app: ./ swarm --timezone <MI app timezone> --mysql-timezone <remote database server timezone> -o <manifest filename>.yml
    • If the Metric Insights Docker images will be pulled from a private Docker registry, use the --registry option along with the Docker registry URL as in ./ swarm... --registry When providing a registry URL, be sure to not include “https://.” The supported values are <hostname> or <hostname>:<port> without any protocol.

Note: Run ./ swarm --help to see the list of available installer options. See Basic Console Commands section.

  1. Finally, update the NFS share address in the deployment manifest file:
    • Look for this section and change the address to the appropriate NFS share:
      type: "nfs"
      o: ",nolock,soft,rw"
      device: ":/opt/mi/data/data"


To deploy docker swarm using the deployment manifest, use the docker stack deploy command:

$ docker stack deploy -c mi-swarm.yml --with-registry-auth mi
Creating secret mi_mysql
Creating secret mi_web
Creating secret mi_dataprocessor
Creating secret mi_seed
Creating secret mi_monitoring
Creating service mi_dataprocessor
Creating service mi_seed
Creating service mi_web
Creating service mi_monitoring
  • Note, the docker stack deploy command will create the docker secrets required for each service based on the *.env files. There is no need to create the secrets yourself.
  • Please see Docker Commands Cheat Sheet for a list of docker commands to use to manage the deployment.

If you need to customize some processes after the application deployment, see Configuring Custom Components article.  

Architectural Diagram of Docker Swarm

This diagram highlights a basic 2-node Docker Swarm deployment with primary services (containers) on Node 1 and additional Web services on Node 2.

Upgrading Metric Insights to a newer Version

To upgrade the deployment to a newer version of Metric Insights, simply generate a new config file using the installer for the new release, then redeploy using docker stack deploy.

Basic Console Commands

Basic console commands can be checked by running ./ swarm --help.

The following list of utilities are available to use on the host.

Note, all of these tools become available only if the Web Component is installed.

Optional Parameters
--registry REGISTRY Docker registry URL, that will be used for deploying MI components. Example: <hostname> or <hostname>:<port>. (default: None)
--hostname HOSTNAME Web service additional hostname (default: None). The option is used to assign to the Web container. It helps the Metric Insights application to interact with its internal components faster inside the container.