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
- Build and publish a Docker image
- Create an application and application version record in Edge
- Launch the app
Above: a screenshot of the Streamlit example running on Edge.
Before you begin
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
dockercommand-line tool, which can be installed via
yumon 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
- 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
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
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
Step 2: Configure your build environment
README.md file in the Streamlit folder for instructions. In
general, you will need to install a few Node and Python packages, and
~/.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:
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":
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:
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
- The icon should be a square PNG image. 64x64 and 128x128 are common sizes.
- For "Recommended Profile", start with Small and increase later if needed.
Step 7: Launch your app!
You should now see a new tile on the Workbench, with your app's title and logo:
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.
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.
EDM reports "package not found"
Verify that your
~/.edm.yaml file has at least these entries in the
There should also be an
api_token entry in the
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
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
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.