> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/reference-manual/v3.44.2/installation/elimity-insights-server.md).

# Elimity Insights server

The Elimity Insights server fulfills multiple roles in a deployment of the Elimity Insights platform:

* Serving the Elimity Insights web application
* Serving the Elimity Insights REST API
* Running various scheduled background tasks
  * Performing imports for built-in sources
  * Sending daily notifications for access review reminders and failed health checks

For SaaS customers we perform the setup and maintenance of Elimity Insights servers behind the scenes. These installation instructions are mainly useful for on-prem deployments.

## Installation

We distribute all Elimity Insights releases as Docker images for both Linux and Windows Server hosts. Our recommendation for deploying these is to use your cloud provider's CaaS solution for complex applications (e.g. Google Cloud App Engine flexible environment, Azure App Service, ...). Note that we don't support deploying Elimity Insights using services like Google Cloud Run and Azure Container Apps (but we do recommend these for [gateways and import agents](/technical-guides/gateways-and-import-agents.md)). The main reason is that Elimity Insights servers currently do not match most cloud providers' definition of a microservice:

* Elimity Insights servers build a cache on startup which might take a while.
* Elimity Insights servers do not support horizontal scaling.
* Elimity Insights servers perform long-running tasks in the background.

Services like Google Cloud App Engine flexible environment and Azure App Service however are a perfect fit for Elimity Insights servers:

* No manual VM management
* Encrypted connections to Elimity Insights via out-of-the box HTTPS reverse proxy
* Great integration with your cloud provider's key vault for mounting secrets
* Configuration / monitoring / upgrades via your cloud provider's user-friendly UI

We also support deploying manually on e.g. Windows Server if using your cloud provider's CaaS solution is not an option. In either case please refer to [our documentation about working with containers](/technical-guides/working-with-containers.md) for detailed setup instructions. Visit <https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/insights> to get a list of available image tags.

## Upgrades

Upgrading an Elimity Insights deployment typically requires performing the following steps:

1. Shutting down the old server
2. Backing up your database
3. Performing database migrations (not applicable for patch upgrades)
4. Updating the server (simply bumping image version for container-based installations)
5. Starting the updated server

### Database migrations

For database migrations we also provide OCI images. As usual, we recommend using a CaaS solution like Google Cloud Run or Azure Container Apps to perform database migrations as a one-off job.&#x20;

There are two ways to provide configuration to the migration tool: via the command line or via a configuration file.

#### Command-line (CLI)

You can run the image manually using the Docker CLI:

```shell-session
$ docker run --rm europe-west1-docker.pkg.dev/elimity-general/docker/insights-database-migrate:<tag> help
Elimity Insights database migration tool
Description:
  This tool applies database migrations required for upgrading Elimity Insights. It migrates the specified Postgres
  databases in-place. Note that this tool can only migrate databases for Elimity Insights v3.x.

Usage:
  elimity-insights-database-migrate help
  elimity-insights-database-migrate migrate -dsn=<dsn> -target-version=<target-version>
  elimity-insights-database-migrate target-versions
  elimity-insights-database-migrate version

Commands:
  help            Print usage information
  migrate         Migrate a database
  target-versions List supported target versions
  version         Print version information

Flags:
  -dsn=<dsn> Data source name, e.g. 'postgres://user@host/database'
  -target-version=<target-version> Target version, e.g. 'v3.1'
```

#### Configuration file

To simplify the database migration process, the migration can read configuration directly from a `config.json` file.

To configure your migration, mount a JSON configuration file at `/app/config/config.json` with the properties listed below. Refer to the following snippet for a starting point:

```json
{
  "pgConnStr": "postgres://<user>:<password>@<host>:5432/postgres",
  "targetVersion": "v3.44",
  "pgAzureManagedIdentity": false
}
```

The table below describes each supported configuration option in more detail:

<table data-full-width="true"><thead><tr><th width="218.96484375">Configuration option</th><th>Value type</th><th>Default value</th><th width="243.40625">Description</th></tr></thead><tbody><tr><td><code>pgConnStr</code></td><td><code>string</code></td><td></td><td>The PostgreSQL connection string (e.g., <code>"postgres://&#x3C;user>:&#x3C;password>@&#x3C;host>:5432/postgres"</code>).</td></tr><tr><td><code>targetVersion</code></td><td><code>string</code></td><td></td><td>The target release version for the migration (e.g., <code>"v3.44"</code>).</td></tr><tr><td><code>pgAzureManagedIdentity</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Set to <code>true</code> to automatically retrieve an Azure AD token from Azure for database authentication.</td></tr></tbody></table>

Visit <https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/insights-database-migrate> to get a list of available tags for this specific image.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/reference-manual/v3.44.2/installation/elimity-insights-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.