# 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 (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 HTTPS-enabled, a new field `httpsApp` is required in the [`dxapp.json`](/developer/apps/app-metadata.md) 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`

![](/files/-LiKV9CJcK5OAA02MOV1)

## Use Cases

* [JupyterLab](/user/jupyter-notebooks.md)
* 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.dnanexus.com/developer/apps/https-applications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.