Jupyter Notebook Server on macOS

Run Jupyter Notebook Server as a background service on your mac.

Generate a Login Password

The first thing you need to do is to generate a password for your server, such that all your codes / resources are being protected.

Open terminal, type ipython to enter interactive console, then enter the following:

from notebook.auth import passwd
Generate password hash in iPython console

The password you entered here will be the password for logging in your Jupyter notebook server.

The output of the passwd() function is the hash of your password, you will need to paste the hash into your Jupyter configuration file later.

Configure the Jupyter Notebook

You first need a configuration file to configure your notebook server. Generate the config file with the follow command in terminal:

jupyter notebook --generate-config

A jupyter_notebook_config.py will be saved in your ~/.jupyter directory, open it and edit the follow entries:

You may now start your notebook server by typing jupyter notebook in terminal, and you can be able to access it from any computer in your network, with your server IP address and the default port 8888.

Server setup successful if you see the above login page

Type in the password (not the hash) and you are good to go.

Start the Server as a Background Service

In stead of staring the server with jupyter notebook in terminal, we can use the following command to start the server in background, then close the terminal.

jupyter notebook &> /dev/null &

What we did above is to put all the text output generated by the server to void (&> /dev/null), then run the server process in background (the last &).

You can also check the server process with the following command:

ps aux | grep jupyter

You will get the process ID from the above command, and you can stop the server by:

kill -9 <PID>

Optional Setup

Above is the minimal setup for runing a Jupyter Notebook server in background on mac. If you would like to enhance the server security and usability, here listed some extra things you can do.

Using HTTPS for Secure Server Access

If you would like to connect the server through a secure connection, such that your password is encrypted during network transmittion, you can enable SSL of your server.

If you refer to the Jupyter Notebook documentation, they suggest us to generate self-signed certificate and private key for SSL connection. It does work in desktop computers and Android devices. However, it doesn’t work in iOS devices, no matter using Safari, Chrome, or native Jupyter client apps.

A better solution is to be the Certificate Authority (CA) yourself, and generate a CA cert to sign your own SSL cert. The details of generate self-signed CA cert, SSL cert and private key could be found in Juno’s documentation. The doc also demonstrated how to install the CA cert into iOS devices.

After generating the SSL cert and key, you need to specify them in the Jupyter configuration file. Open your Jupyter_notebook_config.py again and edit the following entries:

After restarting the Jupyter Notebook server, you may access your server with https protocol.

As your cert is self-signed, your browser will warn you and you have to click show details and visit this website to confirm that you trust the cert and the site. You also need to type in your mac login password for accepting the cert for your computer.

Special Notes for iOS devices: at the time of writing, most functionalities of Jupyter Notebook work well in web browsers, however some keyboard shortcuts, say escape / control-m / tap auto-completion are not functioning in both Safari and Chrome… using native app like Juno seems a better choice at the moment.

Start the Server in Background During Login

There are serveral ways to start the notebook server during login, such as setting up a launchd deamon. However, I prefer setting Login Items in System Preferences → Users & Groups as its simplier to implement.

We first create an Login Item using Automator App

  • launch Automator app, select “Application” for document type
  • drag Library → Utilities → Run shell script to the workflow area
  • paste the following script and save it as JupyterAutoStart.app

The script did pretty much the same as Start the Server as a Background Service above. Here we also save the server process ID into a text file, such that we can kill the old server instance and start a new one if we login again.

After adding the Login Item, re-login to check if your notebook server is runing at the background or not.

Router Setting for Servers in LAN

You have to do port mapping on your router if you want to access a server in LAN from the internet. Here I use Apple Airport Extreme as an example, but all routers should work similarly.

Open AirPort Utitility → Network → Port Settings, add a new entry and map the public TCP port to your private(your local server) TCP port.

Last but not least, you may want to apply for a dynamic DNS service such that you don’t have to change your server URL everytime your IP changed.