Running a Jupyter Server

References

• Jupyter Server Documentation
• • Jupyter Server Github Repo, the source code we describe in this code.
  • Jupyter Notebook Github Repo , the source code for the classic Notebook.
  • JupyterLab Github Repo, the JupyterLab server which runs on the Jupyter Server.

Related

• Decoupled Two-Process Model
• • IPython has abstracted and extended the notion of a traditional Read-Evaluate-Print Loop (REPL) environment by decoupling the evaluation into its own process. We call this process a kernel: it receives execution instructions from clients and communicates the results back to them. The decoupling allows us to have several clients connected to the same kernel, and even allows clients and kernels to live on different machines.
• ZeroMQ
• • ZeroMQ looks like an embeddable networking library but acts like a concurrency framework. It gives you sockets that carry atomic messages across various transports like in-process, TCP, and multicast. You can connect sockets N-to-N with patterns like fan-out, pub-sub, task distribution, and request reply. It's fast enough to be the favric for clustered products. Its asynchronous I/O model gives you scalable multicore applications, built as asynchronous message-processing tasks.
• Tornado
• • Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed. By using non-blocking networking I/O, Tornado can scale to tens of thousands of open connections, making it ideal for long polling, WebSockets, and other application that require a long-lived connection to each user.

Notes

Jupyter Server is the backend that provides the core services, APIs, and REST endpoints for Jupyter web applications. Jupyter Server extensions can use the framework and services provided by Jupyter Server to create applications and services. Examples of Jupyter Server extensions include:

• Jupyter Lab
• • JupyterLab computational environment
• Jupyter Resource Usage
• • Jupyter Notebook Extension for monitoring your own resource usage
• Jupyter Scheduler
• • Run Jupyter notebooks as jobs
• jupyter-collaboration
• • A Jupyter Server Extension Providing Support for Y Documents
• NbClassic
• • Jupyter notebook as a Jupyter Server extension
• Clyc UI Server
• • A Jupyter Server extension that serves the cylc-ui web application for monitoring and controlling Cylc workflows

Users

The Jupyter Server is a highly technical piece of the Jupyter Stack, so users probably won't import or install this library directly. These pages are meant to help you in case you run into issues or bugs.

Most Jupyter users will never need to install Jupyter Server manually. Jupyter Web applications will include the (correct version) of Jupyter Server as a dependency. It's best to let those applications handle installation, because they may require a specific version of Jupyter Server.

To install manually, run:

$ pip install jupyter_server[==<version>]

By default, Jupyter Server looks for server-specific configuration in a jupyter_server_config file located on a Jupyter path. To list the paths where Jupyter server will look, run:

$ jupyter --paths

config:
    /Users/username/.jupyter
    /usr/local/etc/jupyter
    /etc/jupyter
data:
    /Users/username/Library/Jupyter
    /usr/local/share/jupyter
    /usr/share/jupyter
runtime:
    /Users/username/Library/Jupyter/runtime

The paths under config are listed in order of precedence. If the same trait is listed in multiple places, it will set to the value from the file with the highest precedence. Jupyter Server uses IPython's traitlets system for configuration. Traits can be listed in a Python or JSON config file. You can quickly create a jupyter_server_config.py file in the .jupyter directory, with all the defaults commented out, using the following command: jupyter server --generate-config. In Python files, these traits will have the prefix c.ServerApp. Alternatively, you can configure Jupyter Server when launching the command line using CLI arguments. Prefix each argument with --ServerApp like so: jupyter server --ServerApp.port=9999. A full list of configuration options can be seen here.

Most of the time, you won't need to start the Jupyter Server directly. Jupyter Web Applications (like Jupyter Notebook, Jupyterlab, Voila, etc. ) come with their own entry points that start a server automatically. Sometimes it can be useful to start a Jupyter Server directly when you want to run multiple Jupyter Web applications at the same time. For more details, see the Managing multiple extensions page. If these extensions are enabled, simply run the following:

$ jupyter server

Operators

These pages are targeted at people using, configuring, and/or deploying multiple Jupyter Web Application with Jupyter Server.

One of the major benefits of Jupyter Server is that you can run serve multiple Jupyter frontend applications above the same Tornado web server. That's because every Jupyter frontend application is now a server extension. When you run a Jupyter Server with multiple extensions enabled, each extension appends its own set of handlers and static assets to the server.

When you install a Jupyter Server extension, it should automatically add itself to your list of enabled extensions. You can see a list of installed extensions by calling:

> jupyter server extension list

config dir: /Users/username/etc/jupyter
    myextension enabled
    - Validating myextension...
      myextension  OK

You can enable/disable extension using the following:

> jupyter server extension enable myextension

Enabling: myextension
    - Validating myextension...
      myextension  OK
    - Extension successfully enabled.


> jupyter server extension disable myextension

Disabling: jupyter_home
    - Validating jupyter_home...
      jupyter_home  OK
    - Extension successfully disabled.

Extensions that are also jupyter applications can be launched from a CLI endpoint. Launch Jupyter Notebook using:

> jupyter notebook 

Jupyter Server will automatically start a server and the browser will be routed to Jupyter Notebook's default URL. Other enabled extension will be available to the user. The entry point simply offers a more direct launching mechanism. If multiple extensions are enabled, a Jupyter Server can be launched directly: jupyter server. Extensions can also be enabled manually from the Jupyter Server entry point using the jpserver_extensions trait.

Some Jupyter Server extensions are also configurable applications. There are two ways to configure such extensions:

1. Pass arguments to the extension's entry point
2. List configurable options in a Jupyter config file

Use the jupyter --paths command to see where Jupyter Server looks for extension config files. Config files can either be Python or JSON files and are named like jupyter_{extension-name}_config. Server extension applications can also be configured from the command line.

The Jupyter Server uses a two-process kernel architecture based on ZeroMQ, as well as Tornado for serving HTTP requests. You can protect your Jupyter server with a simple single password. This can be done automatically now, or you can set it manually in the configuration file. If you want to access your notebook server remotely via a web browser, you can do so by running a public notebook server.

Sometimes you may want to embed the notebook somewhere on your website, e.g. in an IFrame. To do this, you may need to override the Content-Security-Policy to allow embedding. Assuming your website is at https://mywebsite.example.com, you can embed the notebook on your website with the following configuration setting in jupyter_server_config.py:

c.ServerApp.tornado_settings = {
    "headers": {
        "Content-Security-Policy": "frame-ancestors https://mywebsite.example.com 'self' "
    }
}

Jupyter Server (and Jupyter Server extension applications such as Jupyter Lab) are Traitlets applications. By default Traitlets applications log to stderr. You can configure them to log to other locations e.g. log files.

Developers

The Jupyter Server system can be seen in the figure below.

Jupyter Server contains the following components:

• ServerApp is the main Tornado-based application which connects all components together.
• Config Manager initializes configuration for the ServerApp. You can define custom classes for the Jupyter Server managers using this config and change ServerApp settings.
• Custom Extensions allow you to create the custom Server's REST API endpoints.
• Gateway Server is a web server that, when configured, provides access to Jupyter Kernels running on other hosts. There are different ways to create a gateway server. If your ServerApp needs to communicate with remote kernels residing within resource-managed clusters, you can use Enterprise Gateway, otherwise, you can use Kernel Gateway, where kernels run locally to the gateway server
• Contents Manager and File Contents Manager are responsible for serving Notebook on the file system. Session Manager uses Contents Manager to receive kernel path.
• Session Manager processes users' Sessions. When a user starts a new kernel, Session Manager starts a process to provision kernel for the user and generates a new Session ID. Each opened Notebook has a separate Session, but different Notebook kernels can use the same Session. Session Manager uses SQLite3 database to store the Session information. The database is stored in memory by default, but can be configured to save to disk.
• Mapping Kernel Manager is responsible for managing the lifecycles of the kernels running withing the ServerApp. It starts a new kernel for a user's Session and facilitates interrupt, restart, and shutdown operations against the kernel
• Jupyter Client library is used by Jupyter Server to work with the notebook kernels.
• • Kernel Manager manages a single kernel for the Notebook.
  • Kernel Spec Manager parses files with JSON specification for a kernels, and provides a list of available kernel configurations.

The create Session workflow can be seen in the figure below.

When a user starts a new kernel, the following steps occur:

1. The Notebook clients sends the POST /api/sessions request to the Jupyter Server. This request has all necessary data, such as Notebook name, type, path, and kernel name.
2. Session Manager asks Contents Manager for the kernel file system path based on the input data.
3. Session Manager sends kernel path to Mapping Kernel Manager
4. Mapping Kernel Manager starts the kernel create process by using Multi Kernel Manager and Kernel Manager.
5. Kernel Manager uses the provisioner layer to launch a new kernel
6. Kernel Provisioner is responsible for launching kernels based on the kernel specification.
7. Kernel Spec Manager gets the kernel specification form the JSON file. The specification is located in kernel.json file.
8. Once Kernel Provisioner launches the kernel, Kernel Manager generates the new kernel ID for Session Manager
9. Session Manager saves the new Session data to the SQLite3 database
10. Notebook client receives the created session data.

The delete session workflow can be seen below.

Other

Helpful Links

• Frequently Asked Questions
• Jupyter Server Github Repo
• JupyterLab Github Repo
• Jupyter Notebook Github Repo
• Jupyterhub Github Repo
• Jupyter Zoom Channel

The Jupyter Server can be run with a variety of command line arguments. A list of available options can be found below in the options section.