> For the complete documentation index, see [llms.txt](https://documentation.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.dnanexus.com/developer/apps/https-applications.md). # 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). The following source code shows 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 the applet ```shell dx run httpsapp-hello-world ``` 3. Wait until the job is running and get the 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 * On first-time access to the job URL, the browser redirects to the DNAnexus login page for authentication. After successful authentication, the browser 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 * You can access the job via the HTTPS proxy before the application inside the job is ready to serve requests, which results in the `502 Bad Gateway` error. This happens because the application may not have finished setting up dependencies and is not running yet. The application can also be configured to listen on an incorrect port. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://documentation.dnanexus.com/developer/apps/https-applications.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.