- Docs »
- Running a notebook server
- Edit on GitHub
The Jupyter notebook web application is based on aserver-client structure. The notebook server uses a two-process kernelarchitecture based on ZeroMQ, as well as Tornado forserving HTTP requests.
Note
By default, a notebook server runs locally at 127.0.0.1:8888and is accessible only from localhost. You may access thenotebook server from the browser using http://127.0.0.1:8888.
This document describes how you cansecure a notebook server and how torun it on a public interface.
Important
This is not the multi-user server you are looking for. This documentdescribes how you can run a public server with a single user. This shouldonly be done by someone who wants remote access to their personal machine.Even so, doing this requires a thorough understanding of the set-upslimitations and security implications. If you allow multiple users toaccess a notebook server as it is described in this document, theircommands may collide, clobber and overwrite each other.
If you want a multi-user server, the official solution is JupyterHub.To use JupyterHub, you need a Unix server (typically Linux) runningsomewhere that is accessible to your users on a network. This may run overthe public internet, but doing so introduces additionalsecurity concerns.
Securing a notebook server¶
You can protect your notebook server with a simple single password. As of notebook5.0 this can be done automatically. To set up a password manually you can configure theNotebookApp.password setting in jupyter_notebook_config.py.
Prerequisite: A notebook configuration file¶
Check to see if you have a notebook configuration file,jupyter_notebook_config.py. The default location for this fileis 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 containa notebook configuration file, run the following command:
$ jupyter notebook --generate-config
This command will create the Jupyter folder if necessary, and create notebookconfiguration 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 servershould 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 asyour _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 ofthe login token, otherwise follow the procedure to set a password from thecommand line.
The ability to change the password at first login time may be disabled byintegrations by setting the --NotebookApp.allow_password_change=False
Starting at notebook version 5.0, you can enter and store a password for yournotebook server with a single command. jupyter notebook password willprompt you for your password and record the hashed password in yourjupyter_notebook_config.json.
$ jupyter notebook passwordEnter 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 credentialshave been leaked and desire to change your password. Changing your password willinvalidate all logged-in sessions after a server restart.
Preparing a hashed password¶
You can prepare a hashed password manually, using the functionnotebook.auth.security.passwd():
In [1]: from notebook.auth import passwdIn [2]: passwd()Enter password:Verify password:Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
Caution
passwd() when called with no argumentswill prompt you to enter and verify your password such asin the above code snippet. Although the function can alsobe passed a string as an argument such as passwd('mypassword'), pleasedo not pass a string as an argument inside an IPython session, as itwill be saved in your input history.
Adding hashed password to your notebook configuration file¶
You can then add the hashed password to yourjupyter_notebook_config.py. The default location for this filejupyter_notebook_config.py is in your Jupyter folder in your homedirectory, ~/.jupyter, e.g.:
c.NotebookApp.password = u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
Automatic password setup will store the hash in jupyter_notebook_config.jsonwhile this method stores the hash in jupyter_notebook_config.py. The .jsonconfiguration options take precedence over the .py one, thus the manualpassword 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 webcertificate, so that your hashed password is not sent unencrypted by yourbrowser.
Important
Web security is rapidly changing and evolving. We provide this documentas a convenience to the user, and recommend that the user keep current onchanges that may impact security, such as new releases of OpenSSL.The Open Web Application Security Project (OWASP) website is a good resourceon general security issues and web practices.
You can start the notebook to communicate via a secure protocol mode by settingthe certfile option to your self-signed certificate, i.e. mycert.pem,with the command:
$ jupyter notebook --certfile=mycert.pem --keyfile mykey.key
Tip
A self-signed certificate can be generated with openssl. For example,the following command will create a certificate valid for 365 days withboth the key and certificate data written to the same file:
$ 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-signedcertificate is insecure or unrecognized. If you wish to have a fullycompliant self-signed certificate that will not raise warnings, it is possible(but rather involved) to create one, as explained in detail in thistutorial. Alternatively, you may use Let’s Encrypt to acquire a free SSLcertificate and follow the steps in Using Let’s Encrypt to set up apublic server.
Running a public notebook server¶
If you want to access your notebook server remotely via a web browser,you can do so by running a public notebook server. For optimal securitywhen running a public notebook server, you should first secure theserver with a password and SSL/HTTPS as described inSecuring a notebook server.
Start by creating a certificate file and a hashed password, as explained inSecuring a notebook server.
If you don’t already have one, create aconfig file for the notebook using the following command line:
$ jupyter notebook --generate-config
In the ~/.jupyter directory, edit the notebook config file,jupyter_notebook_config.py. By default, the notebook config file hasall fields commented out. The minimum set of configuration options thatyou should uncomment and edit in jupyter_notebook_config.py is thefollowing:
# Set options for certfile, ip, password, and toggle off# browser auto-openingc.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'c.NotebookApp.keyfile = u'/absolute/path/to/your/certificate/mykey.key'# 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.
Using Let’s Encrypt¶
Let’s Encrypt provides free SSL/TLS certificates. You can also set up apublic server using a Let’s Encrypt certificate.
Running a public notebook server will be similar when using a Let’s Encryptcertificate with a few configuration changes. Here are the steps:
Create a Let’s Encrypt certificate.
Use Preparing a hashed password to create one.
If you don’t already have config file for the notebook, create oneusing 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 hasall fields commented out. The minimum set of configuration options thatyou should to uncomment and edit in jupyter_notebook_config.py is thefollowing:
# 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.
Important
Use ‘https’.Keep in mind that when you enable SSL support, you must access thenotebook server over https://, not over plain http://. The startupmessage from the server prints a reminder in the console, but it is easyto overlook this detail and think the server is for some reasonnon-responsive.
When using SSL, always access the notebook server with ‘https://’.
You may now access the public server by pointing your browser tohttps://your.host.com:9999 where your.host.com is your public server’sdomain.
Firewall Setup¶
To function correctly, the firewall on the computer running the jupyternotebook server must be configured to allow connections from clientmachines on the access port c.NotebookApp.port set injupyter_notebook_config.py to allow connections to theweb interface. The firewall must also allow connections from127.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 requiremultiple connections per kernel, so a large range of ports must be accessible.
Running the notebook with a customized URL prefix¶
The notebook dashboard, which is the landing page with an overviewof the notebooks in your working directory, is typically found and accessedat the default URL http://localhost:8888/.
If you prefer to customize the URL prefix for the notebook dashboard, you cando so through modifying jupyter_notebook_config.py. For example, if youprefer that the notebook dashboard be located with a sub-directory thatcontains other ipython files, e.g. http://localhost:8888/ipython/,you can do so with configuration options like the following (see above forinstructions about modifying jupyter_notebook_config.py):
c.NotebookApp.base_url = '/ipython/'
Embedding the notebook in another website¶
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 theContent-Security-Policy to allow embedding. Assuming your website is athttps://mywebsite.example.com, you can embed the notebook on your websitewith the following configuration setting injupyter_notebook_config.py:
c.NotebookApp.tornado_settings = { 'headers': { 'Content-Security-Policy': "frame-ancestors https://mywebsite.example.com 'self' " }}
When embedding the notebook in a website using an iframe,consider putting the notebook in single-tab mode.Since the notebook opens some links in new tabs by default,single-tab mode keeps the notebook from opening additional tabs.Adding the following to ~/.jupyter/custom/custom.js will enablesingle-tab mode:
define(['base/js/namespace'], function(Jupyter){ Jupyter._target = '_self';});
Known issues¶
Proxies¶
When behind a proxy, especially if your system or browser is set to autodetectthe proxy, the notebook web application might fail to connect to the server’swebsockets, and present you with a warning at startup. In this case, you needto 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 serverto the ‘No proxy for’ field.
Docker CMD¶
Using jupyter notebook as aDocker CMD results inkernels repeatedly crashing, likely due to a lack of PID reaping.To avoid this, use the tini init as yourDockerfile ENTRYPOINT:
# Add Tini. Tini operates as a process subreaper for jupyter. This prevents# kernel crashes.ENV TINI_VERSION v0.6.0ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /usr/bin/tiniRUN chmod +x /usr/bin/tiniENTRYPOINT ["/usr/bin/tini", "--"]EXPOSE 8888CMD ["jupyter", "notebook", "--port=8888", "--no-browser", "--ip=0.0.0.0"]