Running the Notebook Server.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Running the Notebook Server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Jupyter notebook server runs Notebooks on the web."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Starting a notebook server using the command line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can start the notebook server from the command line (Terminal on Mac/Linux, CMD prompt on Windows) by running the following command: \n",
    "\n",
    "    jupyter notebook\n",
    "\n",
    "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.\n",
    "\n",
    "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.\n",
    "\n",
    "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.\n",
    "\n",
    "You can also specify the port manually:\n",
    "\n",
    "    jupyter notebook --port 8883\n",
    "\n",
    "Or start notebook server without opening a web browser.\n",
    "\n",
    "    jupyter notebook --no-browser\n",
    "\n",
    "The notebook server has a number of other command line arguments that can be displayed with the `--help` flag: \n",
    "\n",
    "    jupyter notebook --help\n",
    "\n",
    "<div class=\"alert alert-failure\">\n",
    " \n",
    "</div>\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuring the IPython Notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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 `ipython_notebook_config.py` in your IPython *profile directory*. The profile directory is a subfolder of your IPython directory, which itself is usually `.ipython` in your home directory.\n",
    "\n",
    "You can display the location of your default profile directory by running the command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/Users/bgranger/.ipython/profile_default\r\n"
     ]
    }
   ],
   "source": [
    "!jupyter --paths"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To start the notebook server using a given profile, run the following:\n",
    "\n",
    "    jupyter notebook --profile=my_profile"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More details about Jupyter configuration files and profiles can be found [here](https://jupyter-notebook.readthedocs.io/en/stable/config.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running a public notebook server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-error\">\n",
    "Don't run a public notebook server unless you know what you are doing.\n",
    "</div>\n",
    "\n",
    "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.\n",
    "\n",
    "This can be accomplished by passing a command line options.\n",
    "\n",
    "    jupyter notebook --ip=* --no-browser\n",
    "\n",
    "You can also add the following to your`ipython_notebook_config.py` file:\n",
    "\n",
    "```python\n",
    "c.NotebookApp.ip = '*'\n",
    "c.NotebookApp.open_browser = False\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running with a different URL prefix"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The notebook dashboard typically lives at the URL `http://localhost:8888/tree`. If you prefer that it lives, together with the \n",
    "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.\n",
    "\n",
    "```python\n",
    "c.NotebookApp.base_url = '/ipython/'\n",
    "c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Known issues"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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.\n",
    "\n",
    "For example, in Firefox, go to the Preferences panel, Advanced section,\n",
    "Network tab, click 'Settings...', and add the address of the notebook server\n",
    "to the 'No proxy for' field."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using a different notebook store"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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\n",
    "`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. \n",
    "\n",
    "The [bookstore](https://github.com/rgbkrk/bookstore) package currently allows users to store notebooks on Rackspace CloudFiles or OpenStack Swift based object stores.\n",
    "\n",
    "Writing a notebook manager is as simple as extending the base class `NotebookManager`. The [simple_notebook_manager](https://github.com/khinsen/simple_notebook_manager) provides a great example\n",
    "of an in memory notebook manager, created solely for the purpose of\n",
    "illustrating the notebook manager API."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Multi-User Notebook Servers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## JupyterHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user IPython/Jupyter Notebook server. (see also Bindr project)\n",
    "\n",
    "<img src=\"https://c2a32ff18d23c8f567f0-e44b0df73868b5d567b1e58e01681d15.ssl.cf5.rackcdn.com/2015-03-24-deploying-jupyterhub-for-education/jupyterhub-9efc59baf33d2640641cb4a1fd9145ff.gif\" width=\"800px\" />\n",
    "\n",
    "### Components\n",
    "\n",
    "* multi-user Hub (tornado process)\n",
    "* configurable http proxy (node-http-proxy)\n",
    "* multiple single-user IPython notebook servers (Python/IPython/tornado)\n",
    "\n",
    "#### [Configurable Proxy](https://github.com/jupyter/configurable-http-proxy)\n",
    "\n",
    "* Based on node-http-proxy\n",
    "* Proxy routes to localhost, external IPs, etc.\n",
    "\n",
    "```\n",
    "/user/123/ -> 127.0.0.1:56790\n",
    "```\n",
    "\n",
    "* Provides an administrative API for adding routes\n",
    "\n",
    "```\n",
    "POST /api/routes/[:path]\n",
    "```\n",
    "\n",
    "#### [JupyterHub](https://github.com/jupyter/jupyterhub)\n",
    "\n",
    "* Hub spawns proxy\n",
    "* Proxy forwards ~all requests to hub by default\n",
    "* Hub handles login, and spawns single-user servers on demand\n",
    "* Hub configures proxy to forward url prefixes to single-user servers\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Authentication models\n",
    "\n",
    "* PAM/Unix (Default)\n",
    "* [GitHub OAuth](https://github.com/jupyter/oauthenticator) - Demo at demohub.jupyter.org\n",
    "\n",
    "This is extensible enough to implement other authentication methods, the simplest being any involving OAuth (follow the GitHub OAuthenticator for a skeleton)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Spawners\n",
    "\n",
    "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](https://github.com/jupyter/dockerspawner) which runs each user in their own environment inside a Docker container.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Real world implementations of JupyterHub\n",
    "\n",
    "The Computational Models class at UC Berkeley ran a JupyterHub installation for ~220 students in Winter/Spring of 2015.\n",
    "\n",
    "* Docker Spawner\n",
    "* Multiple compute nodes\n",
    "* GitHub Authentication\n",
    "* NFS backed for student data, assignments, notebooks, etc.\n",
    "\n",
    "![](https://c2a32ff18d23c8f567f0-e44b0df73868b5d567b1e58e01681d15.ssl.cf5.rackcdn.com/2015-03-24-deploying-jupyterhub-for-education/setup-2e74d935ee0c874e66a9b53359493ceb.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## tmpnb\n",
    "\n",
    "tmpnb is a temporary notebook system. Visit [try.jupyter.org](https://try.jupyter.org) for a demo.\n",
    "\n",
    "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.\n",
    "\n",
    "<img src=\"https://cloud.githubusercontent.com/assets/836375/5911140/c53e3978-a587-11e4-86a5-695469ef23a5.png\" width=\"800px\" />\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3.0
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}