Skip to main content

Document collaboration for JupyterLab and JupyterLite, powered by y-webrtc

Project description

jupyterlab-webrtc-docprovider

install from PyPI reuse from npm install from conda-forge demo on Binder GitHub Actions

Document collaboration for JupyterLab, powered by y-webrtc.

Requirements

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:

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupyterlab-webrtc-docprovider-0.1.1.tar.gz (387.2 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file jupyterlab-webrtc-docprovider-0.1.1.tar.gz.

File metadata

File hashes

Hashes for jupyterlab-webrtc-docprovider-0.1.1.tar.gz
Algorithm Hash digest
SHA256 a1578d88ed8e46c0b74af39df364eb73be60d494ab5ff7bad486c0ef9c04b668
MD5 8af830835acec5051379b8aa6595b1be
BLAKE2b-256 dce4382328f20d352a3c8bbc0c7eb7e17e78a51cb747a2536a590e10b4a2bda2

See more details on using hashes here.

File details

Details for the file jupyterlab_webrtc_docprovider-0.1.1-py3-none-any.whl.

File metadata

File hashes

Hashes for jupyterlab_webrtc_docprovider-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f71e4720528adf44c437b5bf31a47fc493d06f1a7c59f5c2e2ae5e77bca90235
MD5 f4fb0f687155e52c6997af7ac397873b
BLAKE2b-256 7ce7dbca4569e933d95e5a6252cb2ec94ab45d781805d0dba9dc5e4444ba8e6a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page