Deploy a linux-container application

In this tutorial we will show:

• How to onboard linux docker image onto the "AIRC Research" prototyping environment.
• How to create OAF package

For this purpose we will use a simple example and show each step required to have it running in "AIRC Research" as well as in "Open Apps".

For some general background on how to develop Frontier Fusion prototypes please see Getting Started.

note

Our example uses Python as a popular language for AI driven applications. However, during the tutorial it will become clear how to onboard any prototype that adheres to the boundary conditions described here, not just Python...

In this example we will use a prototype that is processing-only. Hence, no UI parts (for configuration as well as viewing/confirming results) need to be developed and onboarded. Obviously, this is the most simple kind of prototype and many real-world prototypes will at least require a configuration UI. However, for the sake of simplicity we leave this out in this example. There will be more examples and tutorials which will demonstrate the UI aspects. In particular the next tutorial is showing how to extend this example with a generic configuration UI without the need for programming.

Python scripts

Python scripts are per se no windows executables. As described in Getting Started the Frontier developer portal currently only allows to onboard Windows executables. In this guide we are showing an easy way to create a self-contained Windows executable from a Python script. Afterwards we will onboard this executable using the Frontier developer portal.

The example itself is rather simplistic and only performs an image rotation by a configured angle. It is primarily used to demonstrate how to read input and configuration data, perform some processing and store the results. While this part will be similar in a real prototype, the processing part obviously needs to be replaced with the real processing.

The example: DicomImageRotator

Overview

'DicomImageRotator' is a non-interactive python windows application that accepts command-line arguments. It reads the DICOM images provided in the source folder and rotates DICOM images with an angle provided in the configuration file. Rotation angle by default is 90 degrees. Rotated images are then saved in the output folder.

The following image shows an example processed with this script (in the teamplay DICOM hub UI):

Project Structure

The source code of the example is available here.

The files are structured in the following way:

\---PythonWinApp
    |
    \---DicomImageRotator
        | DicomImageRotator.py --> Entry-point script
        | DicomImageRotator.spec
        | README.md
        |
        \---ImageRotator
                RotateImage.py
                __main__.py
    \---config
        | RotateAngleConfig.json
    \---in
        | sample_xray.dcm
    \---out
    \---log

DockerFile

The docker file needed to create a docker image is available here

Application usage

To get a feeling for what the example app does and to test it before deploying, navigate to the top-level folder of the downloaded example ("PythonWinApp") and execute the script locally.

The onboarding steps:

Step 1: Prerequisites

Prerequisites

• Prepared Linux DockerImage of an application which rotates images
• Access to Developer portal & Teamplay (needs to have access to institution)

Preparation of Linux dockerImage

1. Move your downloaded unzipped dockerfile and the PythonRotatorApp to the same folder.
2. Open your powershell and move into the folder location.
3. Enter to your powershell following command:
   docker build . -t dicomrotatorimageexample

Step 2: DevPortal: Create new app

Go to the "Applications" tab in the dev portal. Create a new application in the dev portal by pressing the add button ("+").

The following dialog will be shown:

Please note that the technical name must be unique (will be checked) and can currently only contain lowercase characters and the '-' character. Unfortunately these are technical restrictions based on the usage of the technical identifier in the names of several cloud services. The application name will be used in the dev portal but also in the final deployment to identify the prototype on the UI.

Step 3: DevPortal: Configure new app

After creation of the application we need to provide more detailed configuration metadata, create deployable artifacts and finally deploy those to the target runtime environment. The respective screen is automatically shown after creation. These steps are done in the following screen split into two tabs, which we will navigate through in this tutorial. You can always come back to this screen by clicking the application in the application list.

The first tab is the configuration screen. We can leave all configurations with the default settings but before leaving we need to upload the terms and conditions file, for this purpose use please any .pdf file:

Optionally, if you wish to add licensing, you can do so now, following these steps

In the dataSelection part of configuration we need to choose default accepted Data types for this tutorial choose:

CR, X-Ray For Presentation and Processing, CT and MR images.

Do not forget to press the "Save" button in the top right corner.

Step 4: DevPortal: Upload container image

After completion of the configuration we go to the next step, i.e. the next tab: "Processing Unit". Click the Add button ("+") in the lower right corner and select ContainerImage.

In the first step setup the mount path configuration - for our example fill with paths shown in the image, for future uses paths must be unique, linux style so no backslashes, have to start with / and cannot end with /, also cannot contain invalid path characters and whitespaces. After completing the setup press Proceed with image upload. This transition can take some seconds, afterwards you enter the second page.

At the second page you have prepared three commands, first to tag your image, second to login to docker repository and last to push your docker image. After you copied the commands you can close the window and you can see that your processing unit is in the state of creation. In the case you accidentally leave the page without copying the commands you can still access them with the information button in the processing unit list.

For successfully uploading your image you need :

1. tag your image with the command : docker tag dicomrotatorimageexample < tag value from the textfield >
2. use docker login command
3. use docker push command Example of sucessfully running all the commands. If your binary looks like this you can continue to the next step. (After uploading this image it can take few minutes until the upload is confirmed in the UI).

Step 5: DevPortal: Deploy to target environment

The final step is to perform the actual deployment of the created deployment artifacts. This is where the two different deployments "Open Apps" and "AI Rad Companion Research" require different user actions.

AIRC and Open Apps Deployments

The deployment into the AIRC Research or Open Apps environment can be achieved using the second tab of the applications details screen: "Deployments" the target environment is based on configuration. If this is the first deployment expect the list to be empty. Click the "+" button to add a new deployment:

In this menu we choose ProcessingUnit or in the following UI binary which we uploaded before. In the last step we select where to deploy our application. For the purpose of this tutorial we select the "Airc" environment. We set Expiration date to at least one day over the current date and continue the wizard, after verifying all is correct press Create.

Give it some time for the deployment to finish. You can leave the page and come back later. Successful deployment will be indicated by a green "airc-lab32" button.

Open Apps

For OpenApps there will be a possibility to push the generated deployment artifact ("OAF" file) directly to the respective marketplace. However, this is still under development. Therefore we are offering to download the generated OAF file. Afterwards, this OAF file can be installed on a "syngo.via" system of your choice (or any Open-Apps-capable system, for that matter) using a simple install wizard.

For directly downloading the generated OAF file click the "Download Artifact" button. However, in some cases it can be more convenient to download the OAF file directly onto the system where it needs to be installed. For this purpose we also offer to copy the download link ("copy artifact link" button) and execute it on the target system. The link has a validity of 30 minutes and both options are provided in OpenApps button...

Step 6: Check deployed app appears in "AIRC Research"

After successful deployment to AIRC Research, we check if the prototype is visible in the AIRC Research "General Configuration" section. For this purpose we need to login to the teamplay Sandbox environment. Select an institution that has access to AIRC Research Frontier prototypes and open the "AIRC Research lab32" application (subject to change!):

Open the configuration and check the "General" section:

Find the "Tutorial C" app and enable it. Disable all the other apps for now. Do not worry about the "Allow data sharing" option at this time.

note

• Obviously, when, at a later point in time, also other environments are supported, you need to login to the respective other environment instead of the Sandbox environment.
• In order to enable a teamplay institution for "AIRC Research Frontier", the AI_RAD_RESEARCH_FRONTIER_EXTENSION license (in addition to AI_RAD_RESEARCH_ENGINE license) needs to be granted as well as the corresponding feature flags (at the time of writing the feature flags are granted automatically). More details will be provided.

Step 7: Test deployed app

To test our prototype we will use "teamplay DICOM Hub" to upload and send a DICOM image to our app and receive the result back. Remember, the result should be a rotated version of the input image.

Upload the example image from the provided ZIP file (see above) and upload it to "teamplay DICOM Hub". Make sure that you select "AIRCResearch lab32 WEU" as the target application already during upload:

After uploading the image should be visible in the "All Studies" section and can be send to "AIRCResearch lab32 WEU":

After some time the case should become visible in the AIRC Research "Queued" list:

And after some more time, the case should be finished processing and moved to the "Completed" list. The results would than be visible in the "teamplay DICOM Hub" again:

Step 8: Have a look at the logs

The developer portal gives you the opportunity to access the logs related to your prototype. However, currently this is only possible for the "AIRC Research" cloud deployment. For the Open Apps deployment, you need to get the logs directly from the system or via SRS.

In order to access the logs go to the deployment section of the application. Click the button for the respective deployment and select the "Application Logs" entry:

Congratulations, you have successfully finished the self-onboarding of your first containerImage-based app using the Frontier developer portal!