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.
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:
OSG (OpenScienceGrid), or
Apps may require input data, parameters, settings, and flags which the user selects each time they are run.
OSG apps run non-interactively until they complete.
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.
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 Namea 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.
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:
You can then follow with your own
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
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¶
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".
Tool nameis the name of the tool. This will appear in the DE's tool listing dialog. This is mandatory field.
descriptionis a brief description of the tool. This will appear in the DE's tool listing dialog.
versionis the version of the tool. This will appear in the DE's tool listing dialog. This is mandatory field.
Typeis the type of tool. For VICE apps, choose "interactive"; for command line applications, choose "executable".
Image nameis the name of the image and its public registry. This is mandatory field.
Tagis the image tag. If you don't specify the tag, the DE will look for the
latesttag which is the default tag.
Docker Hub URLis the URL of the image on Dockerhub.
Entrypointis the Entrypoint for your tool. Entrypoint should be present in the Docker image, and if not, you should specify it here.
Working Directoryis the working directory of the tool and must be filled in with the value you gathered above, e.g.,
UIDis a number and must be filled in with the value you gathered from above. Typically
0and default users are
Portsselect the external port address that your graphic interface needs.
Max CPU Coresis the number of cores for your tool, e.g., 16
Memory Limitis the memory for your tool, e.g., 64 GB
Min Disk Spaceis the minimum disk space for your tool, e.g., 200 GB
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.,
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
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
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
- 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.
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
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.
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.