---
title: "Extending interactive apps"
description: "Copy an existing VICE app, modify an existing tool's container, or build a new Docker-based tool and interactive app in the Discovery Environment."
type: Guide
tags:
- VICE
- Docker
- App Integration
generated:
by: "claude/opus-5"
at: "2026-09-11T00:00:00Z"
sources:
- id: cyverse-learning-materials
resource: "https://github.com/CyVerse-learning-materials/learning-materials-home/blob/b7392d21be4fd6a67d051847f98c81a18e058a12/docs/de/vice/extend_apps.md"
title: "CyVerse Learning Materials: docs/de/vice/extend_apps.md"
author: "team:cyverse"
last_modified: "2025-03-16T09:25:29-07:00"
---
# Extending interactive apps
There are several options to extend interactive apps for your specific use(s):
| Options | Hypothetical use case |
|---------|-----------------------|
| [Copy an Existing App](#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](#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](#create-a-new-tool) | 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 [CyVerse support](https://unm-carc.github.io/cyverse/getting-started/getting-help/) to ask about the availability of your favorite development environment.
??? tip "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
[de]: https://unm-carc.github.io/cyverse/assets/de/logos/deIcon.svg
[home]: https://unm-carc.github.io/cyverse/assets/de/menu_items/homeIcon.svg
[data]: https://unm-carc.github.io/cyverse/assets/de/menu_items/dataIcon.svg
[apps]: https://unm-carc.github.io/cyverse/assets/de/menu_items/appsIcon.svg
[analysis]: https://unm-carc.github.io/cyverse/assets/de/menu_items/analysisIcon.svg
Navigating the [![][de]{width=25}](https://de.cyverse.org){target=_blank} [Discovery Environment](https://de.cyverse.org){target=_blank}:
![][apps]{width=20} **Apps** - Applications (including VICE interactive applications)
Under "Apps" you will see "Tools" and "Instant Launches" -- for this section, we are interested in "Tools".
![][analysis]{width=20} **Analyses** - Status and history of analysis jobs
Analyses will be where you can test your new App to ensure it is functioning properly.
1. If necessary, log into the [![][de]{width=25}](https://de.cyverse.org){target=_blank} [Discovery Environment](https://de.cyverse.org){target=_blank}
2. Click the [![][apps]{width=20}](https://de.cyverse.org/apps){target=_blank} [Apps](https://de.cyverse.org/apps){target=_blank} 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.
3. 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".
4. 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.
6. Modify the Parameters as you see fit.
7. Save your new app. The app will be private, and is available under your "Apps Under Development" tab in [![][apps]{width=20}](https://de.cyverse.org/apps){target=_blank} [Apps](https://de.cyverse.org/apps){target=_blank}
## 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.
??? tip "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](https://github.com/cyverse-vice){target=_blank}, 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](https://github.com/cyverse-vice/jupyterlab-datascience){target=_blank} |
| 
| [RStudio Verse](https://github.com/cyverse-vice/rstudio-verse){target=_blank}|
| 
| [CloudShell](https://github.com/cyverse-vice/cli){target=_blank}|
| 
| [KASM Ubuntu Desktop](https://github.com/cyverse-vice/kasm-ubuntu){target=_blank} |
| 
| [VS Code](https://github.com/cyverse-vice/vscode){target=_blank} |
### Write your new Dockerfile
Create your own Dockerfile. We suggest using GitHub, and setting up a [GitHub Action](https://github.com/marketplace/actions/build-and-push-docker-images){target=_blank} 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](https://harbor.cyverse.org/harbor/projects/17/repositories/){target=_blank}, which uses a different naming convention than Docker Hub containers.
For example, for the Rocker Project's featured [RStudio Verse Latest](https://github.com/cyverse-vice/rstudio-verse){target=_blank} image, the `FROM` statement would be:
```{docker}
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:
```{bash}
$ docker build -t /rstudio/verse:custom-latest .
```
??? tip "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](https://hub.docker.com){target=_blank} or [quay.io](http://quay.io){target=_blank}. 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 [CyVerse support](https://unm-carc.github.io/cyverse/getting-started/getting-help/) and tell us what tool you are interesting in having us make as a VICE app.
## Create a new Tool
### Add Tool
1. If necessary, log into the [![][de]{width=25}](https://de.cyverse.org){target=_blank} [Discovery Environment](https://de.cyverse.org){target=_blank}.
2. Click the [![][apps]{width=20}](https://de.cyverse.org/apps){target=_blank} [Apps](https://de.cyverse.org/apps){target=_blank} and click on the "Manage Tools" wrench icon.
3. 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.
??? tip "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)](https://github.com/cyverse/irods-csi-driver){target=_blank} 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.
1. All commonly needed dependencies are installed in the container image - you will not have `root` privileges later.
2. The default user set.
3. Disable any additional authentication (CyVerse provides CAS authentication and authorization).
4. 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.
??? tip "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.
??? tip "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](https://github.com/cyverse-vice/rstudio-verse){target=_blank} 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.
??? tip "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](#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.
??? tip "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.
!!! info "Under the hood"
How interactive tools are deployed, proxied, and given Data Store access is described on the [VICE](https://docs.cyverse.org/deployment/06-applications/vice/){target=_blank} deployment page in the CyVerse Developer Documentation.
Adapted from [CyVerse Learning Materials](https://github.com/CyVerse-learning-materials/learning-materials-home/blob/b7392d21be4fd6a67d051847f98c81a18e058a12/docs/de/vice/extend_apps.md){target=_blank} (last source update 2025-03-16), CC BY 4.0. Spotted a problem? [Open an issue](https://github.com/UNM-CARC/cyverse/issues){target=_blank}.