Skip to main content

Your First App

In this chapter, we'll walk you through building and deploying the Streamlit example from the Edge examples gallery.

The process we'll go through is roughly this:

  • Set everything up for development (tools, accounts)
  • Download the examples using git
  • Build and publish a Docker image
  • Create an application and application version record in Edge
  • Launch the app

Streamlit example

Above: a screenshot of the Streamlit example running on Edge.

Before you begin​

Required software​

Before starting, you'll need the following software tools installed on your computer.

  • Git version control tool.
  • The Enthought Deployment Manager (EDM), which we'll use to install Python and various libraries like Streamlit.
  • Docker. You will need at least the docker command-line tool, which can be installed via apt or yum on a Linux system. General instructions are here. There is also a (paid) "Docker Desktop" product which you may find useful, particularly if developing on a Mac or on Windows.
  • The Streamlit example also requires Node.js for some packages needed by the "preflight" tests.

After installing, ensure you can run the following command-line commands without error:

$ git --version
$ edm --version
$ docker --version
$ node --version

Required accounts​

  • An account on the Edge server where you want to deploy the app. This account will need the Developer license, and additionally you must have "developer" privileges on the Edge organization where you want to deploy.
  • An account on a Docker image registry, such as Docker Hub or Quay.
  • An account on Enthought's package server (or your organization's package server) with access to the enthought/edge package repository.

Required resources​

On the Docker image registry (Docker Hub, Quay.io, etc.), you will need access to a repository where the app image will be published. This repository will have a full name like quay.io/myorganization/myappname.

You should also request "machine credentials" (also known as a "robot account") with access to this repository. Edge will use those credentials to fetch the app image when it is launched.

Step 1: Clone the examples​

In a terminal run the following command:

$ git clone https://github.com/enthought/edge-examples

This will create an "edge-examples" folder. cd into it, and into the "Streamlit" folder:

cd edge-examples/Streamlit

Step 2: Configure your build environment​

See the README.md file in the Streamlit folder for instructions. In general, you will need to install a few Node and Python packages, and ensure your ~/.edm.yaml file has the correct package repositories listed.

You should also run docker login (or docker login quay.io, if using Quay) at this point, to ensure you will be able to push the images.

Finally, follow the README instructions ("Modifying the example for your use case" or similar section) to modify the example to use your Docker repository, rather than the default one.

Step 3: Build, test, and publish​

Follow the README instructions to build the application and run it locally. There is also a "preflight" command to test the application in a mode that mimics running in Edge. You should get the example running, and then run the "publish" command in the README to push it to your Docker repository.

Step 4: Create the Application record​

An "Application" record in Edge is needed before you can publish your app. This consists of an identifier and a small number of settings.

In the Edge Workbench, access the Settings page via the "gear" icon in the upper right-hand corner:

gear

Then, click "Create Application". You will need to provide a short identifier. This isn't user-visible, so something like my-app-id is appropriate. Finally, click "Save App":

new app

Step 5: Tell Edge where your image is located​

Select your new app, and click "New Server Info". Put in the domain (hub.docker.com, quay.io, etc.), and the robot account information needed to access the image:

server info

Step 6: Create the Application Version record​

The "Application Version" record is used to actually launch the app. It has the text and icon that will be displayed on the workbench tile, along with the full name of the Docker image, including tag.

Click "Create Version", and fill in basic information on your app. Some things to keep in mind:

  • Be sure "Kind" is set to "Native App".
  • See the example README for where to find the version. In general, the version will match the Docker image tag (part of the image name after the : character).
  • The icon should be a square PNG or JPEG image. 64x64 and 128x128 are common sizes.
  • For "Recommended Profile", start with Small and increase later if needed.

new version

Step 7: Launch your app!​

You should now see a new tile on the Workbench, with your app's title and logo:

my app

Click the tile and verify the app launches correctly.

Sharing your app with others​

By default, an app you create will have the "In Review" status. You can see this in the "General Settings" UI for your app. This means that the app will only be visible to other developers in your organization.

When you're ready, ask an organization administrator to "Approve" the app. This will make it visible to regular users with an Edge Essentials or Edge Plus license.

Please note that once an app is approved, an organization admin will need to intervene to make new versions visible. Or, if "Auto-add New Versions to Visible List" is checked, new versions will be visible automatically.

review

Next steps​

If the app works, congratulations! The next chapter has more information about how apps work internally, including environment variables and options for customization.

If not, see the section below, or contact support.

Common problems​

EDM reports "package not found"​

Verify that your ~/.edm.yaml file has at least these entries in the "repositories" section:

repositories:
  - enthought/free
  - enthought/lgpl
  - enthought/edge

There should also be an api_token entry in the authentication section:

authentication:
  api_token: <very_long_string_of_characters>

If this is missing, run edm create-token on the command line and follow the instructions. You can also see the official EDM docs for more info on configuring EDM.

Can't publish the Docker image​

Ensure the Docker daemon is running (run docker --version on the command line), and that you are logged in to the remote registry (docker login [registry-name]).

Double-check that the built image is using your Docker repository (e.g. quay.io/myorganization/myappname) rather than the default one (quay.io/enthought/edge-streamlit-example). The Streamlit example README will have instructions on how to modify this.

App fails to launch on Edge​

info

Be aware that "cold" app launch on Edge (i.e. without placeholders, which is the default) can take as long as 5 minutes.

First, double-check that you can run the example locally, in particular in "preflight" mode.

In Edge, also check the robot account credentials under Server Info. If these are incorrect or missing, Edge won't be able to pull the image.

Finally, you can contact Enthought support to request application logs.