Single Server Docker Deployment (Simple Install)

This article details how to install Metric Insights on a single server. Because this is a non-orchestrated deployment (meaning there is no automated management of the containers), we call this a 'Simple Install'.

PREREQUISITES: 

For servers without outbound access, the host machine must have the following packages installed manually to support the application:

For servers with outbound access, the packages above are installed by the Metric Insights installer automatically. 

Please ensure enough disk space is available for the following directories (if configured as separate partitions), as mentioned in What are the system requirements for a Metric Insights server? 

  • /var/lib 
  • /opt or /app
  • /home
  • /tmp

Simple Installation Architecture

The deployment scheme consists of the following services deployed as individual containers (1 service per container):

Required services:

  1. Web Master
  2. Web Slave
  3. Data Analyzer
  4. Data Processor
  5. Seed
  6. MySQL 
  7. Monitoring

Optional services:

  1. Remote Data Processor (for BI Tools that require integrating from a Windows environment instead of Linux)

If you are using a firewall on the Linux machine, the following ports are necessary for Metric Insights to work correctly:

  • 80, 443 - HTTP and HTTPS ports for the Web Application (by default redirection to 443)
  • 2550 - TCP port for the Data Processor service
  • 2551 - TCP port for the Seed service
  • 3306 - MySQL port for external access to the database
  • 8080, 8443 - HTTP and HTTPS ports for the REST API Data Processor Service (only one port is enabled at one time)
  • 8081 - TCP port for the Monitoring service (separate GUI service that admins can use to monitor the health of the application containers in a browser)

1. SSH to the Server

  1. SSH to the host server (where x.x.x.x represents the IP of the server, or use the hostname):  ssh root@x.x.x.x 

Note: The Metric Insights application must be installed as user root or as a user with sudo privileges (added to the wheel or sudo group, thereby included in the sudoers list). The docker daemon binds to a unix socket instead of a tcp port, therefore unix sockets are owned by user root and accessible by users with sudo privileges.

2. Download the MI App Installation Package

  1. Depending on the version, you will be given a link to the corresponding MI app installation package.
  2. Along with the link, Username and Password will be provided by the MI support team; enter these credentials into the respective fields.
  3. Confirm your agreement with the Terms and Conditions of the Metric Insights usage.
  4. Click [Submit].

This will initiate the download process of the .tar.gz archive (containing all docker images and binaries required to install the application).

3. Package Overview

  1. base 
    • Subfolder with default /opt/mi file system for MI application
  2. build.properties 
    • File listing MI component versions
  3. data 
    • Subfolder with binaries and miscellaneous data
  4. installer.py 
    • Python script that initializes the Metric Insights installation process
  5. scripts
    • A set of auxiliary scripts
  6. uninstaller.py
    • Python script that uninstalls the Metric Insights application
  7. utils 
    • Subfolder containing common libraries used by installer.py
    • Also holds third-party libraries

4. Supported Operating Systems

Metric Insights v6.x can be installed on the following Operating Systems (any OS with Linux kernel >= 3.10):

  • RHEL 7,8
  • CentOS 7,8
  • Oracle Linux 7
  • Ubuntu 16.04, 18.04, 20.04
  • Debian 9,10
  • Amazon Linux 2

5. Run the Installer

Please make sure to set the correct timezone for the application when running the installer using the --timezone parameter.

If the database is running on a remote server that has timezone different from the MI application timezone, specify the timezone of the remote database server using the --mysql-timezone parameter.

Use the ./installer.py --timezone-list command to see the list of available timezones.

We recommend checking the help to ensure appropriate parameters are defined for the install. To see the help:

./installer.py -h

Run the installer command depending on whether your database is deployed on localhost or on remote database server:

  • If MySQL runs on localhost:

sudo ./installer.py --bind-address 0.0.0.0 --timezone <timezone> -vv

  • If  MySQL runs on a remote database server:
    • If the remote DB server has the same timezone as MI app: sudo ./installer.py --bind-address 0.0.0.0 --db-hostname <remote DB host> --db-user <remote DB root username> --db-password <remote DB root password> --timezone <timezone> --components web,data-analyzer,dataprocessor,seed,monitoring -vv
    • If the remote DB server has a different timezone than MI app: sudo ./installer.py --bind-address 0.0.0.0 --db-hostname <remote DB host> --db-user <remote DB root username> --db-password <remote DB root password> --timezone <timezone> --mysql-timezone <MySQL timezone> --components web,data-analyzer,dataprocessor,seed,monitoring -vv

Once the installation is complete, you will see a "Metric Insights v6.x.x installed successfully" message.

The "Waiting while all provision actions are completed" can take a while, so it's not so unusual. While it's running, in a separate terminal, please tail /opt/mi/log/web.log to see what it's doing.

Example 

./installer.py --bind-address 0.0.0.0 --timezone 'US/Pacific' -vv

The installer command above is an example of installing the application with MySQL running on localhost where the timezone is set to Pacific Time. Setting the --bind-address to 0.0.0.0 is also key. Other timezone examples are:

Eastern Time

  • --timezone 'US/Eastern' 

Central Time

  • --timezone 'US/Central'

5.1. Basic Console Commands

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.

mi-web OR mi-console Wrapper for docker-compose; used to enter the Web docker container directly
mi-dataprocessor OR mi-console dataprocessor Wrapper for docker-compose; used to enter the Data Processor docker container directly
mi-seed OR mi-console seed Wrapper for docker-compose; used to enter the Seed docker container directly
mi-monitoring OR mi-console monitoring Wrapper for docker-compose; used to enter the Monitoring docker container directly
mi-data-analyzer OR mi-console data-analyzer Wrapper for docker-compose; used to enter the Data Analyzer docker container directly
mi-control Wrapper for docker-compose; used to manage Metric Insights docker containers (stop, start, restart, etc.)
mi-version Displays the Metric Insights version in the command line

5.2. The Following List of Parameters Can Be Used When Running the Installer (from the Help)

Positional Parameters
kubernetes Metric Insights Kubernetes Deployment Config Generator. Use --help with this command to get more details
ecs Metric Insights ECS Deployment Config Generator. Use --help with this command to get more details.
swarm Metric Insights Swarm Deployment Config Generator. Use --help with this command to get more details.
images Metric Insights Docker Images Manager. Use --help with this command to get more details.
Optional Parameters
-h, --help Show this help message and exit
-v, --verbose Verbose logging (default: False)
-y, --yes Assume "yes" on interactive requests (default: False)
--path INSTALL_PATH Base path for Metric Insights (default: /opt/mi)
--bind-address BIND_ADDRESS General bind address for listening by services. (default: 10.0.2.15)
--dp-hostname DATAPROCESSOR_HOSTNAME Data Processor service hostname for external services. (default: 10.0.2.15)
--skip-packages Skip installation of any additional packages (default: False)
--show-packages Show packages required to run Metric Insights (default: False)
--db-ram-config DB_RAM_CONFIG Amount of RAM (integer value in gigabytes) on the Database Server. Options: [12,16,32] (default: None)
--db-dataset-hostname DB_DATASET_HOSTNAME MySQL hostname for Default Dataset Storage. (default: mysql)
--db-hostname DB_HOSTNAME MySQL hostname of Database Server. (default: mysql)
--db-name DB_NAME MySQL database name. (default: dashboard)
--db-port DB_PORT MySQL port for db-hostname. (default: 3306)
--db-user DB_USER MySQL admin user name to init Metric Insights database. (default: root)
--db-dataset-user DB_DATASET_USER MySQL admin user for --db-dataset-hostname.
--db-password DB_PASSWORD MySQL admin user password
--db-dataset-password DB_DATASET_PASSWORD MySQL admin user for --db-dataset-hostname
--dp-db-password DP_DB_PASSWORD MySQL dataprocessor user password
-timezone TIME_ZONE Set time zone. (default: UTC)
--timezone-list List available Timezones.
--mysql-timezone MYSQL_TIME_ZONE Set MySQL time zone if MySQL engine has different timezone than application. If not specified, then the value from --timezone option is used.
--restrict-access RESTRICT_ACCESS Comma separated list of MI services that must not have outside access. By default all services are opened externally. Example: web, mysql, dataprocessor, seed, data-analyzer, monitoring. (default: None)
--unprivileged During install, skip actions that require root access, like system package installation.
CAUTION: System must already have all the required packages installed.
--seed-hostname DATAPROCESSOR_SEED_HOSTNAME Data Processor seed service hostname for external services. (default: 10.0.2.15)
--dp-url DP_URL Set Data Processor REST-API URL (default: http://dataprocessor:8080)
--dp-user DP_USER User to get access to the Data Processor REST-API service (default: dataprocessor)
--dp-password DP_PASSWORD Password for the Data Processor REST-API user.
--dp-enable-ssl Enable HTTPS for the Data Processor REST-API service. Ensure that correct SSL certificate and DP URL are provided (default: False)
--components COMPONENTS Comma-separated list of components to deploy. Possible values: web, mysql, dataprocessor, seed, data-analyzer, monitoring. (default: web, mysql, dataprocessor, seed, data-analyzer, monitoring)
--custom-component CUSTOM_COMPONENT Comma-separated list of custom components.
--high-load Enable high-load configuration for the Web service. This will optimize the system for several thousand concurrent users.
--use-prior-command Use the last installation command.
--tmpdir TMP_FOLDER Specify the temp directory for Metric Insights services (default: /opt/mi/data/tmp)
--no-proxy NO_PROXY Comma separated list of components which should not be accessed via proxy (if set)
--proxy-server-https-address PROXY_SERVER_HTTPS_ADDRESS HTTPS proxy address.
--proxy-server-http-address PROXY_SERVER_HTTP_ADDRESS HTTP proxy address. May be omitted if it is the same as for HTTPS.
--disable-logger Disable additional logger service for collecting logs.

6. Security 

./installer.py --restrict-access mysql,dataprocessor

This allows for situations where only the UI is accessible externally.