From 91e811f7af1ac3d340ce5db9e1c1b86f32d1c808 Mon Sep 17 00:00:00 2001 From: Pierre Ossman Date: Fri, 8 Dec 2017 16:25:41 +0100 Subject: [PATCH] Add documentation for integrating noVNC --- README.md | 9 +++++ docs/EMBEDDING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++ docs/LIBRARY.md | 35 ++++++++++++++++++++ 3 files changed, 127 insertions(+) create mode 100644 docs/EMBEDDING.md create mode 100644 docs/LIBRARY.md diff --git a/README.md b/README.md index 9121b6b9..dfc06edb 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,15 @@ proxy. configured, and enjoy! +### Integration and Deployment + +Please see our other documents for how to integrate noVNC in your own software, +or deploying the noVNC application in production environments: + +* [Embedding](docs/EMBEDDING.md) - For the noVNC application +* [Library](docs/LIBRARY.md) - For the noVNC JavaScript library + + ### Authors/Contributors * Core team: diff --git a/docs/EMBEDDING.md b/docs/EMBEDDING.md new file mode 100644 index 00000000..acaef62b --- /dev/null +++ b/docs/EMBEDDING.md @@ -0,0 +1,83 @@ +# 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](LIBRARY.md). + +## Files + +The noVNC application consists of the following files and directories: + +* `vnc.html` - The main page for the application and where users should go. It + is possible to rename this file. + +* `app/` - Support files for the application. Contains code, images, styles and + translations. + +* `core/` - The core noVNC library. + +* `vendor/` - Third party support libraries used by the application and the + core library. + +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: + +* `autoconnect` - Automatically connect as soon as the page has finished + loading. + +* `reconnect` - If noVNC should automatically reconnect if the connection is + dropped. + +* `reconnect_delay` - How long to wait in milliseconds before attempting to + reconnect. + +* `host` - The WebSocket host to connect to. + +* `port` - The WebSocket port to connect to. + +* `encrypt` - If TLS should be used for the WebSocket connection. + +* `path` - The WebSocket path to use. + +* `password` - The password sent to the server, if required. + +* `repeaterID` - The repeater ID to use if a VNC repeater is detected. + +* `shared` - If other VNC clients should be disconnected when noVNC connects. + +* `bell` - If the keyboard bell should be enabled or not. + +* `view_only` - If the remote session should be in non-interactive mode. + +* `view_clip` - If the remote session should be clipped or use scrollbars if + it cannot fit in the browser. + +* `resize` - How to resize the remote session if it is not the same size as + the browser window. Can be one of `off`, `scale` and `remote`. + +* `logging` - The console log level. Can be one of `error`, `warn`, `info` or + `debug`. + +## 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. diff --git a/docs/LIBRARY.md b/docs/LIBRARY.md new file mode 100644 index 00000000..63f55e8f --- /dev/null +++ b/docs/LIBRARY.md @@ -0,0 +1,35 @@ +# Using the noVNC JavaScript library + +This document describes how to make use of the noVNC JavaScript library for +integration in your own VNC client application. If you wish to embed the more +complete noVNC application with its included user interface then please see +our [embedding documentation](EMBEDDING.md). + +## API + +The API of noVNC consists of a single object called `RFB`. The formal +documentation for that object can be found in our [API documentation](API.md). + +## Example + +noVNC includes a small example application called `vnc_lite.html`. This does +not make use of all the features of noVNC, but is a good start to see how to +do things. + +## Conversion of Modules + +noVNC is written using ECMAScript 6 modules. Many of the major browsers support +these modules natively, but not all. They are also not supported by Node.js. To +use noVNC in these places the library must first be converted. + +Fortunately noVNC includes a script to handle this conversion. Please follow +the following steps: + + 1. Install Node.js + 2. Run `npm install` in the noVNC directory + 3. Run `./utils/use_require.js --as ` + +Several module formats are available. Please run +`./utils/use_require.js --help` to see them all. + +The result of the conversion is available in the `lib/` directory.