Use custom apps

Prior reading: Cloud apps overview

Purpose: This document explains how to create custom apps in Workbench using dev containers.

Introduction

Verily Workbench users can create custom cloud apps that can be shared with other users in the same workspace. These apps can be run on GCE instances for GCP-based Workbench workspaces. Workbench uses development containers to support app configuration and management. The Development Container Specification for examples in Workbench can be found in the workbench-app-devcontainers repository.

Dev containers

Dev containers stands for "development containers." Workbench runs your apps in an isolated container in a VM. To define an app with a dev container, you must create a .devcontainer.json file.

Containerized apps

.devcontainer.json supports Docker images, Dockerfiles, and Docker Compose. To customize your container with Dockerfile or Docker Compose, see Using Images, Dockerfiles, and Docker Compose.

Dev Container Features

Besides Docker, Dev Container Features is a powerful dev container tool for adding tools and libraries into your containers. Here is a list of available features.

You can clone over the R Analysis Environment app example definition from workbench-app-devcontainers and then add your custom features. For example, if you want to add RShiny packages into R Analysis Environment, you can install the R packages through devcontainer-features/r-packages feature.

"features": {
        "ghcr.io/rocker-org/devcontainer-features/r-packages:1": {
            "packages": "shiny,shinydashboard",
            "installSystemRequirements": true
        }
    }

Create your own app with dev containers

If you want to create your own custom applications, the simplest way is to modify the Workbench template. Alternatively, see devcontainers/templates for more dev container templates. If you choose to use these templates, there are some Workbench specific requirements that you must satisfy:

1. The app must be running on app-network.
2. The app port is exposed on localhost.
3. If you want to sync the workspace bucket files to your working directory, set --cap-add SYS_ADMIN --device /dev/fuse --security-opt apparmor:unconfined to the Docker container.

Publish your custom app to Git

You can publish your custom app dev container to a public or private Git repository for Workbench to reference it. For examples of a custom app dev container, see Devcontainer for R Analysis.

Create and launch a custom app in Workbench

To launch the app from the Workbench UI, follow the steps below.

1. First, select Custom, then choose Next.

   

2. Provide your Git repository URL and the folder to your devcontainer.json definition if it's not in the root folder. It should look like this:

   

3. Continue creating your app by configuring CPUs, GPUs, and the autostop idle time. Once the app is created, its definition will be available for everyone in the workspace and will appear in the Select app list the next time you create a new app.

   

   Note

   If you don't have access to the GitHub repository where the defined devcontainer.json file lives, you'll see an error when trying to create the app.