2. Create and test a Dataloop app locally.

2.1. How to create and test Dataloop Applications?

2.1.1. Tl;dr

Tutorial ImageTutorial Image

  • Create a client-side app using the framework of your choice. Use our JS SDK to work with Dataloop entities.

  • Serve dataloop.json on the root of your application.

  • Serve this application on your local server on the local.dataloop.ai domain over HTTPS.

  • Open console.dataloop.ai and go to FaaS/Application Hub. Go to the Developer tab and click on Add Function.

  • Fill out the form and choose the type of your panel. eg: Item Viewer.

  • Go to the screen where your panel is used and trigger your panel and test the application.

  • Use the Browser console and Network tab to debug the application.

2.1.2. Too Short; Want More?

As a part of this tutorial, we will be creating and testing a react-based “Image Item Viewer” app and serving it using an Apache server. Through this app, you can view an image in a react application. Although, Dataloop runs on Micro-frontend architecture so you can write your application on any framework of your choice. For this tutorial, we are writing a react-based application.

2.1.3. Prerequisites:

  • Install Node.js for running the react based application.

  • install Apache server for serving your build on ports 80 and 443. You can use Nginx, Node.js, Python, etc based servers as well.

2.1.4. Create a React Application:

  1. Initiatialise a react-based application.

    npx create-react-app image-viewer

  2. Move to the react app folder.

    cd image-viewer

  3. Change the App.js file to render anything you want in your react application. eg: If you just want to show an image in your react app:

App.js
import './App.css';
import { useEffect, useState } from 'react';

function App() {
  const [ img, setImage ] = useState('');
  const [ width, setWidth ] = useState(0);
  const [ height, setHeight ] = useState(0);

  const handleFetch = async () => {
    const item = await window.dl.items.get()
    const stream = await window.dl.items.stream(item.stream)
    const width = item.metadata?.system.width
    const height = item.metadata?.system.height;
    setHeight(height)
    setWidth(width)
    setImage(stream)
  }

  useEffect(() => {
   const init = async function() {
    await window.dl.init()
    await window.dl.on('ready', async () => {
        console.log('ready')
        await handleFetch()
    })
  }
  init()
  }, []);

  return (
    <div className="App">
      <header className="App-header">
        <h1>
          Hello World
        </h1>
        <div>
          <img alt="item" src={img} height={height} width={width}>
          </img>
        </div>
      </header>
    </div>
  );
}

export default App;

  1. (Optional step) If you want to use the JD SDK of Dataloop, you can include it as an external script in your main index.html file located in the public folder. Keep it in the HEAD of the HTML.

<script src="https://console.dataloop.ai/dlAppLib.js"></script>

The dl object would now be globally available through the window object, i.e., window.dl. You can do a lot of stuff on all the Dataloop entities using DL. For using typescript please see below.

Read more about installing the SDK

2.1.5. Create a host:

  1. open /etc/hosts folder

    sudo vi /etc/hosts

  2. Register the domain by adding the following lines:

    127.0.0.1 local.dataloop.ai

2.1.6. Generate SSL certificate

We need to serve this application on HTTPS, so use OPENSSL to create an SSL certificate on your local machine.

```
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
```

Now, you can choose any option to serve your application over HTTPS. We have mentioned two ways here. One is using create-react-app and other is to use apache:

2.1.6.1. CREATE-REACT-APP:

There are various ways to enable HTTPS in the create-react-app’s local build.

Open package.json Locale scripts section and start command there. Rewrite the start command:

“start”: “HTTPS=true SSL_CRT_FILE=cert.pem SSL_KEY_FILE=key.pem react-scripts start”

Make sure the path of the file cert.pem and key.pem is correct.

Now, your application would be running on the default port 3000 on the following host: https://local.dataloop.ai:3000

2.1.6.2. APACHE SETUP:

  1. After creating your application, you should create a react build and move it to the /var/www/html/image-viewer folder for the Apache server to access it.

  2. Open the file file 000-default.conf.

sudo vi /etc/hosts/sites-available/000-default.conf

  1. Make changes to the file:

    DocumentRoot /var/www/html ====> DocumentRoot /var/www/html/image-viewer

  2. Move the cert.pem and key.pem files to the respective folders /etc/ssl/certs/ and /etc/ssl/private/

mv cert.pem /etc/ssl/certs/cert.pem
mv key.pem /etc/ssl/private/key.pem

  1. Go to the sites-available folder in the application. cd /etc/apache2/sites-available

  2. Open the default-ssl.conf file and make the following changes:

    • To the filename of the SSL certificate and private key as follows:

          SSLCertificateFile /etc/ssl/certs/cert.pem
    SSLCertificateKeyFile /etc/ssl/private/key.pem

    • To the DocumentRoot folder

      DocumentRoot /var/www/html ====> DocumentRoot /var/www/html/image-viewer

  3. Enable this site.

    sudo a2ensite default-ssl.conf

  4. Enable SSL in apache.

    sudo a2enmod ssl

  5. Restart Apache:

    sudo service apache2 restart

  6. Open https://local.dataloop.ai

Your react app should be running here.

2.1.7. Test the app locally

Before deploying your application, you want to test it in a fast manner. For that reason, we have the debug application feature, which allows you to run your application locally and test it on the platform, and see the changes immediately as they happen.

You will need the app manifest json, dataloop.json. These files define the meta configuration of your application and let the Dataloop OS know what to expect from your application.

The base route of your application should serve these files. eg: if your base route is: local.dataloop.ai then the dataloop.json file should be available at GET https://local.dataloop.ai/dataloop.json location.

Currently, there is no validation of the JSON file, it doesn’t affect the operation of the application.

<TODO: update the above line when the validation is done.>

Examples of a basic dataloop.json:

dataloop.json
{

  "components": {

    "panels": [

      {

        "name": "preview-modality",

        "minRole": "annotator",

        "supportedSlots": [

          {

            "type": "itemSidePanel",

            "configuration": {

              "route": []

            }

          }

        ],

        "conditions": {

          "resources": []

        },

        "icon": "icon-dl-sdk-documentation",

        "metadata": {},

        "defaultSettings": {

        }

      }

    ]

  }

}
dataloop.json
{
    "name": "item-viewer",
    "description": "Dataloop's image zoom viewer",
    "categories": [
        "viewer"
    ],
    "icon": "",
    "scope": "project",
    "components": {
        "panels": [
            {
                "name": "zoom-item-viewer",
                "supportedSlots": [
                    {
                        "type": "itemViewer",
                        "configuration": {
                            "layout": {
                                "leftBar": false,
                                "rightBar": false,
                                "bottomBar": false
                            },
                            "route": [ "/index.html" ]
                        }
                    }
                ],
                "conditions": {
                    "resources": [
                        {
                            "entityType": "item",
                            "filter": {
                                "metadata.system.mimetype": "image/*"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

  1. Open the Dataloop platform and locate the FaaS -> Application Hub on the and go to the Developer Tab.

  2. Click the Add function button at the top left corner

  3. Name your application, set the address to the appropriate URL (in our case it is local.dataloop.ai), and specify the required slot (We are testing for Item Viewer).

  4. And now you are ready to run your application. Locate an item in a sample dataset and right-click on it. Click the Open With option and Click on your application name. You would be able to see the text Hello World item if you used the given App.js file.

For any troubleshooting, you can see the browser console and network tab. Fix any issues you see regarding your application.

2.1.8. Using Typescript :

Add the following lines to the main.ts file:

declare global {

    interface Window {

        dl: any

        XFrameManager: any

        GuestAgent: any

    }

}

2.1.9. FAQ section:

Q. Why do we need the domain to be local.dataloop.ai to test the app locally? A: Dataloop AI platform needs to pass cookies to the guest application in order to authenticate the application and provide it access to the SDK backend.

Q. Why do we need HTTPS for running the application locally? A: Dataloop AI platform runs on HTTPS and it tries to access your dataloop.json file. If the local server is serving over HTTP and not on HTTPS, the Mixed-Content Policy of most of the browsers won’t allow the HTTP request for this dataloop.json file.