docs/EMBEDDING.md

   1 # Embedding and Deploying noVNC Application
   2
   3 This document describes how to embed and deploy the noVNC application, which
   4 includes settings and a full user interface. If you are looking for
   5 documentation on how to use the core noVNC library in your own application,
   6 then please see our [library documentation](LIBRARY.md).
   7
   8 ## Files
   9
  10 The noVNC application consists of the following files and directories:
  11
  12 * `vnc.html` - The main page for the application and where users should go. It
  13   is possible to rename this file.
  14
  15 * `app/` - Support files for the application. Contains code, images, styles and
  16   translations.
  17
  18 * `core/` - The core noVNC library.
  19
  20 * `vendor/` - Third party support libraries used by the application and the
  21   core library.
  22
  23 The most basic deployment consists of simply serving these files from a web
  24 server and setting up a WebSocket proxy to the VNC server.
  25
  26 ## Parameters
  27
  28 The noVNC application can be controlled by including certain settings in the
  29 query string. Currently the following options are available:
  30
  31 * `autoconnect` - Automatically connect as soon as the page has finished
  32   loading.
  33
  34 * `reconnect` - If noVNC should automatically reconnect if the connection is
  35   dropped.
  36
  37 * `reconnect_delay` - How long to wait in milliseconds before attempting to
  38   reconnect.
  39
  40 * `host` - The WebSocket host to connect to.
  41
  42 * `port` - The WebSocket port to connect to.
  43
  44 * `encrypt` - If TLS should be used for the WebSocket connection.
  45
  46 * `path` - The WebSocket path to use.
  47
  48 * `password` - The password sent to the server, if required.
  49
  50 * `repeaterID` - The repeater ID to use if a VNC repeater is detected.
  51
  52 * `shared` - If other VNC clients should be disconnected when noVNC connects.
  53
  54 * `bell` - If the keyboard bell should be enabled or not.
  55
  56 * `view_only` - If the remote session should be in non-interactive mode.
  57
  58 * `view_clip` - If the remote session should be clipped or use scrollbars if
  59   it cannot fit in the browser.
  60
  61 * `resize` - How to resize the remote session if it is not the same size as
  62   the browser window. Can be one of `off`, `scale` and `remote`.
  63
  64 * `quality` - The session JPEG quality level. Can be `0` to `9`.
  65
  66 * `show_dot` - If a dot cursor should be shown when the remote server provides
  67   no local cursor, or provides a fully-transparent (invisible) cursor.
  68
  69 * `logging` - The console log level. Can be one of `error`, `warn`, `info` or
  70   `debug`.
  71
  72 ## Pre-conversion of Modules
  73
  74 noVNC is written using ECMAScript 6 modules. Many of the major browsers support
  75 these modules natively, but not all. By default the noVNC application includes
  76 a script that can convert these modules to an older format as they are being
  77 loaded. However this process can be slow and severely increases the load time
  78 for the application.
  79
  80 It is possible to perform this conversion ahead of time, avoiding the extra
  81 load times. To do this please follow these steps:
  82
  83  1. Install Node.js
  84  2. Run `npm install` in the noVNC directory
  85  3. Run `./utils/use_require.js --with-app --as commonjs`
  86
  87 This will produce a `build/` directory that includes everything needed to run
  88 the noVNC application.
  89
  90 ## HTTP Serving Considerations
  91 ### Browser Cache Issue
  92
  93 If you serve noVNC files using a web server that provides an ETag header, and
  94 include any options in the query string, a nasty browser cache issue can bite
  95 you on upgrade, resulting in a red error box. The issue is caused by a mismatch
  96 between the new vnc.html (which is reloaded because the user has used it with
  97 new query string after the upgrade) and the old javascript files (that the
  98 browser reuses from its cache). To avoid this issue, the browser must be told
  99 to always revalidate cached files using conditional requests. The correct
 100 semantics are achieved via the (confusingly named) `Cache-Control: no-cache`
 101 header that needs to be provided in the web server responses.
 102
 103 ### Example Server Configurations
 104
 105 Apache:
 106
 107 ```
 108     # In the main configuration file
 109     # (Debian/Ubuntu users: use "a2enmod headers" instead)
 110     LoadModule headers_module modules/mod_headers.so
 111
 112     # In the <Directory> or <Location> block related to noVNC
 113     Header set Cache-Control "no-cache"
 114 ```
 115
 116 Nginx:
 117
 118 ```
 119     # In the location block related to noVNC
 120     add_header Cache-Control no-cache;
 121 ```