Prerequisite: A notebook configuration file

Check to see if you have a notebook configuration file,  jupyter_notebook_config.py . The default location for this file is your Jupyter folder located in your home directory:

• Windows:  C:\Users\USERNAME\.jupyter\jupyter_notebook_config.py
• OS X:  /Users/USERNAME/.jupyter/jupyter_notebook_config.py
• Linux:  /home/USERNAME/.jupyter/jupyter_notebook_config.py

If you don’t already have a Jupyter folder, or if your Jupyter folder doesn’t contain a notebook configuration file, run the following command:

$ jupyter notebook --generate-config

This command will create the Jupyter folder if necessary, and create notebook configuration file,  jupyter_notebook_config.py , in this folder.

Automatic Password setup

As of notebook 5.3, the first time you log-in using a token, the notebook server should give you the opportunity to setup a password from the user interface.

You will be presented with a form asking for the current _token_, as well as your _new_ _password_ ; enter both and click on  Login   and   setup   new   password .

Next time you need to log in you’ll be able to use the new password instead of the login token, otherwise follow the procedure to set a password from the command line.

The ability to change the password at first login time may be disabled by integrations by setting the  --NotebookApp.allow_password_change=False

Starting at notebook version 5.0, you can enter and store a password for your notebook server with a single command.  jupyter notebook password  will prompt you for your password and record the hashed password in your  jupyter_notebook_config.json .

$ jupyter notebook password
Enter password:  ****
Verify password: ****[NotebookPasswordApp] Wrote hashed password to /Users/you/.jupyter/jupyter_notebook_config.json

This can be used to reset a lost password; or if you believe your credentials have been leaked and desire to change your password. Changing your password will invalidate all logged-in sessions after a server restart.

Preparing a hashed password

You can prepare a hashed password manually, using the function  notebook.auth.security.passwd() :

In [1]: from notebook.auth import passwdIn [2]: passwd()Enter password:Verify password:Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'

Adding hashed password to your notebook configuration file

You can then add the hashed password to your  jupyter_notebook_config.py . The default location for this file  jupyter_notebook_config.py  is in your Jupyter folder in your home directory,  ~/.jupyter , e.g.:

c.NotebookApp.password = u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'

Automatic password setup will store the hash in  jupyter_notebook_config.json  while this method stores the hash in  jupyter_notebook_config.py . The  .json  configuration options take precedence over the  .py  one, thus the manual password may not take effect if the Json file has a password set.

Using SSL for encrypted communication

When using a password, it is a good idea to also use SSL with a web certificate, so that your hashed password is not sent unencrypted by your browser.

You can start the notebook to communicate via a secure protocol mode by setting the  certfile option to your self-signed certificate, i.e.  mycert.pem , with the command:

$ jupyter notebook --certfile=mycert.pem --keyfile mykey.key

$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out mycert.pem

When starting the notebook server, your browser may warn that your self-signed certificate is insecure or unrecognized. If you wish to have a fully compliant self-signed certificate that will not raise warnings, it is possible (but rather involved) to create one, as explained in detail in this  tutorial . Alternatively, you may use  Let’s Encrypt  to acquire a free SSL certificate and follow the steps in  Using Let’s Encrypt  to set up a public server.

Using Let’s Encrypt

Let’s Encrypt  provides free SSL/TLS certificates. You can also set up a public server using a  Let’s Encrypt  certificate.

Running a public notebook server  will be similar when using a Let’s Encrypt certificate with a few configuration changes. Here are the steps:

1. Create a  Let’s Encrypt certificate .

2. Use  Preparing a hashed password  to create one.

3. If you don’t already have config file for the notebook, create one using the following command:

   $ jupyter notebook --generate-config
   

4. In the  ~/.jupyter  directory, edit the notebook config file,  jupyter_notebook_config.py . By default, the notebook config file has all fields commented out. The minimum set of configuration options that you should to uncomment and edit in  jupyter_notebook_config.py  is the following:

# Set options for certfile, ip, password, and toggle off# browser auto-openingc.NotebookApp.certfile = u'/absolute/path/to/your/certificate/fullchain.pem'c.NotebookApp.keyfile = u'/absolute/path/to/your/certificate/privkey.pem'# Set ip to '*' to bind on all interfaces (ips) for the public serverc.NotebookApp.ip = '*'c.NotebookApp.password = u'sha1:bcd259ccf...<your hashed password here>'c.NotebookApp.open_browser = False# It is a good idea to set a known, fixed port for server accessc.NotebookApp.port = 9999

You can then start the notebook using the  jupyter   notebook  command.

You may now access the public server by pointing your browser to  https://your.host.com:9999 where  your.host.com  is your public server’s domain.

Firewall Setup

To function correctly, the firewall on the computer running the jupyter notebook server must be configured to allow connections from client machines on the access port  c.NotebookApp.port  set in jupyter_notebook_config.py  to allow connections to the web interface. The firewall must also allow connections from 127.0.0.1 (localhost) on ports from 49152 to 65535. These ports are used by the server to communicate with the notebook kernels. The kernel communication ports are chosen randomly by ZeroMQ, and may require multiple connections per kernel, so a large range of ports must be accessible.

Proxies

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.

Content-Security-Policy (CSP)

Certain  security guidelines  recommend that servers use a Content-Security-Policy (CSP) header to prevent cross-site scripting vulnerabilities, specifically limiting to  default-src:   https:  when possible. This directive causes two problems with Jupyter. First, it disables execution of inline javascript code, which is used extensively by Jupyter. Second, it limits communication to the https scheme, and prevents WebSockets from working because they communicate via the wss scheme (or ws for insecure communication). Jupyter uses WebSockets for interacting with kernels, so when you visit a server with such a CSP, your browser will block attempts to use wss, which will cause you to see “Connection failed” messages from jupyter notebooks, or simply no response from jupyter terminals. By looking in your browser’s javascript console, you can see any error messages that will explain what is failing.

To avoid these problem, you need to add  'unsafe-inline'  and  connect-src   https:   wss:  to your CSP header, at least for pages served by jupyter. (That is, you can leave your CSP unchanged for other parts of your website.) Note that multiple CSP headers are allowed, but successive CSP headers can only restrict the policy; they cannot loosen it. For example, if your server sends both of these headers

Content-Security-Policy “default-src https: ‘unsafe-inline’” Content-Security-Policy “connect-src https: wss:”

the first policy will already eliminate wss connections, so the second has no effect. Therefore, you can’t simply add the second header; you have to actually modify your CSP header to look more like this:

Content-Security-Policy “default-src https: ‘unsafe-inline’; connect-src https: wss:”

Docker CMD

Using  jupyter   notebook  as a  Docker CMD  results in kernels repeatedly crashing, likely due to a lack of  PID reaping . To avoid this, use the  tini   init  as your Dockerfile  ENTRYPOINT :

# Add Tini. Tini operates as a process subreaper for jupyter. This prevents
# kernel crashes.
ENV TINI_VERSION v0.6.0
ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /usr/bin/tini
RUN chmod +x /usr/bin/tini
ENTRYPOINT ["/usr/bin/tini", "--"]
EXPOSE 8888
CMD ["jupyter", "notebook", "--port=8888", "--no-browser", "--ip=0.0.0.0"]