2. Create and test a Dataloop app locally.¶
2.1. How to create and test Dataloop Applications?¶
2.1.1. Tl;dr¶
Tutorial 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 theDeveloper
tab and click onAdd 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:¶
Initiatialise a react-based application.
npx create-react-app image-viewer
Move to the react app folder.
cd image-viewer
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;
(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.
2.1.5. Create a host:¶
open /etc/hosts folder
sudo vi /etc/hosts
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:¶
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.Open the file file
000-default.conf
.
sudo vi /etc/hosts/sites-available/000-default.conf
Make changes to the file:
DocumentRoot /var/www/html ====> DocumentRoot /var/www/html/image-viewer
Move the
cert.pem
andkey.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
Go to the sites-available folder in the application.
cd /etc/apache2/sites-available
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
folderDocumentRoot /var/www/html ====> DocumentRoot /var/www/html/image-viewer
Enable this site.
sudo a2ensite default-ssl.conf
Enable SSL in apache.
sudo a2enmod ssl
Restart Apache:
sudo service apache2 restart
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/*"
}
}
]
}
}
]
}
}
Open the Dataloop platform and locate the FaaS -> Application Hub on the and go to the
Developer
Tab.Click the Add function button at the top left corner
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).
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.