Add documentation for integrating noVNC

diff --git a/README.md b/README.md
index 9121b6b9646ed5a4f027c105501a75fe6dccb1bf..dfc06edb86d0ff13fc3f7fd59f700aaf3c812882 100644 (file)
--- 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 (file)
index 0000000..acaef62
--- /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 (file)
index 0000000..63f55e8
--- /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 <module format>`
+
+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.