# Deployment

Source: https://docs.interop.io/manager/deployment/index.html

## 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**.
- A supported [database](https://docs.interop.io/manager/databases/overview/index.md).

> ⚠️ *Note that the **io.Manager** Server is a single-threaded program. To scale it up, you must spawn multiple instances of it.*

**io.Manager** can be deployed using a basic or an advanced deployment scenario from the [template repository](https://github.com/InteropIO/manager-examples/tree/main/manager-template) 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.

## Template Repository

The [template repository](https://github.com/InteropIO/manager-examples/tree/main/manager-template) 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](https://github.com/InteropIO/manager-examples/tree/main/manager-template/1-basic) and an [advanced](https://github.com/InteropIO/manager-examples/tree/main/manager-template/2-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 custom unsupported authentication mechanism, or if you want to extend its functionality and customize the Admin UI.

Follow the instructions in the [README](https://github.com/InteropIO/manager-examples/blob/main/manager-template/README.md) 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](#template_repository) approach for deploying **io.Manager**. If you need more advanced customization options for your **io.Manager** deployment, use the advanced scenario from the template repository.*

The following packages are available on NPM:

- [`@interopio/manager`](https://www.npmjs.com/package/@interopio/manager) - The Server component.
- [`@interopio/manager-admin-ui`](https://www.npmjs.com/package/@interopio/manager-admin-ui) - The Admin UI component.
- [`@interopio/manager-api`](https://www.npmjs.com/package/@interopio/manager-api) - A JavaScript (TypeScript) wrapper around the **io.Manager** Server REST API.

## Examples

For full working examples on how to run **io.Manager** and configure its features ([authentication](https://docs.interop.io/manager/authentication/overview/index.md), [databases](https://docs.interop.io/manager/databases/overview/index.md), [OpenTelemetry support](https://docs.interop.io/manager/opentelemetry-support/overview/index.md)) in various scenarios, see the [**io.Manager** Examples](https://github.com/InteropIO/manager-examples) repository on GitHub.

## Health Checks

Available since io.Manager Server 1.7

**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](#health_checks-configuration) 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](https://docs.interop.io/manager/databases/overview/index.md). It's also possible to [configure](#health_checks-configuration) 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. *Available since **io.Manager** Server 1.8.* |
| `API_HEALTH_ENDPOINTS_CUSTOM_DB_CONNECTIVITY_STATUS` | The string that the database connectivity health check will return as a successful response. Defaults to `OK`. *Available since **io.Manager** Server 1.8.1.* |
| `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. *Available since **io.Manager** Server 1.8.* |
| `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`. *Available since **io.Manager** Server 1.8.1.* |
| `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:

```cmd
# 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:

```javascript
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. *Available since **io.Manager** Server 1.8.* |
| `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. *Available since **io.Manager** Server 1.8.* |
| `databaseHealthCheckStatus` | `string` | The string that the database connectivity health check will return as a successful response. Defaults to `"OK"`. *Available since **io.Manager** Server 1.8.1.* |
| `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"`. *Available since **io.Manager** Server 1.8.1.* |

> ⚠️ *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

Available since io.Manager Server 1.7 & io.Manager Admin UI 2.0.4

#### 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 via an environment variable:

```cmd
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 via an environment variable:

```cmd
DOCKER_HEALTHCHECK_MODE=none
```