Remote Access to a Public Jupyter Notebook Server

Jupyter Notebook is a great way to share documents with other collaborators (e.g. team members) to collaborate on analytic use cases. Of course, it is not only limited to that:

The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text. Uses include: data cleaning and transformation, numerical simulation, statistical modeling, machine learning and much more.

– Official definition from jupyter.org

In this post, I will walk-through the steps I took to set up a simple Jupyter Notebook server that is used on the LAN.

If this is your first time hearing about Jupyter Notebooks, I recommend browsing through the official site (http://jupyter.org), and using the free online viewer (https://nbviewer.jupyter.org/) to get a better understanding of this technology.

Some of the steps below have already been documented by very talented people on the Internet – where relevant, I will provide the link to the official article I referenced to give credit where it is due.

In summary, the high level steps I took were:

1. Begin with a fresh “minimal install” of CentOS 7 (Minor Release 7 (1611))
2. Install the latest version of Python 3 and pip
3. Install Jupyter Notebook
4. Open Jupyter Notebook Server Port in Firewall
5. Configure Jupyter Notebook to Accept Remote Connections
6. Adding a Login Password

Although Jupyter Notebook runs on both (Python 3.3 or greater, or Python 2.7), I used Python 3 to take advantage of pip, which comes bundled together. Detailed steps listed below – hope you have fun 🙂

List of Steps

Step 1: Minimal Install of CentOS 7

I use Oracle VM VirtualBox to set up a fresh minimal install of CentOS 7 because I like my servers lightweight, and secure.

Create both a root account, and a non-root account.

Step 2: Install Python 3 and pip

Credits to: https://www.digitalocean.com/community/tutorials/how-to-install-python-3-and-set-up-a-local-programming-environment-on-centos-7

CentOS 7 (Minor Release 7 (1611)) comes pre-installed with Python 2.7.5. However, I choose to install Python 3 so as to use pip to install Jupyter (more in step 3).

As root, update the system with a package update, and install both the “yum-utils” and “CentOS Development Tools” packages that will be required to build and compile Python3 from source code.

# yum -y update
# yum -y install yum-utils
# yum -y groupinstall development

After which, we will need to install the “IUS (Inline with Upstream Stable) package” so as to provide to RPM new repositories to look for newer versions of some software:

# yum install https://centos7.iuscommunity.org/ius-release.rpm

Last but not least, install the latest version of Python (refer to the version number from the official Python site at http://www.python.org), and the corresponding pip version. At the point of this article, it was 3.6.1.

# yum install python36u
(Output truncated...)
# python3.6 -V
Python 3.6.1
# yum install python36u-pip

Step 3: Install Jupyter Notebook

With Python3 and pip installed, this step will be a piece of cake. Simply use pip to install:

# pip3.6 install jupyter

Other installation options available at the official Jupyter website: http://jupyter.org/install.html

Step 4: Open Jupyter Notebook Server Port in Firewall

By default, Jupyter Notebook uses a web server to serve out its interface via port 8888 on the host machine. Because this is a fresh minimal install of CentOS 7, the port has to be opened using the firewall-cmd utility (or equivalent).

The option –get-active-zones will print the currently active zones and the network interfaces that are active in this zones.

# firewall-cmd --get-active-zones
public
interfaces: enp0s3 enp0s8
# firewall-cmd --zone=public --add-port=8888/tcp
success

Step 5: Configure Jupyter Notebook to Accept Remote Connections (i.e. function as a Public Notebook Server)

Jupyter recommends that a non-root user runs the Jupyter Notebook Server – and rightfully so. However, you can choose to override it with the –allow-root option at your own risk.

Login as the non-root user, and in the home directory, check if a “.jupyter” folder exists. This folder holds the notebook configuration file “jupyter_notebook_config.py”. If it does not exist, create it with the following command:

$ jupyter notebook --generate-config

Open the “jupyter_notebook_config.py” configuration file inside the “.jupyter” folder with your preferred text editor. Find the commented out configuration line that defines the value of “c.NotebookApp.ip”, and change the value to ‘0.0.0.0’ or ‘*’ to allow remote connections from all IP addresses (realistically, you may not want to do this).

$ vi ./.jupyter/jupyter_notebook_config.py
# Configuration file for jupyter-notebook.
...
#------------------------------------------------------------------------------
# NotebookApp(JupyterApp) configuration
#------------------------------------------------------------------------------
...
## The IP address the notebook server will listen on.
#c.NotebookApp.ip = 'localhost'
c.NotebookApp.ip = '0.0.0.0'

More information can be found on the official documentation: http://jupyter-notebook.readthedocs.io/en/latest/public_server.html#notebook-public-server

At this stage, you can type the following command in your host terminal to start the Jupyter Notebook:

$ jupyter notebook --no-browser
[I 15:23:43.536 NotebookApp] Serving notebooks from local directory: /home/user
[I 15:23:43.536 NotebookApp] 0 active kernels
[I 15:23:43.536 NotebookApp] The Jupyter Notebook is running at: http://0.0.0.0:8888/?token=f1cd3eeb4dd9368d60d...
[I 15:23:43.537 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 15:23:43.538 NotebookApp]

 Copy/paste this URL into your browser when you connect for the first time,
 to login with a token:
 http://0.0.0.0:8888/?token=f1cd3eeb4dd9368d60d...

I added the –no-browser flag because this is the minimal install of CentOS that is basically a stripped down version without a lot of utilities and programs, including a browser. By default, Jupyter will attempt to open the IP address using the system’s browser. In our case, it will instead throw several errors when it cannot find a browser to do so.

At this juncture, feel free to access your Jupyter Notebook Server at HOST_IP_ADDR:8888, or copy and paste the link provided in the terminal output. In the first approach, you will be asked to enter a login token.

This is because a login password has not been configured. While this is not wrong, it forces the user to handle long strings of random tokens that are regenerated each time the server is restarted.

For ease of use, it may be better to set a secure password.

Step 6: Adding a Login Password

In the non-root user’s terminal, press Ctrl + C to stop the running Jupyter Notebook Server.

Set a login password with the following command:

$ jupyter notebook password
Enter password:
Verify password:
[NotebookPasswordApp] Wrote hashed password to /home/user/.jupyter/jupyter_notebook_config.json

A hash of the password is stored in the file listed above. Restart the server and notice that the URL provided no longer contains a random session token to be used for login.

$ jupyter notebook --no-browser
[I 15:31:39.273 NotebookApp] Serving notebooks from local directory: /home/user
[I 15:31:39.273 NotebookApp] 0 active kernels
[I 15:31:39.273 NotebookApp] The Jupyter Notebook is running at: http://0.0.0.0:8888/
[I 15:31:39.273 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).

Navigate to HOST_IP_ADDR:8888 to access your Jupyter Notebook Server. If you find yourself in the homepage without entering a password, click on the logout button and try again.

---

Hope this walk-through has helped you get started with your Public Jupyter Notebook Server. To serve out Notebooks via the web browser, simply place the .ipynb files in the home directory of the non-root user.

More details about securing a public server can be found on the official documentation site.