Enable Real Time Collaboration#

JupyterLite can be extended to enable basic support for Real Time Collaboration over WebRTC.

Warning

Support for Real Time Collaboration in JupyterLite is still experimental.

There is basic support for JupyterLite 0.1.x.

Currently there is no support for JupyterLite 0.2.x, but it is tracked in this issue

Note

Prior to version 0.1.0b6, the WebRTC document provider was built directly into JupyterLite. While still enabled on the JupyterLite demo site, this feature was moved to a separate repository to allow for more configurability, UI customization, and independent iteration with some patches against upstream dependencies.

What is Real Time Collaboration?#

Real Time Collaboration (RTC for short) makes it possible for users to collaborate on the same document at the same time.

Here is an example screencast of what it looks like in JupyterLab:

rtc-demo

Since JupyterLite reuses most of the upstream JupyterLab components and plugins, it also gets support for RTC almost automatically.

The main differences compared to JupyterLab are:

the user content is decentralized: users store notebooks and files in their own browser local storage
the communication with peers and the initial syncing mechanism happens over WebRTC, instead of the WebSocket Jupyter Server handler in JupyterLab
- however, an initial WebSocket connection to one or more WebRTC Signaling Servers are made in order to help discover other peers
- a custom list of signaling servers can be configured with fullWebRtcSignalingUrls in jupyter-config-data

Enabling RTC in JupyterLite#

As an advanced feature with some privacy considerations, enabling collaborative editing requires a few steps to prepare for, deploy, and then use.

Install the Document Provider Extension#

Add jupyterlab-webrtc-docprovider which provides a prebuilt JupyterLab extension to your build environment’s environment.yml or requirements.txt, or install it interactively with one of:

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

As long as ignore_sys_prefix is not enabled, the extension will be discovered and included in the next jupyter lab build.

Enable the Collaborative Flag#

to set the collaborative flag setting in jupyter-config-data in the appropriate jupyter-lite.json configuration file:

{
  "jupyter-config-data": {
    "collaborative": true
  }
}

Note that each JupyterLite application can use its own jupyter-lite.json file to override global defaults.

Configure Rooms and Identity#

Enabling RTC in JupyterLite follows the same behavior as in JupyterLab 3.1 where real time collaboration is an opt-in feature.

In addition to the collaborative flag, end users must specify the room query parameter in the URL. An example of such URL is as follows:

https://your-lite-deployment.example.com/lab/index.html?room=4869637241

Similarly, the username and usercolor can be provided by settings or query parameters. This can be useful when generating a link in an external application that already provides identity.

Hint

Alternately, these can be configured via overrides.json, as described in the jupyterlab-webrtc-docprovider repository.

Users are grouped together in rooms using a combination of:

a room prefix: by default, the host, for example jupyterlite.example.com or myserver:5000
the name of the room parsed from the query string parameter or settings, for example my-custom-room

These values are then hashed together, such that requests to the upstream signaling server contain less easily-identifiable information.

Currently both collaborative and room must be configured for RTC to be enabled. When this is the case, users can collaborate on documents together:

rtc-rtd

See the reference section of the docs for more details on how to configure jupyter-lite.json.