diff --git a/docs/source/public_server.rst b/docs/source/public_server.rst index df51307bb..d79a3cd4d 100644 --- a/docs/source/public_server.rst +++ b/docs/source/public_server.rst @@ -32,6 +32,18 @@ You can protect your notebook server with a simple single password by configuring the :attr:`NotebookApp.password` setting in :file:`jupyter_notebook_config.py`. +Prerequisite: A notebook configuration file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Check to see if you have a notebook configuration file, +:file:`jupyter_notebook_config.py`. The default location for this file +is your Jupyter folder in your home directory, ``~/.jupyter``. + +If you don't already have one, create a config file for the notebook +using the following command:: + + $ jupyter notebook --generate-config + + Preparing a hashed password ~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can prepare a hashed password using the function @@ -57,9 +69,8 @@ You can prepare a hashed password using the function Adding hashed password to your notebook configuration file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can then add the hashed password to your :file:`jupyter_notebook_config.py`. -The default location for this file ``jupyter_notebook_config.py`` in your Jupyter -folder in your home directory, ``~/.jupyter``. -e.g.:: +The default location for this file :file:`jupyter_notebook_config.py` is in +your Jupyter folder in your home directory, ``~/.jupyter``, e.g.:: # Get notebook configuration and add hashed password c = get_config() @@ -116,53 +127,68 @@ Running a public notebook server -------------------------------- If you want to access your notebook server remotely via a web browser, -you can do the following. +you can do so by running a public notebook server. For optimal security +when running a public notebook server, you should first secure the +server with a password and SSL/HTTPS as described in +:ref:`notebook_server_security`. + +Start by creating a certificate file and a hashed password, as explained in +:ref:`notebook_server_security`. -Start by creating a certificate file and a hashed password, as explained -above. Then, if you don't already have one, create a config file for the -notebook using the following command line:: +If you don't already have one, create a +config 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 file has all fields -commented; the minimum set you need to uncomment and edit is the following:: +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 :file:``jupyter_notebook_config.py`` is the +following:: + # Notebook configuration for public notebook server c = get_config() - # Notebook config + # Set options for certfile, ip, password, and toggle off browser auto-opening c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem' - c.NotebookApp.ip = '*' + c.NotebookApp.ip = u'*' # where * is the desired ip address + c.NotebookApp.password = u'sha1:bcd259ccf...' c.NotebookApp.open_browser = False - c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]' - # It is a good idea to put it on a known, fixed port + + # It is a good idea to set a known, fixed port for server access c.NotebookApp.port = 9999 -You can then start the notebook and access it later by pointing your browser -to ``https://your.host.com:9999`` with ``jupyter notebook``. +You can then start the notebook and access it later by pointing your browser +to ``https://your.host.com:9999`` after starting the ``jupyter notebook`` +client. Firewall Setup ~~~~~~~~~~~~~~ -To function correctly, the firewall on the computer running the ipython server must be -configured to allow connections from client machines on the ``c.NotebookApp.port`` -port 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 +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 +:file:``jupyter_notebook_config.py`` port 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. -Running with a different URL prefix ------------------------------------ +Running the notebook with a customized URL prefix +------------------------------------------------- + +The notebook dashboard, which is the landing page with an overview +of the notebooks in your working directory, is typically found and accessed +at the default URL ``http://localhost:8888/``. -The notebook dashboard (the landing page with an overview -of the notebooks in your working directory) typically lives at the URL -``http://localhost:8888/``. If you prefer that it lives, together with the -rest of the notebook, under a sub-directory, -e.g. ``http://localhost:8888/ipython/``, you can do so with -configuration options like the following (see above for instructions about -modifying ``jupyter_notebook_config.py``):: +If you prefer to customize the URL prefix for the notebook dashboard, you can +do so through modifying ``jupyter_notebook_config.py``. For example, if you +prefer that the notebook dashboard be located with a sub-directory that +contains other ipython files, e.g. ``http://localhost:8888/ipython/``, +you can do so with configuration options like the following (see above for +instructions about modifying ``jupyter_notebook_config.py``):: c.NotebookApp.base_url = '/ipython/' c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}