On-Premise Installation

Requirements

• Linux OS
• 8GB RAM
• 4 Core CPU
• Docker 20.10.6+
• Docker Compose - newer versions of the Docker Engine include Compose, see here for more info

Recommended

Although navio can be installed on any Linux distribution, it is best tested and thus runs most optimally on Ubuntu 18.04 or 20.04.

Instance components

A navio instance consists of multiple components:

• The core components of navio are the Backend, Frontend and Database components. Without these core components, navio cannot be used.

• The Prediction Explainer is required for calculating and displaying the standard SHAP prediction explanations on the try-out view.

• Prometheus is used for model monitoring and enables the monitoring view. This is used for monitoring outliers in the data as well as monitoring the number and latency of requests being made to deployed models.

• The Database component is used for storing credentials, models, data sets and all other persisted data that navio requires.

Setup

We recommend to setup navio with docker and docker-compose.

Core Components

The setup of navio makes use of docker-compose.yml files to compose and configure the required docker services for navio to run. A bare-bones setup only needs to include the core components of navio as mentioned above.

Example:

version: "2.1"

networks:
  navio:
    external:
      name: navio
  navio-internal:

services:
  db:
    image: postgres:12
    volumes:
      - ./storage/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=craftworksnavio
      - POSTGRES_USER=craftworksnavio
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - PGDATA=/var/lib/postgresql/data/pgdata
    networks:
      - navio-internal

  backend:
    image: registry.craftworks.io/craftworks/navio-backend:${IMAGE_VERSION}
    volumes:
      - /mnt/shared_filesystem/:/shared_filesystem/
      - ./storage/backend:/app/local_storage/
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SPRING_CONFIG_ADDITIONAL_LOCATION=file:/app/local_storage/conf/craftworks-navio.properties
      - SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/craftworksnavio
      - SPRING_DATASOURCE_USERNAME=craftworksnavio
      - SPRING_DATASOURCE_PASSWORD=${DB_PASSWORD}
    networks:
      - navio
      - navio-internal
    depends_on:
      - db

  frontend:
    image: registry.craftworks.io/craftworks/navio-frontend:${IMAGE_VERSION}
    environment:
      - GOOGLE_TAG_MANAGER_ID=${GOOGLE_TAG_MANAGER_ID}

note

The Google tag manager id is optional and only required if you would like to use Google Tag manager to monitor user behaviour.

The above example contains some environment variables:

• ${DB_PASSWORD}
• ${GOOGLE_TAG_MANAGER_ID}
• ${IMAGE_VERSION}

You can do one of those things:

1. Replace them directly in the docker-compose.yml file with your desired variable values.

or

2. Configure the environment variables by including an .env file that specifies values for these variables where the placeholders are filled in with your IDs:

IMAGE_VERSION=1.6.1

DB_PASSWORD=${YOUR_DATABASE_PASSWORD}
#optional
GOOGLE_TAG_MANAGER_ID=${GOOGLE_TAG_MANAGER_ID}

Example .env file

Docker Networks

navio makes use of an external docker network, in this example it is given the name navio. The reason for using an external network is, that navio is creating docker containers on-demand and uses this external network to communicate with these containers. Additionally - when enabled - this network is also used to communicate with Prometheus for monitoring purposes and with the prediction explainer

You can use a different name for this network, but make sure that you set this name in the property app.docker.network as described in advanced config. It is required to specify the same network name for prometheus and the prediction explainer too.

The navio-internal network is used for communication between backend and database.

API access

Congratulations, the basic setup of your navio instance is now done. If you have not created the external docker network yet, you need to do so now. Then you should be able to start your instance with:

docker network create navio
$ docker-compose up

To access your instance you now need to make the certains backend and frontend components available outside of the docker network. You are not limited in the ways you can achieve this, some populater ways to achieve this are:

• traefik
• nginx
• direct port mapping

To achieve this the following services need to be available from outside of the docker network:

• Backend:
  • Port 8080
  • All paths matching /api/**
• Fronted:
  • Port 80
  • All other paths

caution

It is strongly recommended, to allow only HTTPS secured access to frontend and backend components.

Example 1: traefik v1.7

If you already use traefik or plan to use traefik for navio, you only need to add the following properties to your docker-compose.yml file, assuming you want to deploy navio at navio.example.com.

networks:
  ...
  proxy:
    external:
      name: proxy
---
services:
---
backend:
---
  labels:
    - "traefik.enable=true"
    - "traefik.port=8080"
    - "traefik.api.frontend.rule=Host:navio.example.com;PathPrefix:/api/"
  networks:
    - ...
    - proxy
---
frontend:
---
  labels:
    - "traefik.enable=true"
    - "traefik.port=80"
    - "traefik.frontend.rule=Host:navio.example.com"
  networks:
    - ...
    - proxy

The docker network proxy must be a preexisting, external docker network that also hosts the traefik container.

Example 2: nginx

Alternatively, you can also use nginx to accomplish this if you're more familiar with nginx. This requires two things:

1. add nginx to your docker-compose.yml file

nginx:
  image: nginx
  volumes:
    - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
  depends_on:
    - backend
    - db
    - frontend
  ports:
    - 80:80
  networks:
    - navio

2. create the config file for nginx under ./nginx/default.conf

client_max_body_size    50m;
client_body_buffer_size 128k;
proxy_connect_timeout   180;
proxy_send_timeout      180;
proxy_read_timeout      180;
proxy_buffers           32 4k;


upstream dockerfrontend {
    server frontend:80;
}

upstream dockerbackend {
    server backend:8080;
}

server {
    listen 80 default;

    location / {
        proxy_pass          http://dockerfrontend;
        proxy_redirect      off;
        proxy_set_header    Host $host;
        proxy_set_header    X-Real-IP $remote_addr;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host $server_name;
    }

    location ~ ^/(api|/v2/api-docs) {
        proxy_pass          http://dockerbackend;
        proxy_redirect      off;
        proxy_set_header    Host $host;
        proxy_set_header    X-Real-IP $remote_addr;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host $server_name;
    }
}

Monitoring

Prometheus

Prometheus is an open-source monitoring system that navio uses for monitoring deployed models.

To include prometheus in the set up, append the follwing to the docker-compose.yml file or create an additional compose file containing:

services:
---
prometheus:
  image: prom/prometheus:YYY
  stop_signal: SIGINT
  command:
    - --config.file=/etc/prometheus/conf/prometheus.yml
    - --storage.tsdb.retention.size=2GB
  volumes:
    - ./prometheus/:/etc/prometheus/conf/:ro
    - ./prometheus_data:/prometheus
  networks:
    - navio

Prometheus relies on a config file for certain configuration values so ensure that the config file ./prometheus/prometheus.yml exists.

It should look something like:

global:
  scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  - job_name: "navio-actuator"
    metrics_path: "/actuator/prometheus"
    scrape_interval: 5s
    basic_auth:
      username: actuator
      password: ACTUATOR_PASSWORD
    static_configs:
      - targets: ["backend:8080"]

tip

Visit the Prometheus Documentation for more information.

Prediction Explainer

As previously mentioned, the prediction explainer is responsible for handling the default explanations or model predictions. Append the services section of the docker-compose.yml file to start using these default explanations:

services:
---
prediction-explainer:
  image: registry.craftworks.io/craftworks/navio-prediction-explainer:XXX
  environment:
    - DEBUG=False # enables swagger ui
  networks:
    - navio