HTTPS Apps

Run applications that are accessible via HTTPS.

Overview

A license is required to run HTTPS applications on the DNAnexus Platform. Contact DNAnexus Sales for more information.

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.

Now DNAnexus jobs can be accessed interactively via a browser at https://job-xxxx.dnanexus.cloud via an HTTPS proxy which handles all of the necessary authentication. This allows a user to host an unencrypted webapp 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 will authenticate the user with DNAnexus and generate 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 propogated 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

#!/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 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.

{
  "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

   dx build httpsapp-hello-world

2. Run applet

   dx run httpsapp-hello-world

3. Wait until job is running and get URL

   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

Use Cases

• DXJupyterLab
• Interactive tools for exploring data

Notes and Issues

• Accessing the URL for the first time will redirect 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. The reason for this is that 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.