novnc.github.io

Embedding and Deploying noVNC Application

This document describes how to embed and deploy the noVNC application, which includes settings and a full user interface. If you are looking for documentation on how to use the core noVNC library in your own application, then please see our library documentation.

Files

The noVNC application consists of the following files and directories:

The most basic deployment consists of simply serving these files from a web server and setting up a WebSocket proxy to the VNC server.

Parameters

The noVNC application can be controlled by including certain settings in the query string. Currently the following options are available:

Pre-conversion of Modules

noVNC is written using ECMAScript 6 modules. Many of the major browsers support these modules natively, but not all. By default the noVNC application includes a script that can convert these modules to an older format as they are being loaded. However this process can be slow and severely increases the load time for the application.

It is possible to perform this conversion ahead of time, avoiding the extra load times. To do this please follow these steps:

  1. Install Node.js
  2. Run npm install in the noVNC directory
  3. Run ./utils/use_require.js --with-app --as commonjs

This will produce a build/ directory that includes everything needed to run the noVNC application.

HTTP Serving Considerations

Browser Cache Issue

If you serve noVNC files using a web server that provides an ETag header, and include any options in the query string, a nasty browser cache issue can bite you on upgrade, resulting in a red error box. The issue is caused by a mismatch between the new vnc.html (which is reloaded because the user has used it with new query string after the upgrade) and the old javascript files (that the browser reuses from its cache). To avoid this issue, the browser must be told to always revalidate cached files using conditional requests. The correct semantics are achieved via the (confusingly named) Cache-Control: no-cache header that needs to be provided in the web server responses.

Example Server Configurations

Apache:

    # In the main configuration file
    # (Debian/Ubuntu users: use "a2enmod headers" instead)
    LoadModule headers_module modules/mod_headers.so

    # In the <Directory> or <Location> block related to noVNC
    Header set Cache-Control "no-cache"

Nginx:

    # In the location block related to noVNC
    add_header Cache-Control no-cache;