Interactive Apps¶

There are several options to extend interactive apps for your specific use(s):

Options	Hypothetical use case
Copy an Existing App	You want to create a Quick Launch Button which has a different set of input data, specific to a course you're teaching
Modify an Existing Tool	You need to add new packages or libraries to an existing Featured App and Tool that requires building a new Docker Container
Create a New Tool & App	There are no existing App types which fit your needs. You need to develop your own Docker container and integrate it from start to finish

Depending on your specific needs, it may be easiest to copy an existing app or modify an existing tool. If you cannot find any existing Apps which suit your use case, do not hesitate to contact us via Intercom to ask about the availability of your favorite development environment.

Definitions

Tool - the Discovery Environment refers to Docker container templates as "Tools". The tool builder allows you to set the environment, UID, entrypoint, working directory, and computational requirements of your Docker container.

Apps - Applications, or "Apps", are the user interface that you build in the Discovery Environment to interact with our Tools. Apps are designed using a template builder.

Types of Tools include: executable, HPC, OSG (OpenScienceGrid), or interactive.

Apps may require input data, parameters, settings, and flags which the user selects each time they are run. executable, HPC, and OSG apps run non-interactively until they complete.

For interactive VICE apps, the App template may only include a set of input data files and folders, or nothing at all. VICE Apps use Kubernetes to orchestrate their launch.

Adding interactive Tools and Apps is different from adding executable Tools. VICE applications like Jupyter and RStudio run on open ports, enabling their User Interface (UI) in the browser.

Copy an Existing App¶

Navigating the Discovery Environment:

Apps - Applications (including VICE interactive applications)

Under "Apps" you will see "Tools" and "Instant Launches" -- for this section, we are interested in "Tools".

Analyses - Status and history of analysis jobs

Analyses will be where you can test your new App to ensure it is functioning properly.

If necessary, log into the Discovery Environment
Click the Apps icon in the left side of the navigation view. Or use the search bar to search existing public Apps for what you're interested in.
When you've found the app you want, click on the three vertical dots on the right side of the selection field and select "Copy App".
You will be taken to the App editor, where you can now give the Copy of App Name a new name. You can also change the App's Description and the Tool used by the App.
Modify the Parameters as you see fit.
Save your new app. The app will be private, and is available under your "Apps Under Development" tab in Apps

Modify an Existing Tool¶

Copying an App does not change the underlying Tool (Docker image). You may need to install some new system packages or software libraries that are too complex or take too long to compile on any of the public featured apps.

If you find that one of the existing public Apps, e.g. our Featured Apps, is useful but may be missing some key packages, you can take the next step of building a new container from our featured images.

Why use our Featured Images?

Some of the managed features that CyVerse provides for you are not available on publicly maintained Docker images of popular data science development environments.

For example, CyVerse adds a reverse proxy to allow RStudio to work behind our authenticated systems, and we install iRODS iCommands and other popular package managers and editors on all of our featured images.

By building a new container from our featured image set, you are assured that your new Docker image will work immediately in the Discovery Environment.

It is strongly recommended if you're using common IDEs like RStudio, Jupyter Lab, VS Code, Remote Desktops, or web-based applications like Shiny, Flask, or Streamlit, that you use one of our featured Docker images, or at least view our public Dockerfiles on GitHub, to ensure your new Container is compatible with the Discovery Environment.

Select a Featured Base Image¶

Each of these featured Apps have a public GitHub repository where their Dockerfile is available. The containers are hosted on CyVerse Harbor public/private Docker container registry.

Name	Dockerfile
	JupyterLab Datascience
	RStudio Verse
	CloudShell
	Xpra
	VS Code

Write your new Dockerfile¶

Create your own Dockerfile. We suggest using GitHub, and setting up a GitHub Action for building your container and pushing it to a public Docker Registry.

If you select a Featured App image, it will be pulled from our public Harbor Registry, which uses a different naming convention than Docker Hub containers.

For example, for the Rocker Project's featured RStudio Verse Latest image, the FROM statement would be:

FROM harbor.cyverse.org/vice/rstudio/verse:latest

You can then follow with your own ENV and RUN commands to do your own package installations.

Build your container as you normally would:

$ docker build -t <dockerhub-username>/rstudio/verse:custom-latest .

Selecting tag names

By default Docker gives the latest tag to containers without a : and trailing tagname.

You can modify your tagname in any way you see fit, but names like dev and latest should only be used for development or activities that do not require rigorous reproducability.

It is a good practice to use versioned tag names when preparing for peer-reviewed scientific publication.

Push your new image to a public container registry¶

After you have built your new image, you need to push it to a public Docker registry. We recommend Dockerhub or quay.io. The Discovery Environment can pull any public Docker image from any public/private registry.

We currently do not allow private Docker images to be pulled, but do contact us about special private container hosting in our Harbor registry if you have sensitive data or software needs.

Alternatively, you can provide us the Dockerfile of your requested image and we will build the Docker image for you.

If there is no Dockerfile for the tool that you are interested in, contact us via Intercom and tell us what tool you are interesting in having us make as a VICE app.

Create a new Tool¶

Add Tool¶

If necessary, log into the Discovery Environment.
Click the Apps and click on the "Manage Tools" wrench icon.
You'll see a list of all of the tools in the DE. Click on "More Actions" and select "Add Tool".

Add Tool

Tool name is the name of the tool. This will appear in the DE's tool listing dialog. This is mandatory field.
description is a brief description of the tool. This will appear in the DE's tool listing dialog.
version is the version of the tool. This will appear in the DE's tool listing dialog. This is mandatory field.
Type is the type of tool. For VICE apps, choose "interactive"; for command line applications, choose "executable".

Container Image

Image name is the name of the image and its public registry. This is mandatory field.
Tag is the image tag. If you don't specify the tag, the DE will look for the latest tag which is the default tag.
Docker Hub URL is the URL of the image on Dockerhub.
Entrypoint is the Entrypoint for your tool. Entrypoint should be present in the Docker image, and if not, you should specify it here.
Working Directory is the working directory of the tool and must be filled in with the value you gathered above, e.g., /home/jovyan/work.
UID is a number and must be filled in with the value you gathered from above. Typically root is 0 and default users are 1000.

Container Ports

Ports select the external port address that your graphic interface needs.

Restrictions

Max CPU Cores is the number of cores for your tool, e.g., 16
Memory Limit is the memory for your tool, e.g., 64 GB
Min Disk Space is the minimum disk space for your tool, e.g., 200 GB

Required settings¶

Set the `WORKDIR`¶

Executable apps to not require a working directory.

The container needs to have a set working directory (for interactive apps), typically this is the home folder, e.g., /home/jovyan or /home/rstudio .

Set the WORKDIR in the Dockerfile; if there is no set WORKDIR, you can set it in the Tool Builder.

Your Data in Your Container

We recommend that you set the working directory of your tool to the username home path in a new folder called work, e.g., /home/jovyan/work or /home/rstudio/work.

This is because the Discovery Environment's interactive apps use a Kubernetes container storage interface (CSI) driver that connects the CyVerse Data Store to your working directory in the running container. This new mount can clobber any pre-existing files in the the container's WORKDIR.

Set the `ENTRYPOINT`¶

The container must have an ENTRYPOINT set in the Dockerfile, otherwise you must set it in the Tool itself.

All commonly needed dependencies are installed in the container image - you will not have root privileges later.
The default user set.
Disable any additional authentication (CyVerse provides CAS authentication and authorization).
URLs will work sanely behind a reverse proxy. If they don't, you may need to add nginx to the container.

Set the `PORT`¶

Interactive Apps rely on open ports to send display information to the browser.

Ensure the listen port for the web UI has a sane default and is set in the Dockerfile, e.g. PORT 8888 .

You must set the port in the tool to the external port that the container is listening.

Understanding ports in Docker containers

For interactive containers like RStudio and JupyterLab, a conventional docker run execution will have the port set as -p 8888:8888 where the port number on the left side of the : is the external port, and on the right the internal port. For VICE apps you need only be concerned about the external port number.

Using a reverse proxy

The Discovery Environment has its own authentication system, which requires us to use a reverse proxy for some containers.

Our RStudio Server uses nginx to enable reverse proxy and thus we have changed the external port to 80 instead of the Rocker-Project default 8787 port number.

Managing ports in your new tool

Featured VICE apps have default port options based on the app: JupyterLab apps use port 8888, RStudio apps use port 80, and Shiny apps use port 3838.

It is strongly recommended you do not set the bind to host as true for your added ports when creating a new App.

Creating a VICE app for your new tool¶

After your tool template has been saved, you can create an App for connecting your tool to the Discovery Environment. You can copy an existing app and select your tool if you like an existing App's layout.

Alternatively, you can create a new app from a blank template.

Input data

For VICE apps, be sure to check the box "Do not pass this argument to the command line" for each option you add (for VICE, this is usually just input files and folders.