The five-minute guide to setting up a Jupyter notebook server

Nearly every day, I teach a course in Python. And nearly every day, I thus use the Jupyter notebook: I do my live-coding demos in it, answer students’ questions using it, and also send it to my students at the end of the day, so that they can review my code without having to type furiously or take pictures of my screen.

I also encourage my students to install the notebook — not just so that they can open the file I send them at the end of each day, but also so that they can learn to experiment, iterate, and play with their code using a modern interactive environment.

My two-day class in regular expressions uses Python, but as a means to an end: I teach the barest essentials of Python in an hour or so, just so that we can read from files and search inside of them using regular expressions. For this class, it’s overkill to ask the participants to install Python, especially if they plan to use other languages in their work.

When I teach this class, then, I set up a server that is only used for my course. Students can all log into the Jupyter notebook, create and use their own notebook files, and avoid installing anything new on their own computers.

Moreover, this whole setup now takes me just a few minutes. And since the class lasts only two days, I’m paying a few dollars for the use of a server that doesn’t contain any valuable data on it. So if someone happens to break into the server or ruin it, or if one of my students happens to mess around with things, nothing from my own day-to-day work will be ruined or at risk.

How do I do this? It’s pretty simple, actually:

Create a new server. I use Digital Ocean, because they’re cheap and easy to set up. When I teach a class in Israel or Europe, I use one of their European data centers (or should I say “centres”), because it’ll be a bit faster. If a large number of students will participate, then I might get a server with a lot of RAM, but I normally get one of the most basic DO plans. I normally set up an Ubuntu server, but you’re welcome ot use any version of Linux you want.

I log in as root, and add a bunch of packages, starting with “python-pip”. (Note that this assumes you’re willing to use Python 2. I don’t really care which version I use for this class; when Ubuntu switches to Python 3, I’ll gladly use that instead.) This ensures that the Python “pip” program is installed, allowing me to install Python packages:

apt-get install unzip emacs wget curl python-pip

I then use “pip” to install the “ipython[notebook]” package, which in turn downloads and installs everything else I’ll need:

pip install -U 'ipython[notebook]' # yes, you need the quotes

Next, I create a “student” user. It is under this user that I’ll run the notebook.

As the “student” user, I start the notebook with the “–generate-config” option. This creates a configuration directory (~/student/.jupyter) with a configuration file (jupyter_notebook_config.py) inside of it:

jupyter notebook --generate-config

Open the jupyter_notebook_config.py file, which is (as the suffix indicates) a Python file, defining a number of variables. You’ll need to set a few of these in order for things to work; from my experience, changing four lines is sufficient:

c.NotebookApp.open_browser = False # no browser needed on a server

c.NotebookApp.ip = '0.0.0.0' # listen on the network

NotebookApp.password = u'' # don't require a password

c.NotebookApp.token = '' # don't require a security token

These final two instructions, to remove password protection and the security token, are debatable. On the one hand, my server will exist for two days at most, and won’t have any important data on it. On the other hand, you could argue that I’ve provided a new entry point for bad people in the world to attack the rest of the Internet.

Once that’s done, go back to the Unix shell, and launch the notebook using “nohup”, so that even if/when you log out, the server will still keep running:

nohup jupyter notebook

Once this is done, your server should be ready! If you’re at the IP address 192.168.1.1, then you should at this point be able to point your browser to http://192.168.1.1:8888, and you’ll see the Jupyter notebook. You can, of course, change the port that’s being used; I’ve found that when working from a cafe, non-standard ports can sometimes be blocked. Do remember that low-numbered ports, such as 80, can only be used by root, so you’ll need something higher, such as 8000 or 8080.

Also note that working this way means that all users have identical permissions. This means that in theory, one student can delete, change, or otherwise cause problems in another student’s notebook. In practice, I’ve never found this to be a problem.

A bigger problem is that the notebook’s back end can sometimes fail. In such cases, you’ll need to ssh back into the server and restart the Jupyter notebook process. It’s frustrating, but relatively rare. By using “nohup”, I’ve been able to avoid the server going down whenever my ssh connection died and/or I logged out.

I’ve definitely found that using the Jupyter notebook has improved my teaching. Having my students use it in my courses has also improved their learning! And as you can see, setting it up is a quick operation, requiring no more than a few minutes just before class starts. Just don’t forget to shut down the server when you’re done, or you’ll end up paying for a server you don’t need.

Enjoyed this article? Join more than 11,000 other developers who receive my free, weekly “Better developers” newsletter. Every Monday, you’ll get an article like this one about software development and Python:

[…] Reuven Lerner: The five-minute guide to setting up a Jupyter notebook server Nearly every day, I teach a course in Python. And nearly every day, I thus use the Jupyter notebook: I do my live-coding demos in it, answer students’ questions using it, and also send it to my students at the end of the day, so that they can review my code without having to type furiously or take pictures of my screen. […]

Right! I actually ran it in the foreground, did a control-Z, and then used “bg”. Either way will work, but yours is shorter and more elegant. And of course, I didn’t say anything about this at all in my posting…

Maybe! I’ve heard a lot about Docker (some good, some bad), and even used a system based on Docker at a client’s office last year. But I haven’t had time enough to explore it, or to try it in this sort of situation. It might indeed be a great solution — have an empty Docker system (instance? template?) ready for use, and roll it out every time you start a new course.

Save my name, email, and website in this browser for the next time I comment.

Bernardo
-
last year

I see you set it up for the local network. Do you have any tips for doing it remotely? I set it up, got it running and popped up my browser, put in the non-local ip and just waited… waited… and then waited a bit more until timing out.

You don’t need to set up a firewall for remote connections, but it’s a good idea if the site will be up for any length of time, or is on a network with anything secure on it.

I typically don’t use a firewall with my courses, but I am running the notebook on a server that’s open for a few days only, and that if it goes down, nothing bad will happen to me (or my students’ work).