# HTTPS Apps

## Overview

{% hint style="success" %}
A license is required to run HTTPS applications on the DNAnexus Platform. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

Historically, DNAnexus applications have been used for batch executions and pipeline processing. Cloud Workstation is an example of an interactive use case for a DNAnexus worker and job, but it is accessible only via SSH configured for a single user.

DNAnexus jobs can be accessed interactively via a browser at `https://job-xxxx.dnanexus.cloud` via an HTTPS proxy which handles the necessary authentication. This allows a user to host an unencrypted web app within a job and rely on the platform to provide access and security.

## Quickstart

This application illustrates how to add `httpsApp` to your `dxapp.json` and run a hello-world web server with Docker. Listening on port 443 externally is the worker's HTTPS proxy, which authenticates the user with DNAnexus and generates a session for the browser.

After the job has been assigned and transitioned to the `running` state, the URL `https://job-xxxx.dnanexus.cloud` is created. This URL is accessible once it has propagated to your DNS server (generally within 60 seconds). Below is the source code for an applet running a web server on port 443.

### `src/hello-world-webapp.sh`

```shell
#!/bin/bash
# Example of running a web server with docker

main() {
    set -e -x -o pipefail
    # Pull tiny webserver docker images from DockerHub
    docker pull crccheck/hello-world:latest
    # Run docker container build
    # Mapping of port 443 to 8000 inside the docker container
    # 443 is accessible via https://job-xxxx.dnanexus.cloud
    docker run --name web-test -p 443:8000 crccheck/hello-world
}
```

### `dxapp.json`

To make the applet an HTTPS enabled, a new field `httpsApp` is required in the [`dxapp.json`](https://documentation.dnanexus.com/developer/apps/app-metadata) of the applet. This field requires `ports` and `shared_access` keys. `ports` is an array of integers with `443`, `8080`, and `8081` as allowed values. `shared_access` is a string, with `VIEW`, `CONTRIBUTE`, `ADMINISTER`, or `NONE` as possible values. This value restricts access to users with at least the specified access to the project in which the job executes, or to only the launching user if `NONE` is set. In this example access is restricted to DNAnexus users with at least VIEW access to the project in which the job executes.

Ubuntu 24.04 is recommended and has native support for `docker`. Outbound network access is enabled to pull the image from DockerHub.

```json
{
  "name": "httpsapp-hello-world",
  "title": "Example of an HTTPS applet",
  "summary": "httpsapp-hello-world",
  "dxapi": "1.0.0",
  "version": "0.0.1",
  "inputSpec": [],
  "outputSpec": [],
  "httpsApp": {
      "ports": [443],
      "shared_access": "VIEW"
  },
  "timeoutPolicy": {
    "*": {
      "hours": 72
    }
  },
  "runSpec": {
    "interpreter": "bash",
    "file": "src/hello-world-webapp.sh",
    "systemRequirements": {
      "*": {
        "instanceType": "mem1_ssd1_x4"
      }
    },
    "distribution": "Ubuntu",
    "release": "24.04",
    "version": "0"
  },
  "access": {
    "network": [
      "*"
    ]
  }
}
```

## Running and Accessing the Job

1. Build the applet

   ```shell
   dx build httpsapp-hello-world
   ```
2. Run applet

   ```shell
   dx run httpsapp-hello-world
   ```
3. Wait until job is running and get URL

   ```shell
   dx describe job-xxxx --json | jq .httpsApp
   {
     "dns": {
       "url": "https://job-xxxx.dnanexus.cloud"
     },
     "access": "VIEW",
     "ports": [
       443
     ],
     "enabled": true
   }
   ```
4. Navigate to `https://job-xxxx.dnanexus.cloud`

![](https://1612471957-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-L_EsL_ie8XyZlLe_yf9%2Fuploads%2Fgit-blob-27da004e027eb731fb884adbe67608e5467df264%2Fhttpsapp-hello-world.png?alt=media)

## Use Cases

* [JupyterLab](https://documentation.dnanexus.com/user/jupyter-notebooks)
* Interactive tools for exploring data

## Notes and Issues

* Accessing the URL for the first time redirects the browser to the DNAnexus login page for authentication, the browser then redirects back to the web application
* Sessions expire after 15 minutes of inactivity (defined as any HTTP request sent through the proxy), redirecting the user back to the DNAnexus login page
* It is possible to access the job via the HTTPS proxy before the application inside the job is ready to serve requests. This results in the `502 Bad Gateway` error. This happens because the application may have not finished setting up dependencies and is not running yet. It could also be configured to listen on an incorrect port.