jupyterlab-webrtc-docprovider

Document collaboration for JupyterLab, powered by y-webrtc.

Requirements

• Python >=3.7
• JupyterLab >=3.1
  • or a derived application like JupyterLite or RetroLab

How to Use It

• Install the package
• Configure your server for collaboration
• Launch a Lumino-based Jupyter client that supports collaboration
  • e.g. JupyterLab 3.1+, RetroLab 0.3+, or JupyterLite (beta)
• Open the client with the room URL parameters
  • e.g. http://localhost:8888/lab?room=demo
  • optionally provide username and usercolor
    • e.g. http://localhost:8888/lab?room=demo&username=jo&usercolor=e65100
  • these parameters will probably be consumed, but that's okay
• Open a shared editing activity like Notebook or Editor

Install

To install the extension, run:

                 pip install jupyterlab-webrtc-docprovider
mamba install -c conda-forge jupyterlab-webrtc-docprovider
conda install -c conda-forge jupyterlab-webrtc-docprovider

For a development install, see the contributing guide.

How it Works

Unlike JupyterLab's built-in, purely WebSocket-based collaborative document provider, jupyterlab-webrtc-docprovider relies on:

• an initialing signaling server to locate peers
• the WebRTC protocol to coordinate actual data exchange

Configuration

Server Configuration

Jupyter Server is configured with jupyter_server_config.json:

{
  "LabServerApp": {
    "collaborative": true
  }
}

collaborative

This flag must be enabled for the provider to be used.

In JupyterLite, this is a configurable of jupyter-config-data in jupyter-lite.json.

Client Configuration

User-configurable settings can be pre-populated in {sys.prefix}/share/jupyter/lab/settings/overrides.json: roomPrefix and signalingUrls are security-related.

{
  "@jupyterlite/webrtc-docprovider:plugin": {
    "disabled": false,
    "room": "an pre-shared room name",
    "roomPrefix": "a-very-unique-name",
    "signalingUrls": [
      "wss://y-webrtc-signaling-eu.herokuapp.com",
      "wss://y-webrtc-signaling-us.herokuapp.com",
      "wss://signaling.yjs.dev"
    ],
    "usercolor": "f57c00",
    "username": "Jo V. Un"
  }
}

In JupyterLite, this can be configured with an overrides.json

roomPrefix

By default, the final room ID that is actually sent to the signaling server will be the SHA256 hash of the configured room prefix and the chosen room name.

By default this prefix is the domain serving the site, but for common URLs (like localhost) a more random prefix should be chosen.

signalingUrls

By default, a number of public signaling servers are provided, as described by y-webrtc, as shown above.

Note: the signaling server, as the name suggests, should only know high-level metadata about your exchange, and should be protected from third-parties by standard SSL encryption.

However, a real deployment should not rely on free hosted services at runtime. Some research would be required to find an appropriate server for your specific deployment.

username

The name displayed to others next to your cursor in shared editing sessions.

usercolor

A suggested color of your cursor, as displayed to others next in shared editing sessions.

Uninstall

To remove the extension, run:

  pip uninstall jupyterlab_webrtc_docprovider
mamba uninstall jupyterlab_webrtc_docprovider
conda uninstall jupyterlab_webrtc_docprovider

Open Source

This work is licensed under the BSD 3-Clause License.

The code was originally extracted from JupyterLite and JupyterLab, which are also covered under the BSD 3-Clause License.

Two vendored patches (special thanks to @datakurre) are applied to simple-peer and int64-buffer, both of which are licensed under the MIT license, and should hopefully be merged some day.