Document collaboration for JupyterLab and JupyterLite, powered by y-webrtc
Project description
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
andusercolor
- e.g.
http://localhost:8888/lab?room=demo&username=jo&usercolor=e65100
- e.g.
- these parameters will probably be consumed, but that's okay
- e.g.
- 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
injupyter-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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jupyterlab-webrtc-docprovider-0.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a1578d88ed8e46c0b74af39df364eb73be60d494ab5ff7bad486c0ef9c04b668 |
|
MD5 | 8af830835acec5051379b8aa6595b1be |
|
BLAKE2b-256 | dce4382328f20d352a3c8bbc0c7eb7e17e78a51cb747a2536a590e10b4a2bda2 |
Hashes for jupyterlab_webrtc_docprovider-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f71e4720528adf44c437b5bf31a47fc493d06f1a7c59f5c2e2ae5e77bca90235 |
|
MD5 | f4fb0f687155e52c6997af7ac397873b |
|
BLAKE2b-256 | 7ce7dbca4569e933d95e5a6252cb2ec94ab45d781805d0dba9dc5e4444ba8e6a |