Deployment

Overview

io.Manager can be deployed on-premise and can run inside your organization network.

The deployment consists of the following:

io.Manager Server - a Node.js app, the actual server;
io.Manager Admin UI - a React app that allows managing the data stored in io.Manager;
MongoDB database;

io.Manager can be deployed using a basic or an advanced deployment scenario from the template repository in GitHub. The repository provides configurations for development and production environments.

⚠️ Note that it's highly recommended to use the template repository approach for deploying io.Manager.

io.Manager is also provided as a set of NPM packages exposing the io.Manager Server and Admin UI as modules. The modules provide extension points for different customizations like authentication and storage. The NPM packages are hosted in a private NPM repository. To obtain access, contact us.

Template Repository

The template repository is a template for building and deploying io.Manager to your own infrastructure. It provides a Docker Compose configuration for local development and testing, as well as Kubernetes configurations for deployment to a production environment. This is the recommended approach for deploying io.Manager.

The template repository offers a basic and an advanced deployment scenarios:

The basic scenario uses already built Docker images for deployment. It's possible to customize the deployment to a certain extent by registering environment variables that will provide configuration settings for io.Manager. This includes configuration for the supported databases and authentication mechanisms.
The advanced scenario uses internally the NPM packages and offers a project template that you can customize to a much greater extent. Use the advanced deployment scenario if you need to integrate io.Manager with a non-standard or proprietary storage solution, a custom unsupported authentication mechanism, or if you want to extend its functionality and customize the Admin UI.

Follow the instructions in the README file to build and deploy io.Manager.

NPM Packages

⚠️ Note that it's possible to use the NPM packages exposing the io.Manager Server and Admin UI directly, but it's highly recommended to use the template repository approach for deploying io.Manager.

Access

The NPM packages exposing io.Manager and the Admin UI are hosted in a private NPM repository. To obtain access, contact us.

Environment Setup

Generate an .npmrc file that will contain the authentication information for connecting to the private NPM repository. Make sure to exclude this file from your source control system.

To generate an .npmrc file:

Login to JFROG.
Expand the menu in top right.
Click "Setup".
Select "NPM".
From the dropdown menu select _default-npm-virtual_.
Copy the snippet.
Create an .npmrc file with the copied contents.

MongoDB

io.Manager uses MongoDB as a default database. You must have a running MongoDB instance.

For details about the supported databases and how to use them with io.Manager, see the Databases section.

Now you can begin using the packages and start the server locally.

Examples

See also the following examples on GitHub demonstrating how to run io.Manager with various supported authentication mechanisms:

io.Manager Basic Authentication example;
io.Manager Auth0 Authentication example;
io.Manager Custom Authentication example;

Health Checks

io.Manager exposes HTTP endpoints for health checks. Two types of health checks are supported - basic health check and database connectivity health check. It's possible to to provide health check settings via configuration when initializing io.Manager or via environment variables.

Health checks are provided also for the io.Manager Server and Admin UI Docker images.

Basic

The basic health check reports whether io.Manager is available for processing requests. It's also possible to configure an additional basic health check on a custom route.

To perform a basic health check, invoke the GET / endpoint.

The following table describes the meaning of the status codes received in the HTTP response:

Status Code	Description
`200`	Indicates that io.Manager is available for processing requests.
Any other status code or a lower level network error	Indicates that io.Manager is unable to process requests.

Database Connectivity

The database connectivity health check reports whether io.Manager is connected to its configured database. It's also possible to configure an additional database connectivity health check on a custom route.

To perform a database connectivity health check, invoke the GET /db-connectivity endpoint.

The following table describes the meaning of the status codes received in the HTTP response:

Status Code	Description
`200`	Indicates that io.Manager is connected to its configured database.
`503`	Indicates that io.Manager is unable to connect to its configured database.
Any other status code or a lower level network error	Indicates that io.Manager is unable to process the request.

The database connectivity health check has a configurable timeout that defaults to 2000 ms. If the timeout expires before a response is received from the database, io.Manager will respond with a status code of 503, signaling that it's unable to connect to its configured database.

Configuration

Health check setting can be provided via the healthEndpoints property of the configuration object for initializing the io.Manager Server, or via environment variables, depending on your deployment approach.

Environment Variables

To provide health check settings, use the following environment variables:

Environment Variable	Description
`API_HEALTH_ENDPOINTS_CUSTOM_DB_CONNECTIVITY_HEALTHCHECK_ROUTE`	If present, an additional database health check endpoint will be available on the specified route. The health check behaves exactly the same as when invoking the `GET /db-connectivity` endpoint.
`API_HEALTH_ENDPOINTS_CUSTOM_DB_CONNECTIVITY_STATUS`	The string that the database connectivity health check will return as a successful response. Defaults to `OK`.
`API_HEALTH_ENDPOINTS_CUSTOM_HEALTHCHECK_ROUTE`	If present, an additional health check endpoint will be available on the specified route. The health check behaves exactly the same as when invoking the `GET /` endpoint.
`API_HEALTH_ENDPOINTS_CUSTOM_HEALTHCHECK_STATUS`	String that will be passed as a value to the `"status"` field in the health check response. Defaults to `OK`.
`API_HEALTH_ENDPOINTS_DB_CONNECTIVITY_TIMEOUT`	Interval in milliseconds to wait for a response from the database when performing a database connectivity health check. Defaults to `2000`.

⚠️ Note that when providing custom health check routes via the API_HEALTH_ENDPOINTS_CUSTOM_HEALTHCHECK_ROUTE and the API_HEALTH_ENDPOINTS_CUSTOM_DB_CONNECTIVITY_HEALTHCHECK_ROUTE environment variables, the base API path specified in the API_BASE environment variable won't be taken into account.

The following example demonstrates configuring the timeout for the database connectivity health check and providing custom health check routes:

# Configuring the timeout for the database connectivity health check.
API_HEALTH_ENDPOINTS_DB_CONNECTIVITY_TIMEOUT=3000

# Providing custom health check routes.
API_HEALTH_ENDPOINTS_CUSTOM_HEALTHCHECK_ROUTE=/custom-healthcheck
API_HEALTH_ENDPOINTS_CUSTOM_DB_CONNECTIVITY_HEALTHCHECK_ROUTE=/custom-db-healthcheck

Configuration Object

The following example demonstrates configuring the timeout for the database connectivity health check and providing custom health check routes via the configuration object for initializing the io.Manager Server:

import { start } from "@interopio/manager";

const config = {
    healthEndpoints: {
        // Configuring the timeout for the database connectivity health check.
        dbConnectivityTimeout: 3000,
        // Providing custom health check routes.
        customHealthCheckRoute: "/custom-healthcheck",
        customDatabaseHealthCheckRoute: "/custom-db-healthcheck"
    }
};

const server = await start(config);

The healthEndpoints property has the following properties:

Property	Type	Description
`customDatabaseHealthCheckRoute`	`string`	If present, an additional database health check endpoint will be available on the specified route. The health check behaves exactly the same as when invoking the `GET /db-connectivity` endpoint.
`customHealthCheckRoute`	`string`	If present, an additional health check endpoint will be available on the specified route. The health check behaves exactly the same as when invoking the `GET /` endpoint.
`databaseHealthCheckStatus`	`string`	The string that the database connectivity health check will return as a successful response. Defaults to `"OK"`.
`dbConnectivityTimeout`	`number`	Interval in milliseconds to wait for a response from the database when performing a database connectivity health check. Defaults to `2000`.
`healthCheckStatus`	`string`	String that will be passed as a value to the `"status"` field in the health check response. Defaults to `"OK"`.

⚠️ Note that when providing custom health check routes via the customHealthCheckRoute and the customDatabaseHealthCheckRoute properties, the base API path specified in the base property of the configuration object for initializing the io.Manager Server won't be taken into account.

Docker Health Checks

io.Manager Server

The manager docker image implements a Docker health check that defaults to performing a database connectivity health check. The health check mode can be configured by using the DOCKER_HEALTHCHECK_MODE environment variable which accepts the following values:

Value	Description
`db-connectivity`	Default. Uses the `GET /db-connectivity` endpoint to perform a database connectivity health check.
`http-connectivity`	Uses the `GET /` endpoint to perform a basic health check.
`none`	Disables the health check handler and instructs it to always report a healthy status.

The following example demonstrates providing Docker health check settings using an environment variable:

DOCKER_HEALTHCHECK_MODE=http-connectivity

io.Manager Admin UI

The manager-admin-ui docker image implements a Docker health check that defaults to performing an HTTP connectivity health check on the server that hosts the io.Manager Admin UI static files. The health check mode can be configured by using the DOCKER_HEALTHCHECK_MODE environment variable which accepts the following values:

Value	Description
`http-connectivity`	Default. Checks whether the static file server responds to requests.
`none`	Disables the health check handler and instructs it to always report a healthy status.

The following example demonstrates providing Docker health check settings using an environment variable:

DOCKER_HEALTHCHECK_MODE=none

io.Manager Documentation

Deployment