Running the Notebook Server¶

The IPython notebook server is a custom web server that runs the notebook web application. Most of the time, users run the notebook server on their local computer using IPython's command line interface.

Starting the notebook server using the command line¶

You can start the notebook server from the command line (Terminal on Mac/Linux, CMD prompt on Windows) by running the following command:

jupyter notebook

This will print some information about the notebook server in your terminal, including the URL of the web application (by default, http://127.0.0.1:8888). It will then open your default web browser to this URL.

When the notebook opens, you will see the notebook dashboard, which will show a list of the notebooks and subdirectories in the directory where the notebook server was started. As of IPython 2.0, the dashboard allows you to navigate to different subdirectories. Because of this, it is no longer necessary to start a separate notebook server for each subdirectory. Most of the time, you will want to start a notebook server in the highest directory in your filesystem where notebooks can be found. Often this will be your home directory.

You can start more than one notebook server at the same time. By default, the first notebook server starts on port 8888 and later notebook servers search for open ports near that one.

You can also specify the port manually:

jupyter notebook --port 9999

Or start notebook server without opening a web browser.

jupyer notebook --no-browser

The notebook server has a number of other command line arguments that can be displayed with the --help flag:

jupyer notebook --help

We strongly recommend you run the notebook over https with a password, even on localhost and if you are the only user of the current machine as otherwise any other program on your machine could send commands to be run to your notebook server.

Configuring the Jupyter Notebook¶

The notebook web server can also be configured using IPython profiles and configuration files. The Notebook web server configuration options are set in a file named jupyter_notebook_config.py|json in your Jupyter config directory which is usually .jupyter in your home directory.

You can display the location of your default profile directory by running the command:

IPython configuration¶

The notebook server configuration and the IPtyhon kernels configuration are separate. IPython has the noteion of profiles, and configuration files are often found in ~/.ipython.

More details about IPython configuration files and profiles can be found here.

Securing the notebook server¶

The IPython Notebook allows arbitrary code execution on the computer running it. Thus, the notebook web server should never be run on the open internet without first securing it. By default, the notebook server only listens on local network interface (127.0.0.1) There are two steps required to secure the notebook server:

1. Setting a password
2. Encrypt network traffic using SSL

Setting a password¶

You can protect your notebook server with a simple single password by setting the NotebookApp.password configurable. You can prepare a hashed password using the function IPython.lib.passwd:

You can then add this to your ipython_notebook_config.py:

# Password to use for web authentication
c = get_config()
c.NotebookApp.password = 
u'sha1:6c2164fc2b22:ed55ecf07fc0f985ab46561483c0e888e8964ae6'

Using SSL/HTTPS¶

When using a password, it is a good idea to also use SSL, so that your password is not sent unencrypted by your browser to the web server. When running the notebook on the public internet this is absolutely required.

The first step is to generate an SSL certificate. A self-signed certificate can be generated with openssl. For example, the following command will create a certificate valid for 365 days with both the key and certificate data written to the same file:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem

In most cases, you should run this command in your profile directory, which will make it easy to use the generated key and certificate.

When you connect to a notebook server over HTTPS using a self-signed certificate, your browser will warn you of a dangerous certificate because it is self-signed. If you want to have a fully compliant certificate that will not raise warnings, it is possible (but rather involved) to obtain one, as explained in detail in this tutorial
When you enable SSL support, you will need to access the notebook server over https://, rather than plain http://. The startup message from the notebook server prints the correct URL, but it is easy to overlook and think the server is for some reason non-responsive.

Once you have generated the key and certificate, you can configure the notebook server to use them, by adding the following to ipython_notebook_config.py:

# The full path to an SSL/TLS certificate file.
c.NotebookApp.certfile = u'/Users/bgranger/.ipython/profile_my_profile/mycert.crt'

# The full path to a private key file for usage with SSL/TLS.
c.NotebookApp.keyfile = u'/Users/bgranger/.ipython/profile_my_profile/mycert.key'

Running a public notebook server¶

By default the notebook server only listens on the localhost/127.0.0.1 network interface. If you want to connect to the notebook from another computers, or over the internet, you need to configure the notebook server to listen on all network interfaces and not open the browser. You will often also want to disable the automatic launching of the web browser.

This can be accomplished by passing a command line options.

ipython notebook --ip=* --no-browser

You can also add the following to youripython_notebook_config.py file:

c.NotebookApp.ip = '*'
c.NotebookApp.open_browser = False

Running with a different URL prefix¶

The notebook dashboard typically lives at the URL http://localhost:8888/tree. If you prefer that it lives, together with the rest of the notebook web application, under a base URL prefix, such as http://localhost:8888/ipython/tree, you can do so by adding the following lines to your ipython_notebook_config.py file.

c.NotebookApp.base_url = '/ipython/'
c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}

Known issues¶

When behind a proxy, especially if your system or browser is set to autodetect the proxy, the notebook web application might fail to connect to the server's websockets, and present you with a warning at startup. In this case, you need to configure your system not to use the proxy for the server's address.

For example, in Firefox, go to the Preferences panel, Advanced section, Network tab, click 'Settings...', and add the address of the notebook server to the 'No proxy for' field.

Using a different notebook store¶

By default, the notebook server stores the notebook documents that it saves as files in the working directory of the notebook server, also known as the notebook_dir. This logic is implemented in the FileNotebookManager class. However, the server can be configured to use a different notebook manager class, which can store the notebooks in a different format.

The bookstore package currently allows users to store notebooks on Rackspace CloudFiles or OpenStack Swift based object stores.

Writing a notebook manager is as simple as extending the base class NotebookManager. The simple_notebook_manager provides a great example of an in memory notebook manager, created solely for the purpose of illustrating the notebook manager API.

Multi-User Notebook Servers¶

JupyterHub¶

JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user IPython/Jupyter Notebook server.

Components¶

• multi-user Hub (tornado process)
• configurable http proxy (node-http-proxy)
• multiple single-user IPython notebook servers (Python/IPython/tornado)

Configurable Proxy¶

• Based on node-http-proxy
• Proxy routes to localhost, external IPs, etc.

/user/123/ -> 127.0.0.1:56790

• Provides an administrative API for adding routes

POST /api/routes/[:path]

JupyterHub¶

• Hub spawns proxy
• Proxy forwards ~all requests to hub by default
• Hub handles login, and spawns single-user servers on demand
• Hub configures proxy to forward url prefixes to single-user servers

Authentication models¶

• PAM/Unix (Default)
• GitHub OAuth - Demo at demohub.jupyter.org

This is extensible enough to implement other authentication methods, the simplest being any involving OAuth (follow the GitHub OAuthenticator for a skeleton).

Spawners¶

By default, notebook servers are spawned in the context of the user as a process on the host machine. One alternative for spawning is the DockerSpawner which runs each user in their own environment inside a Docker container.

Real world implementations of JupyterHub¶

The Computational Models class at UC Berkeley ran a JupyterHub installation for ~220 students in Winter/Spring of 2015.

• Docker Spawner
• Multiple compute nodes
• GitHub Authentication
• NFS backed for student data, assignments, notebooks, etc.

tmpnb¶

tmpnb is a temporary notebook system. Visit try.jupyter.org for a demo.

Similar to JupyterHub with the DockerSpawner, tmpnb uses a proxy to route to notebook servers. The difference is that there is no login and notebook servers get deleted after a period of (configurable) inactivity.