Writing Custom Applications#

Edge supports Custom Applications, which can be registered by organization developers. Once registered, custom applications are displayed as application tiles in Edge's home. These applications can take advantage of Edge's authentication system. There are three types of applications - Native, Dashboard and External applications.

Native Applications#

Native Applications are containerized web applications hosted by Edge's web server. These applications can be launched with different profiles on Edge, each with a variety of memory sizes, CPUs and even GPUs. With these Edge-provided resources, a Native Application can be designed to provide a web-based user interface for on-demand computational tasks such as image processing.

Dashboard Applications#

Dashboard Applications are containerized applications, similar to Native Applications. They are designed to provide simple applications that provide status graphs and other instrumentation. Dashboard Applications launch quickly and stay running, using a small Dashboard profile that provides enough memory and CPU resources to perform lightweight tasks.

External Applications#

External Applications are websites that are not hosted in Edge containers, but still appear as an application tile in Edge and benefit from Edge's user authentication. When a user launches an External Application they will be taken to the External Application's home page in a different browser window.

The Edge Application Model#

Applications are records stored in Edge. An Application record is identified by app_id, and can be associated with individual AppVersion records. Version records store all of the information record to display a tile in Edge's Home and any information required to launch the application. Individual versions can be made visible or hidden to users.

Native and Dashboard applications also require a ServerInfo record. This type of record stores the required credentials for accessing the Docker image repository where the application's image is stored.

Publishing an Application#

To publish an Application, first make sure that you are an organization developer. There are several requirements for publishing an application:

  • A Edge API Token

  • EDM, the Enthought Deployment Manager

  • The enthought_edge package from the enthought/edge EDM repository

  • An Native or Dashboard application image that has already been pushed to a Docker repository on quay.io, or the URL of an External Application

  • A quay.io username and password with access to the image repository

Creating an Edge API Token#

As an Organization Developer, you can create an Edge API Token. With your web browser, go to Edge's Token Manager. Here, you can create an API token for use with Edge.

Creating an Edge Token

Installing the enthought_edge Package#

The enthought_edge package is available in the enthought/edge EDM repository. Add this to your .edm.yaml can be installed via EDM using these shell commands:

edm environments create edge
edge shell -e edge
edm install enthought_edge

Working with an EdgeSession#

The enthought_edge package has an EdgeSession object, which provides convenient methods for interacting with Edge. You can use this code in an interactive Python session:

from edge.api import EdgeSession

edge = EdgeSession(
    service_url="https://edge.enthought.com/services/api",
    version_num=1,
    organization="<YOUR_ORGANIZATION>",
    api_token="<YOUR_API_TOKEN>"
)
edge.applications.list_application_ids()

This will list any applications that are currently available in your organization. If no applications have been registered, you will see an empty list.

Creating an Application#

The first step to publishing an Application and an associated Version is to create an Application record using the edge.apps.application.Application class:

from edge.apps.application import Application
app = Application('mynativeapp', True)
edge.applications.add_application(app)
edge.applications.list_application_ids()

This adds an application with the ID mynativeapp. The second parameter in the Application constructor makes any new versions added to the application automatically visible in the Home.

Adding Server information#

When Edge launches an Native or Dashboard application, it must pull the image from a Docker image repository. The repository may require a username and password. Therefore, we must also create a ServerInfo object with the name of the application, domain name of the image registry such as quay.io, and username and password for the image registry:

from edge.apps.server_info import ServerInfo
server = ServerInfo(
    app_id='mynativeapp',
    domain='quay.io',
    username='<QUAY_USERNAME>',
    password='<QUAY_PASSWORD>'
)
edge.applications.add_server_info(server)

Adding an Application Version#

The last step for publishing an application is to add an AppVersion object. The AppVersion object requires: * The Application object's ID * A version number * A title to go on the Application tile in Edge's Home * A description for the application * A base64 encoded image for the Application tile's icon * An AppKindEnum, either Native or External * A Docker image repository for Native apps, or a URL for External applications

In this example code, we will add a Native application:

from edge.apps.app_version import AppKindEnum, AppVersion

ICON = (
    "iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAYAAABXAvmHAAAABmJLR0QA/w"
    "D/AP+gvaeTAAABfklEQVRoge2ZTU7DMBBGHz9bECpLWAI36ZIdEvQa5Rpw"
    "CFQhtaq66o5wErgCWSR7KAvbUrGaFI8Tu5XmSZbjuFK/mS/jNjYoiqLsMp"
    "fAHKiBVeJWAwvgOkZ8mUG430rgQhLAfAfEuzZrEnnQEkANnAQG3RcVcLZp"
    "oi2AlTe+7UzO/1h6441aDxMI6ZUcASz5m11/HMTeO3Cc8Lv8LDeNg2pNHQ"
    "jAZdbPtCjzDnUgAK2BTWgN5CalAw4/01H/sfbeAQ0gN5IaOAJGwNBeF8AE"
    "+LHzna4y25AEMALu18Z3GPGTThQFIglgaPsx8NmhFhGSGhjYPrt4iPsdeM"
    "G8NxfAFPj25sVvWSHErEID4Bx4sM3xEaUokBgHxpgEPGHq4tXef/Q+16sT"
    "EgdK269vc/hbMMmQOFBgHpln714WJAFMbe+W0zdatv76RnfmctPmQAWcph"
    "KyhcbN3TYH3vvRIkK0SNwAX+Q/GyiBK0kAYE5GZhgLUwuvMIcsYvGKoij9"
    "8ws479akcYBsnQAAAABJRU5ErkJggg=="
)
version1 = AppVersion(
    app_id=app.app_id,
    version="1.0.0",
    title="Edge Native App Demo, v1.0.0",
    description="Demonstration of an native application",
    icon=ICON,
    kind=AppKindEnum.Native,
    link="quay.io/enthought/edge-native-app-flask-demo:latest",
)
edge.applications.add_app_version(version1)

Launching the Application#

At this point, the Application Version should be visible on the Edge Home Screen with the title "Edge Native App Demo, v1".

The Edge Home Screen

You can click on the tile to launch the example Native Application, which is an image processing app that identifies faces in images.