# MayStreet Workbench EngineRoom Examples Springboard

## Welcome

Welcome to the EngineRoom Examples Springboard.

This Springboard provides a couple of example applications which can be hosted using Workbench's EngineRoom containers.
EngineRoom allows you to easily create and deploy long-running services which can be accessed by other users depending
on the permissions you configure.

## Reminder

Remember you can drag panels around in the UI so you can see several items at the same time; this
is helpful when you want to copy details from this README file into some of the Edit Service panels.

![images/drag-panels.gif](images/drag-panels.gif)

## Simple HTTP Service Example

This example provides a very simple HTTP API which can be used to return prices for a symbol.

The code is available at _[web-api-example/\_\_main\_\_.py](web-api-example/\_\_main\_\_.py)_.

In order to run this example application, please follow these steps:

### Create a Server to host Services
1. Click on the "Resources" sidebar tab.
2. In the "SERVERS" section, click the small plus icon to the right of the "SERVERS" caption.
3. Provide an example name, and select the first option of each list.

### Create a Service
1. Click on the "Jobs" sidebar tab.
2. In the "SERVICES" section, click the small plus icon to the right of the "SERVICES" caption.
3. In the "Edit Service" view that opened, provide the following options:
   - Name: anything you choose.
   - Description: leave blank
   - Type: Python Web Service
   - Port: 8000 (you might need to change the port if you already have a service with the same port in the same server). This port must match the port that your service's code listens on. In our case the `port` argument passed to `uvicorn.run` is 8000.
   - Subdomain: (enter a random subdomain personal to you; this cannot be shared)
   - Main file: click the "locate" icon to the right of the textbox and select _<your-sprinboard-folder>/web-api-example/\_\_main\_\_.py_.
   - Requirements: click the "locate" icon to the right of the textbox and select _<your-sprinboard-folder>/web-api-example/resources.txt_.
   - Server: select the server you created earlier.
4. Click _Save_ and close the "Edit Service" view.

### Deploy the Service
1. The service should now be visible in the "SERVICES" section. Hover your mouse over the service name and click the "Play" button
   that appears to start the server and deploy the service onto the server.
   - When the service has started you will see its status as "RUNNING" next to the service name.
2. Whilst the server is starting, create an API key you can use to invoke the service:
   - Click the "View" menu and choose "Command Palette..."
   - Enter or select "MST: New API Key".
   - Select the default duration (or customise it).
   - An API key will be created and opened in Workbench. Leave the editor panel open - you will need to copy the API key
     when you run a test later.

### Test the Service
1. Once the service has provisioned and started, there will be a URL visible in the "SERVICE" section. Hover your mouse
   over the URL and a small clipboard icon will appear on the right. Click it to copy the URL to the clipboard.
2. On your local machine, open a Terminal or Console and enter the following command, substituting the tokens for the values:
   - `curl --location --request GET '<<URL from clipboard>>/aapl-hourly-avg/2022/1/3'  --header 'Authorization: Bearer <<your API token>>'`
   - __Note: if you don't have `curl` then install it using your favourite package manager or Brew. You may also install Postman
     and import the cURL command above in Postman by selecting _File_ -> _Import_, selecting "Raw text" and pasting in the cURL
     command.__
3. Run the command. You will see output from the provided day in JSON.

## Advanced Dashboard Example

This example provides a full fledged example Dashboard built using our Streamlit integration.

- The code is available at _[web-dashboard-example/dashboard.py](web-dashboard-example/dashboard.py)_.
- The PWA manifest file is available at _[web-dashboard-example/dashboard_manifest.json](web-dashboard-example/dashboard_manifest.json)_

_Please feel free to explore and customise these files as much as you would like to!_

In order to run this example dashboard, please follow these steps:

### Create a Server to host Services (you may ignore this step if you've already created one as per the earlier instructions):
1. Click on the "Resources" sidebar tab.
2. In the "SERVERS" section, click the small plus icon to the right of the "SERVERS" caption.
3. Provide an example name, and select the first option of each list.

### Create a Service
1. Click on the "Jobs" sidebar tab.
2. In the "SERVICES" section, click the small plus icon to the right of the "SERVICES" caption.
3. In the "Edit Service" view that opened, provide the following options:
   - Name: anything you choose.
   - Description: leave blank
   - Type: Streamlit Application
   - Port: 8000 (you might need to change the port if you already have a service with the same port in the same server)
   - Subdomain: (enter a random subdomain personal to you; this cannot be shared)
   - Main file: click the "locate" icon to the right of the textbox and select _/home/workbench/web-dashboard-example/dashboard.py_.
   - Streamlit Web App Manifest file location: click the "locate" icon to the right of the textbox and select _/home/workbench/web-dashboard-example/dashboard_manifest.json_.
   - Server: select the server you created earlier.
4. Click _Save_ and close the "Edit Service" view.

### Deploy the Service
1. The service should now be visible in the "SERVICES" section. Hover your mouse over the service name and click the "Play" button
   that appears to start the server and deploy the service onto the server.

### Test the Service
1. Once the service has provisioned and started, there will be a URL visible in the "SERVICE" section. Hover your mouse
   over the URL and a small clipboard icon will appear on the right. Click it to copy the URL to the clipboard.
2. Open a browser window, and enter that URL into the Address bar; you will be able to see the UI. Note you are also
   able to install the application as a Portable Web Application (PWA). If you do so, you will able to install the
   application as a native application inside your Operating System.
3. You may also enter the same URL on a mobile phone and view it; you may also install the same application on your
   mobile phone as a Portable Web Application.

## Streamlit New Features
We have recently upgraded Streamlit 1.22.0 to 1.30.0. You can test the notable changes by deploying the Streamlit app available under the _[streamlit-new-features](streamlit-new-features)_ directory. 

- The code is available at _[streamlit-new-features/streamlit-new-features.py](streamlit-new-features/streamlit-new-features.py)_.
- The PWA manifest file is available at _[streamlit-new-features/streamlit-new-features-manifest.json](streamlit-new-features/streamlit-new-features-manifest.json)_

You can follow the steps of the [Advanced Dashboard Example](#advanced-dashboard-example).


## Support

For support, please email <support@maystreet.com>. Thank you.