https://github.com/jupyter-server/synchronizer
A Jupyter Server Session Manager that rehydrates and persists.
https://github.com/jupyter-server/synchronizer
Last synced: 2 months ago
JSON representation
A Jupyter Server Session Manager that rehydrates and persists.
- Host: GitHub
- URL: https://github.com/jupyter-server/synchronizer
- Owner: jupyter-server
- License: bsd-3-clause
- Created: 2022-04-05T16:56:34.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-13T16:07:07.000Z (almost 2 years ago)
- Last Synced: 2025-09-28T08:22:25.396Z (3 months ago)
- Language: Python
- Homepage:
- Size: 153 KB
- Stars: 8
- Watchers: 6
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: COPYING.md
Awesome Lists containing this project
README
# Jupyter Server Synchronizer
[](https://github.com/jupyter-server/synchronizer/actions/workflows/python-tests.yml/badge.svg?query=branch%3Amain++)
[](https://codecov.io/gh/jupyter-server/synchronizer)
A Jupyter Server Session Manager that persists and rehydrates kernel sessions beyond the lifetime of a server.
This is particularly useful for Jupyter Servers running remote kernels and contents.
## Basic usage
Install and enable the extension:
```
pip install jupyter_server_synchronizer
jupyter server extension enable jupyter_server_synchronizer
```
When you start a Jupyter Server, it synchronize all managers before the Web application is started.
```
jupyter server --ServerApp.session_manager_class=jupyter_server_synchronizer.SynchronizerSessionManager
```
To synchronize periodically, enable the auto-synchronizing feature using the `autosync` config option. For example,
```
jupyter server --ServerApp.session_manager_class=jupyter_server_synchronizer.SynchronizerSessionManager --SynchronizerSessionManager.autosync=True
```
Otherwise, you can trigger the synchronization making a `POST` request to the `/api/sync` endpoint.
## Example
Below is a example of running the synchronizer with Jupyter Server talking to a Jupyter Kernel Gateway as its "remote" kernel service provider.
First, start the Kernel Gateway. You'll need to enable the `list_kernels` method. In the example, we are assuming the Kernel Gateway is _not_ multi-tenant; i.e. there is a single KG for a single Jupyter Server. We'll set the port to `9999` to free up `8888` for our Jupyter Server.
```
jupyter kernelgateway \
--port 9999 \
--JupyterWebsocketPersonality.list_kernels=True
```
Second, start the Jupyter Server and point it at the Kernel Gateway. Note that we set a `database_filepath` trait in both the `SessionManager` and `SynchronizerExtension` (these paths don't need to be the same). The Synchronize relies on saving/storing of information about Jupyter kernels and sessions in a persistent database. This information is necessary to rehydrate and synchronize.
We'll enable the "autosync" feature to periodically synchronize the server.
```
jupyter lab \
--gateway-url=http://127.0.0.1:9999 \
--ServerApp.session_manager_class=jupyter_server_synchronizer.SynchronizerSessionManager
--SynchronizerSessionManager.database_filepath=jupyter-database.db \
--SynchronizerSessionManager.autosync=True \
--SynchronizerSessionManager.log_level=DEBUG
```
Now, let's kill that server:
```
kill -9 $(echo $(pgrep -lf jupyter-lab) | awk '{print $1;}')
```
And restart it to see if the kernels rehydrate and begin synchronizing again.
```
jupyter lab \
--gateway-url=http://127.0.0.1:9999 \
--ServerApp.session_manager_class=jupyter_server_synchronizer.SynchronizerSessionManager
--SessionManager.database_filepath=jupyter-database.db \
--SynchronizerSessionManager.autosync=True \
--SynchronizerSessionManager.log_level=DEBUG
```