Skip to content

Latest commit

 

History

History
399 lines (290 loc) · 16.5 KB

setup.md

File metadata and controls

399 lines (290 loc) · 16.5 KB
Raw

Setup

This section outlines the steps to download and install the Informatics Gateway using the CLI and Docker image.

Runtime Requirements

For development requirements, refer to the Informatics Gateway README.md.

Note

Use MONAI Deploy Express to quickly bring up all required services, including the Informatics Gateway.

Skip to Configure Informatics Gateway if you are using MONAI Deploy Express.

Installation

Informatics Gateway CLI

Download and install the Informatics Gateway CLI from the Releases section of the repository and install it.

Note

The example below uses the v0.2.0 release; we recommend always downloading the latest version from the Releases section.

On Linux

# Download the CLI
curl -LO https://github.com/Project-MONAI/monai-deploy-informatics-gateway/releases/download/0.2.0/mig-cli-0.2.0-linux-x64.zip
# Calculate the SHA256 checksum and verify the output with the checksum on the Releases page.
sha256sum mig-cli-0.2.0-linux-x64.zip
# Unzip the CLI
unzip mig-cli-0.2.0-linux-x64.zip
# Install it in bin
sudo mv mig-cli /usr/local/bin

On Windows

# Download the CLI
curl -LO https://github.com/Project-MONAI/monai-deploy-informatics-gateway/releases/download/0.2.0/mig-cli-0.2.0-win-x64.zip
# Calculate the SHA256 checksum and verify the output with the checksum on the Releases page.
Get-FileHash mig-cli-0.2.0-win-x64.zip
# Unzip the CLI
Expand-Archive -Path mig-cli-0.2.0-win-x64.zip

Informatics Gateway Docker Image

Navigate to the monai-deploy-informatics-gateway package page and locate the version to download.

# for the latest build
docker pull ghcr.io/project-monai/monai-deploy-informatics-gateway:latest
# or for a versioned build
docker pull ghcr.io/project-monai/monai-deploy-informatics-gateway:0.2.0

Configure Informatics Gateway

Use the following commands to initialize the Informatics Gateway and default configuration:

mig-cli config init
mig-cli config endpoint http://localhost:5000 #skip if running locally
mig-cli.exe config init
mig-cli.exe config endpoint http://localhost:5000 #skip if running locally

Note

For MONAI Deploy Express, use http://localhost:5003.

The first command extracts the default appsettings.json file into the home directory:

  • Linux: ~/.mig/appsettings.json
  • Windows: C:\Users\[username]\.mig\appsettings.json

This file is mapped into the Docker container and used by the Informatics Gateway when mig-cli is used to launch the application.

For a complete reference of the appsettings.json file, refer to the Configuration Schema.

The second command passes the endpoint for the Informatics Gateway RESTful API to mig-cli.

Note

To see available commands, simply execute mig-cli or mig-cli.exe. Refer to CLI for complete reference.

Database Configuration

The Informatics Gateway supports the following database systems:

  • SQLite (default)
  • MongoDB

SQLite (default)

SQLite is a lite weight, full-featured SQL database engine and is the default database engine used by the Informatics Gateway. With SQLite, the Informatics Gateway works out of the box without any external database service dependencies or configuration.

The default configuration maps the database file mig.db in the /database directory.

{
  "ConnectionStrings": {
    "Type": "sqlite",
    "InformaticsGatewayDatabase": "Data Source=/database/mig.db"
  }
}

MongoDB

For enterprise installations, MongoDB is the recommended database solution. To switch from SQLite to MongoDB, edit the appsettings.json file, and change the ConnectionStrings section to the following with the correct username, password, IP address/hostname, and port.

{
  "ConnectionStrings": {
    "Type": "mongodb",
    "InformaticsGatewayDatabase": "mongodb://username:password@IP:port",
    "DatabaseName": "InformaticsGateway"
  }
}

Other Database Systems

Extending the Informatics Gateway to support other database systems can be done with a few steps.

If the database system is supported by Microsoft Entity Framework, then it can be added to the existing project.

For other database systems that are not listed in the link above, simply implement the Repository APIs, update the Database Manager to support the new database type and optionally, implement the IDabaseMigrationManager.

Authentication

Authentication is disabled by default. To enable authentication using OpenID, edit the appsettings.json file and set bypassAuthentication to true:

{
  "MonaiDeployAuthentication": {
    "bypassAuthentication": true,
    "openId": {
      "realm": "{realm}",
      "realmKey": "{realm-secret-key}",
      "clientId": "{client-id}",
      "audiences": [ "{audiences}" ],
      "roleClaimType": "{roles}",
  ...
}

Refer to the Authentication Setup Using Keycloak section for additional details.

Storage Consideration & Configuration

The Informatics Gateway operates on two storage locations. In the first location, the incoming data for data grouping is temporarily stored. In the second location, the Informatics Gateway uploads grouped datasets to final storage shared by other MONAI Deploy sub-systems.

Temporary Storage of Incoming Dataset

By default, the temporary storage location is set to use Disk and stores any incoming files inside /payloads. This can be modified to user a different location, such as Memory or a different path.

To change the temporary storage path, locate the InformaticsGateway>storage>localTemporaryStoragePath property in the appsettings.json file and modify it.

Note

You will need to calculate the required temporary storage based on the number of studies and the size of each study. Also, consider changing the AE Title timeout if the AE Title needs to wait a long time before assembling and uploading the payload for final storage.

Note

Before running the Informatics Gateway, adjust the values of watermarkPercent and reserveSpaceGB based on the expected number of studies and size of each study. The suggested value for reserveSpaceGB is 2x to 3x the size of a single study multiplied by the number of configured AE Titles.

Storage Service

Informatics Gateway includes MinIO as the default storage service provider. To integrate with another storage service provider, please refer to the Data Storage section of the SRS.

Download and install MinIO by following the quickstart guide. Once MinIO is installed and configured, modify the storage configuration to enable communication between the Informatics Gateway and MinIO.

Locate the storage section of the configuration in appsettings.json:

{
  "ConnectionStrings": {
    "InformaticsGatewayDatabase": "Data Source=migdev.db"
  },
  "InformaticsGateway": {
    "dicom": { ... },
    "storage": {
      "localTemporaryStoragePath": "/payloads", # path to store incoming data before uploading to the storage service
      "remoteTemporaryStoragePath": "/incoming", # the path on the "temporaryBucketName" where the data is uploaded to before payload assembly
      "bucketName": "monaideploy", # name of the bucket for storing payloads
      "temporaryBucketName": "monaideploy", # name of the bucket for temporarily storing incoming data before payload is assembled
      "serviceAssemblyName": "Monai.Deploy.Storage.MinIO.MinIoStorageService, Monai.Deploy.Storage.MinIO", # the fully qualified assembly name for the storage service to use
      "watermarkPercent": 75, # a percentage value that indicates when the system shall stop receiving or downloading data.  Disk space is calculated based on the path defined in "localTemporaryStoragePath"
      "reserveSpaceGB": 5, # minimum disk space required and reserved for the Informatics Gateway
      "settings": { # settings for the storage library: default to minio
        "endpoint": "localhost:9000", # MinIO server IP and port number
        "accessKey": "admin", # username/access key
        "accessToken": "password", # password/access token
        "securedConnection": false, # enable secured connection to minio?
        "region": "local", # storatge region
        "createBuckets": "monaideploy" # buckets to be created on startup if not already exists
      }
    },
    ...
  }
}

Note

Update the createBuckets configuration if you would like to have the Informatics Gateway create the storage buckets on startup. Otherwise, leave it blank. To create multiple buckets, separate each bucket name with comma.

Install the Storage Plug-in

As shown above, the default plug-in configured is MinIO and is ready to use.

To use other storage plug-in, refer to MONAI Deploy Storage for available plug-ins or bring your own plug-in.

To install a new storage plug-in, unzip the files to the plug-ins directory in your home directory:

  • Linux: ~/.mig/plug-ins
  • Windows: C:\Users\[username]\.mig\plug-ins

Note

If a plug-in other than MinIO is used, update the storageService parameter in the appsettings.json file.

Message broker

The Informatics Gateway communicates with other MONAI Deploy components through a message broker. The default messaging service included is provided by RabbitMQ. To integrate with another storage service provider, refer to the Data Storage section of the SRS.

To use the default messaging service, download and install RabbitMQ by following the Get Started page.

The Informatics Gateway publishes all messages to an exchange under the specified virtual host. Before launching Informatics Gateway, update the appsettings.json file to configure the publisher and subscriber settings.

{
  "InformaticsGateway": {
    "messaging": {
      "publisherServiceAssemblyName":"Monai.Deploy.Messaging.RabbitMQ.RabbitMQMessagePublisherService, Monai.Deploy.Messaging.RabbitMQ",
      "publisherSettings": {
        "endpoint": "localhost",
        "username": "username",
        "password": "password",
        "virtualHost": "monaideploy",
        "exchange": "monaideploy"
      },
      "subscriberServiceAssemblyName":"Monai.Deploy.Messaging.RabbitMQ.RabbitMQMessageSubscriberService, Monai.Deploy.Messaging.RabbitMQ",
      "subscriberSettings": {
        "endpoint": "localhost",
        "username": "username",
        "password": "password",
        "virtualHost": "monaideploy",
        "exchange": "monaideploy",
        "exportRequestQueue": "export_tasks"
      }
    },
  }
}

Install the Messaging Plug-in

As shown above, the default plug-in configured is RabbitMQ and is ready to use.

To use other plug-in, refer to MONAI Deploy Messaging for available plug-ins.

To install a new messaging plug-in, unzip the files to the plug-ins directory in your home directory:

  • Linux: ~/.mig/plug-ins
  • Windows: C:\Users\[username]\.mig\plug-ins

Note

If a plug-in other than Rabbit is used, update the publisherServiceAssemblyName and subscriberServiceAssemblyName parameters in the appsettings.json file.

Start/Stop Informatics Gateway

To start or stop the Informatics Gateway, update the value of the DockerImagePrefix parameter in the appsettings.json file with the repository name of the Docker image (the default value is shown below):

{
    ...,
    "Cli": {
        "DockerImagePrefix": "ghcr.io/project-monai/monai-deploy-informatics-gateway"
    }
}

Lastly, use one of the following commands to start or stop the Informatics Gateway:

mig-cli start
mig-cli stop

Enable Incoming Associations

The next step is to configure the Informatics Gateway to enable receiving of DICOM instances from external DICOM devices.

  1. Configure a listening AE Title to receive instances:

    mig-cli aet add -a BrainAET -grouping 0020,000E, -t 30

    The command creates a new listening AE Title with AE Title BrainAET. The listening AE Title will group instances by the Series Instance UID (0020,000E) with a timeout value of 30 seconds.

    Each listening AE Title may be configured with one or more plug-ins to manipulate incoming DICOM files before saving to the storage service and dispatching a workflow request. To include input data plug-ins, first create your plug-ins by implementing the IInputDataPlugIn interface, then add the -p argument, with the fully qualified type name, to the mig-cli aet add command. For example, the following command adds the MyNamespace.AnonymizePlugIn and MyNamespace.FixSeriesData plug-ins from the MyNamespace.Plugins assembly file.

    mig-cli aet add -a BrainAET -grouping 0020,000E, -t 30 -p "MyNamespace.AnonymizePlugIn, MyNamespace.PlugIns" "MyNamespace.FixSeriesData, MyNamespace.PlugIns"

    [!Note] The -grouping argument is optional, with a default value of 0020,000D. The -t argument is also optional, with a default value of 5 seconds. For a complete reference, refer to the Configuration API.

  2. Enable the receiving of DICOM instances from external DICOM devices:

    mig-cli src add -n PACS-LA -a PACSLA001 --h 20.10.30.55

    The above command tells the Informatics Gateway to accept instances from AE Title PACSLA001 at IP 20.10.30.55 and port 104.

    [!Note] By default, Informatics Gateway blocks all unknown sources. To allow all unknown sources, set the dicom>scp>rejectUnknownSources parameter to false in the appsettings.json file.

    [!WARNING] The Informatics Gateway validates both the source IP address and AE Title when rejectUnknownSources is set to true. When the Informatics Gateway is running in a container and data is coming from the localhost, the IP address may not be the same as the host IP address. In this case, open the log file and locate the association that failed; the log should indicate the correct IP address under Remote host.

    See Data Plug-ins to configure data plug-ins or create your own data plug-ins.

Export Processed Results

If exporting via DIMSE is required, add a DICOM destination:

mig-cli dst add -a WORKSTATION1 -h 100.200.10.20 -p 104

The command adds a DICOM export destination with AE Title WORKSTATION1 at IP 100.200.10.20 and port 104.

Logging

See schema page for additional information on logging.