##// END OF EJS Templates
Working on notebook docs.
Brian E. Granger -
Show More
@@ -1,9 +1,248 b''
1 {
1 {
2 "metadata": {
2 "metadata": {
3 "name": "",
3 "name": "",
4 "signature": "sha256:0abf067a20ebda26a671db997ac954770350d292dff7b7d6a4ace8808f70aca1"
4 "signature": "sha256:84fa8b285a29d021b31d7211c6452729fb042a5c74cee6bf31e74e06fdd26b97"
5 },
5 },
6 "nbformat": 3,
6 "nbformat": 3,
7 "nbformat_minor": 0,
7 "nbformat_minor": 0,
8 "worksheets": []
8 "worksheets": [
9 {
10 "cells": [
11 {
12 "cell_type": "heading",
13 "level": 1,
14 "metadata": {},
15 "source": [
16 "Running the Notebook Server"
17 ]
18 },
19 {
20 "cell_type": "markdown",
21 "metadata": {},
22 "source": [
23 "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."
24 ]
25 },
26 {
27 "cell_type": "heading",
28 "level": 2,
29 "metadata": {},
30 "source": [
31 "Starting the notebook server using the command line"
32 ]
33 },
34 {
35 "cell_type": "markdown",
36 "metadata": {},
37 "source": [
38 "You can start the notebook server from the command line (Terminal on Mac/Linux, CMD prompt on Windows) by running the following command: \n",
39 "\n",
40 " ipython notebook\n",
41 "\n",
42 "This will print some information about the notebook server in your console, 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",
43 "\n",
44 "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",
45 "\n",
46 "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",
47 "\n",
48 "You can also specify the port manually:\n",
49 "\n",
50 " ipython notebook --port 9999\n",
51 "\n",
52 "Or start notebook server without opening a web browser.\n",
53 "\n",
54 " ipython notebook --no-browser\n",
55 "\n",
56 "The notebook server has a number of other command line arguments that can be displayed with the `--help` flag: \n",
57 "\n",
58 " ipython notebook --help\n",
59 "\n",
60 "<div class=\"alert alert-failure\">\n",
61 "It used to be possible to specify kernel options, such as <code>--pylab inline</code> from the command line. This is deprecated in IPython 2.0 and will be removed in IPython 3.0. To enable matplotlib based plotting for the Python kernel use the <code>%matplotlib</code> magic command.\n",
62 "</div>\n",
63 "\n"
64 ]
65 },
66 {
67 "cell_type": "heading",
68 "level": 2,
69 "metadata": {},
70 "source": [
71 "Configuring the IPython Notebook"
72 ]
73 },
74 {
75 "cell_type": "markdown",
76 "metadata": {},
77 "source": [
78 "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",
79 "\n",
80 "You can display the location of your default profile directory by running the command:\n",
81 "\n",
82 " ipython locate\n",
83 "\n",
84 "The default version of `ipython_notebook_config.py` lists all of the options available along with documentation for each. Changes made to that file will affect all notebook servers run under that profile. Command line options always override those set in configuration files.\n",
85 "\n",
86 "More details about IPython configuration files and profiles can be found [here](http://ipython.org/ipython-doc/dev/config/intro.html)."
87 ]
88 },
89 {
90 "cell_type": "heading",
91 "level": 2,
92 "metadata": {},
93 "source": [
94 "Securing the notebook server"
95 ]
96 },
97 {
98 "cell_type": "markdown",
99 "metadata": {},
100 "source": [
101 "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:\n",
102 "\n",
103 "1. Setting a password\n",
104 "2. Encrypt network traffic using SSL\n",
105 "\n",
106 "\n",
107 "\n",
108 "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.security.passwd`:\n",
109 "\n",
110 "```python\n",
111 "In [1]: from IPython.lib import passwd\n",
112 "In [2]: passwd()\n",
113 "Enter password: \n",
114 "Verify password: \n",
115 "Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'\n",
116 "```\n",
117 "\n",
118 "<div class=\"alert alert-warn\">\n",
119 "`IPython.lib.security.passwd` can also take the password as a string argument. **Do not** pass it as an argument inside an IPython session, as it will be saved in your input history.\n",
120 "</div>\n",
121 "\n",
122 "You can then add this to your `ipython_notebook_config.py`:\n",
123 "\n",
124 "```python\n",
125 "# Password to use for web authentication\n",
126 "c = get_config()\n",
127 "c.NotebookApp.password = \n",
128 "u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'\n",
129 "```\n",
130 "When using a password, it is a good idea to also use SSL, so that your \n",
131 "password is not sent unencrypted by your browser. You can start the notebook \n",
132 "to communicate via a secure protocol mode using a self-signed certificate with \n",
133 "the command::\n",
134 "\n",
135 " $ ipython notebook --certfile=mycert.pem\n",
136 "\n",
137 ".. note::\n",
138 "\n",
139 " A self-signed certificate can be generated with ``openssl``. For example, \n",
140 " the following command will create a certificate valid for 365 days with \n",
141 " both the key and certificate data written to the same file::\n",
142 "\n",
143 " $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem\n",
144 "\n",
145 "Your browser will warn you of a dangerous certificate because it is\n",
146 "self-signed. If you want to have a fully compliant certificate that will not\n",
147 "raise warnings, it is possible (but rather involved) to obtain one,\n",
148 "as explained in detail in `this tutorial`__.\n",
149 "\n",
150 ".. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars\n",
151 "\t\n",
152 "Keep in mind that when you enable SSL support, you will need to access the\n",
153 "notebook server over ``https://``, not over plain ``http://``. The startup\n",
154 "message from the server prints this, but it is easy to overlook and think the\n",
155 "server is for some reason non-responsive."
156 ]
157 },
158 {
159 "cell_type": "markdown",
160 "metadata": {},
161 "source": [
162 "Running a public notebook server\n",
163 "--------------------------------\n",
164 "\n",
165 "If you want to access your notebook server remotely via a web browser,\n",
166 "you can do the following. \n",
167 "\n",
168 "Start by creating a certificate file and a hashed password, as explained \n",
169 "above. Then create a custom profile for the notebook, with the following \n",
170 "command line, type::\n",
171 "\n",
172 " $ ipython profile create nbserver\n",
173 "\n",
174 "In the profile directory just created, edit the file \n",
175 "``ipython_notebook_config.py``. By default, the file has all fields \n",
176 "commented; the minimum set you need to uncomment and edit is the following::\n",
177 "\n",
178 " c = get_config()\n",
179 "\n",
180 " # Kernel config\n",
181 " c.IPKernelApp.pylab = 'inline' # if you want plotting support always\n",
182 "\n",
183 " # Notebook config\n",
184 " c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'\n",
185 " c.NotebookApp.ip = '*'\n",
186 " c.NotebookApp.open_browser = False\n",
187 " c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]'\n",
188 " # It is a good idea to put it on a known, fixed port\n",
189 " c.NotebookApp.port = 9999\n",
190 "\n",
191 "You can then start the notebook and access it later by pointing your browser \n",
192 "to ``https://your.host.com:9999`` with ``ipython notebook \n",
193 "--profile=nbserver``.\n",
194 "\n",
195 "Running with a different URL prefix\n",
196 "-----------------------------------\n",
197 "\n",
198 "The notebook dashboard (the landing page with an overview\n",
199 "of the notebooks in your working directory) typically lives at the URL\n",
200 "``http://localhost:8888/``. If you prefer that it lives, together with the \n",
201 "rest of the notebook, under a sub-directory,\n",
202 "e.g. ``http://localhost:8888/ipython/``, you can do so with\n",
203 "configuration options like the following (see above for instructions about\n",
204 "modifying ``ipython_notebook_config.py``)::\n",
205 "\n",
206 " c.NotebookApp.base_url = '/ipython/'\n",
207 " c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}\n",
208 "\n",
209 "Using a different notebook store\n",
210 "--------------------------------\n",
211 "\n",
212 "By default, the notebook server stores the notebook documents that it saves as \n",
213 "files in the working directory of the notebook server, also known as the\n",
214 "``notebook_dir``. This logic is implemented in the \n",
215 ":class:`FileNotebookManager` class. However, the server can be configured to \n",
216 "use a different notebook manager class, which can \n",
217 "store the notebooks in a different format. \n",
218 "\n",
219 "The bookstore_ package currently allows users to store notebooks on Rackspace\n",
220 "CloudFiles or OpenStack Swift based object stores.\n",
221 "\n",
222 "Writing a notebook manager is as simple as extending the base class\n",
223 ":class:`NotebookManager`. The simple_notebook_manager_ provides a great example\n",
224 "of an in memory notebook manager, created solely for the purpose of\n",
225 "illustrating the notebook manager API.\n",
226 "\n",
227 ".. _bookstore: https://github.com/rgbkrk/bookstore\n",
228 "\n",
229 ".. _simple_notebook_manager: https://github.com/khinsen/simple_notebook_manager\n",
230 "\n",
231 "Known issues\n",
232 "------------\n",
233 "\n",
234 "When behind a proxy, especially if your system or browser is set to autodetect\n",
235 "the proxy, the notebook web application might fail to connect to the server's\n",
236 "websockets, and present you with a warning at startup. In this case, you need\n",
237 "to configure your system not to use the proxy for the server's address.\n",
238 "\n",
239 "For example, in Firefox, go to the Preferences panel, Advanced section,\n",
240 "Network tab, click 'Settings...', and add the address of the notebook server\n",
241 "to the 'No proxy for' field."
242 ]
243 }
244 ],
245 "metadata": {}
246 }
247 ]
9 } No newline at end of file
248 }
General Comments 0
You need to be logged in to leave comments. Login now