{"id":28395181,"url":"https://github.com/databiosphere/terra-app","last_synced_at":"2025-08-14T07:47:10.338Z","repository":{"id":42087032,"uuid":"315418328","full_name":"DataBiosphere/terra-app","owner":"DataBiosphere","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-05T18:40:58.000Z","size":30541,"stargazers_count":5,"open_issues_count":5,"forks_count":4,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-06-27T01:38:26.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataBiosphere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-23T19:24:20.000Z","updated_at":"2023-02-28T21:15:34.000Z","dependencies_parsed_at":"2023-02-16T20:31:38.447Z","dependency_job_id":"6dbbc02d-832d-4986-80c7-11aa97d5f63c","html_url":"https://github.com/DataBiosphere/terra-app","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/DataBiosphere/terra-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataBiosphere","download_url":"https://codeload.github.com/DataBiosphere/terra-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270385320,"owners_count":24574544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-31T19:39:25.412Z","updated_at":"2025-08-14T07:47:10.329Z","avatar_url":"https://github.com/DataBiosphere.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terra Applications\n\nThis repo contains tooling for launching custom approved apps in [Terra]([https://app.terra.bio/).\n\n**Note this project is under active development, and may not be fully functional yet.**\n\n## Table of Contents\n\n- [Architecture](#architecture)\n- [App Schema](#app-schema)\n- [Supported Apps](#supported-apps)\n- [Launching an App Locally](#launching-an-app-locally)\n- [Launching an App on Terra](#launching-an-app-on-terra)\n- [Helm Chart](#helm-chart)\n- [Publishing `terra-app-charts` Helm Chart](#publishing-terra-app-charts-helm-chart)\n\n# Architecture\n\nApps are defined by a YAML [schema](#app-schema). An \"app launcher\" (such as Terra) receives a request to launch an app, parses the app YAML file, and invokes the [helm chart](#helm-chart) with the appropriate values to launch the app on a Kubernetes cluster. Once the app is launched, it may be accessed by the end user in a browser via a proxy URL defined by the app launcher.\n\nDiagram of the app launch flow:\n\n![Leo - Custom Apps](Leo%20-%20Custom%20Apps.png)\n\n[Lucidchart source](https://lucid.app/lucidchart/invitations/accept/35f8ee43-e1d7-43e2-94d2-65076c08c84d)\n\n# App Schema\n\n*Note: the schema is under evolution!*\n\nHere is a description of the app YAML schema:\n\n```\n# Short name of the app, for example 'jupyter'. This is used to name some Kubernetes resources,\n# for example the namespace is generated as 'jupyter-ns'.\nname: jupyter\n\n# Maintainer of the app. Informational only.\nauthor: workbench-interactive-analysis@broadinstitute.org\n\n# Longer description of the app. Informational only.\ndescription: |\n  Jupyter Notebook, Python and R kernels, GATK packages\n  \n# Version of the app. Informational only.\nversion: 1.0.14\n\n# List of services the app exposes.\n# NOTE: currently only one service is supported by the helm chart. In the future we may explore multi-service apps.\nservices:\n  jupyter:\n    # The app docker image. Required.\n    image: \"us.gcr.io/broad-dsp-gcr-public/terra-jupyter-gatk:1.0.14\"\n    \n    # Port the app listens on. Required.\n    port: 8000\n    \n    # Optional. If the app is configured to listen on a base URL path, specify it here.\n    # If absent, we assume the app listens on / and we will set up an nginx reverse proxy based on\n    # the service name. However, not all apps are guaranteed to behave correctly under reverse proxies;\n    # so if possible, configure your app with a base URL.\n    baseUrl: \"/jupyter/\"\n    \n    # Optional. Specifies a startup command and arguments for the app. This overrides the Dockerfile\n    # ENTRYPOINT if present.\n    command:  [\"/usr/local/bin/jupyter\"]\n    args: [\"notebook\"]\n    \n    # Optional. Specifies the mount point for an attached PD and the access mode (ReadWriteOnce or ReadOnlyMany\n    # for read-write or read-only disks respectively). If absent no persistent volumes will be created.\n    pdMountPath: \"/data\"\n    pdAccessMode: \"ReadWriteOnce\"\n    \n    # Optional. Specifies environment variables to be present in the container.\n    environment:\n      WORKSPACE_NAME: \"my-ws\"\n      WORKSPACE_NAMESPACE: \"my-proj\"\n```\n\n# Supported Apps\n\nExample apps can be found in this repo under [apps](/apps). View the following for more details:\n\nIf an app is in this list, it should have a working smoke test run on PRs. See the testing section for details \n\n[cellxgene](apps/cellxgene)\n\n[cirrocumulus](apps/cirrocumulus)\n\n[jupyter](apps/jupyter)\n\n[rstudio](apps/rstudio)\n\n[ucsc_genome_browser](apps/ucsc_genome_browser)\n\n# Launching an App Locally\n\nThis repo contains a `terra-app-local.sh` script which can launch apps on a locally running [minikube](https://minikube.sigs.k8s.io/docs/) cluster. This can be much more convenient for development than launching apps against Terra.\n\nBefore running the script:\n1. Install a few script dependencies according to instructions here:\n    - [`minikube`](https://minikube.sigs.k8s.io/docs/start/)\n    - [`helm`](https://helm.sh/docs/intro/install/)\n    - [`yq`](https://github.com/mikefarah/yq)\n2. Start `minikube` service.\n   a. On Mac (Catalina) I start it with the command (when NOT connected to a VPN):\n     ```\n     minikube start --mount --mount-string=\"/Users/[USERNAME]/data:/data\" --kubernetes-version=v1.21.0\n     ```\n     Replace the data directory with the directory you want to mount into your persistent volume (or omit if not using persistence).\n    \nOnce `minikube` is running, you can run the script. Here is the usage:\n```\n$ ./terra-app-local.sh \nterra-app-local.sh deploys an app on a local minikube cluster.\n\n Find more information at: https://github.com/DataBiosphere/terra-app\n\nUsage:\n  terra-app-local.sh [command]\n\nAvailable commands:\n  install       installs an app\n  uninstall     deletes an app\n  status        displays stats about an app\n  list          lists all apps\n  show-kubectl  prints kubectl commands to interact with an app\n\nFlags:\n  -h, --help    display help\n\nUse \"terra-app-local.sh [command] --help\" for more information about a command.\n```\n\nExample:\n```\n$ ./terra-app-local.sh install -f apps/jupyter/app.yaml\n```\n\n# Testing\nThe script detailed in the local launching section, `terra-app-local.sh`, is also used to smoke-test supported apps on merges to this repo. If you are adding an app, and want it to be automatically tested, be sure to add it to the `app` `matrix` in the github action file. \n\nThese smoke-tests DO NOT test against Terra/Leonardo. It may be desirable to have a dedicated test in leonardo pegged to a specific version of an app.yaml. This is not possible until we begin publishing and versioning these app yaml. See https://broadworkbench.atlassian.net/browse/IA-2495.  \n\n# Launching an App on Terra\n \nLeonardo has an endpoint that takes an app descriptor and various arguments. See the [swagger](https://leonardo.dsde-dev.broadinstitute.org/#/apps/createApp) documentation for the endpoint, and the associated `CreateAppRequest` schema (located near bottom of swagger specification). \n\n# Helm Chart\n\nThere are three helm charts inside this repo:\n\n1. [terra-app-setup-chart](terra-app-setup-chart): this chart sets up common infrastructure used by Galaxy and Terra custom apps.\n2. [terra-app-chart](terra-app-chart): this chart deploys Terra custom apps.\n3. [terra-app-helm/aou-rstudio-chart](terra-app-helm/aou-rstudio-chart): this chart deploys the fully customizable RStudio app from scratch and do not follow the custom app model\n\nThe charts are deployed to the following repos:\n```\nhelm repo add terra-app https://terra-app-charts.storage.googleapis.com\nhelm repo add terra-app-setup https://terra-app-setup-chart.storage.googleapis.com\nhelm repo add aou-rstudio-chart https://storage.googleapis.com/terra-app-helm/aou-rstudio-chart\nhelm repo update\n```\n```\n$ helm show chart terra-app/terra-app\napiVersion: v2\ndescription: Chart for deploying Terra applications\nname: terra-app\ntype: application\nversion: 0.3.0\n\n$ helm show chart terra-app-setup/terra-app-setup\napiVersion: v2\ndescription: Chart for set up entities for deploying Terra applications\nname: terra-app-setup\ntype: application\nversion: 0.0.1\n\n$ helm show chart aou-rstudio-chart/aou-rstudio-chart\napiVersion: v2\ndescription: Chart for deploying Rstudio to All of Us Workbench\nname: aou-rstudio-chart\ntype: application\nversion: 0.1.0\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabiosphere%2Fterra-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabiosphere%2Fterra-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabiosphere%2Fterra-app/lists"}