Jupyter Notebook Server installation

Create a new user

For this example, we will be using a Linux username hyperion.

In order to create a new user in Linux and set up a password, use the following commands:

sudo useradd -m hyperion
sudo passwd hyperion

Note:

• -m is required in order to create user’s home directory
• the command to remove the user is: userdel hyperion

To make sure that the user has been created, you can preview the contents of the /etc/passwords file:

cat /etc/passwd

or use the awk command:

awk -F':' '{ print $1}' /etc/passwd

(See this nixCraft FAQ entry for more details.)

Note:

• do not append this user to the sudoers group — for security reasons it should be a non-sudo user.

Optional step: in order to prevent other users from being able to list directories owned by the new user you can use the following command:

sudo chmod -R go-rwx /home/hyperion

Now, enter shell as the newly created user:

sudo -i -u hyperion

Make sure that you are in this user’s shell:

echo $USER

---

SSL Certificate

In order to generate a self-signed certificate use the following commands (see the documentation on openssl key generation):

mkdir ~/.certs
cd ~/.certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout jupkey.key -out jupcert.pem

---

Install and configure the Apache server

For this step you need sudo rights, so you need to leave new user’s (hyperion‘s) shell — you can just type (or hit Ctrl + d):

exit

Make sure that you operate as your original user (the one with sudo rights):

echo $USER

Install Apache

Install the Apache and enable modules required by the Jupyter Notebook server.

sudo apt-get install apache2
sudo a2enmod proxy proxy_http proxy_https proxy_wstunnel ssl headers
sudo systemctl restart apache2

Configure Apache

This step is required in order to configure the proxy for your server. The proxy is required to run the Jupyter server a a normal (non-sudo) user.

Make sure that self-signed certificates were generated (see the previous step).

Prepare the configuration file at /etc/apache2/sites-available/jupyter.conf (e.g., by using vim). First, create the file:

sudo vim /etc/apache2/sites-available/jupyter.conf

You need to know what is the external IP address of the server you are using. In order to get to know that you can use: ifconfig, ip address, or:

hostname -I | awk '{print $1}'

(See also this post on obtaining your IP address.)

Now, back to the /etc/apache2/sites-available/jupyter.conf file:

CAUTION! In the file contents below replace the SERVER_IP with your server’s IP (note that SERVER_IP is in two places in the text below):

<VirtualHost *:443>

  ServerName localhost

  # configure SSL
  SSLEngine on
  SSLCertificateFile /home/hyperion/.certs/jupcert.pem
  SSLCertificateKeyFile /home/hyperion/.certs/jupkey.key

  SSLProxyEngine On
  SSLProxyVerify none
  SSLProxyCheckPeerCN off
  SSLProxyCheckPeerName off
  SSLProxyCheckPeerExpire off

  Redirect permanent / https://SERVER_IP/jupyter

  <Location /jupyter>
    # preserve Host header to avoid cross-origin problems
    ProxyPreserveHost on
    ProxyPass         https://localhost:8888/jupyter
    ProxyPassReverse  https://localhost:8888/jupyter
    ProxyPassReverseCookieDomain localhost:8888 SERVER_IP
    RequestHeader set Origin "https://localhost:8888"
  </Location>

  <Location /jupyter/api/kernels/>
	ProxyPass        wss://localhost:8888/jupyter/api/kernels/
	ProxyPassReverse wss://localhost:8888/jupyter/api/kernels/
  </Location>

  <Location /jupyter/terminals/websocket/>
	ProxyPass        wss://localhost:8888/jupyter/terminals/websocket/
	ProxyPassReverse wss://localhost:8888/jupyter/terminals/websocket/
  </Location>
</VirtualHost>

# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

Note! The above configuration assumes that you are using username hyperion and certificate name jupcert.*. In case you modified these filename, make sure to modify the configuration file as well.

Note! Both: the Apache and Jupyter Notebook have to use SSL certificates, and it has to be the same certificate.

Having configured the Apache, enable site, and restart the Apache service:

sudo a2ensite jupyter.conf
sudo service apache2 restart

---

Install and configure the Jupyter Notebook server

For hosting Jupyter Notebook serve you wish to use a virtual Python environment. For that install pipenv with pip.

sudo pip install pipenv

Due to the security reasons, a Jupyter Notebook server has to be run by a non-sudo user, hence, in order to configure Jupyter Notebook server, you has to use non-sudo user’s shell. Therefore, switch to non-sudo user’s command line again:

sudo -i -u hyperion

Note! For the purpose of this tutorial we will be creating a virtual environment for the Jupyter Notebook Server in user’s home directory.

In the home directory, create a Pipfile:

vim ~/Pipfile

Paste in the following content to this file:

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]
ipdb = "*"
ipython = "*"
jupyter = "*"
matplotlib = "*"
notebook = "*"
opencv-python = "*"
pandas = "*"
scipy = "*"
seaborn = "*"
sklearn = "*"
statsmodels = "*"

[requires]
python_version = "3"

Install the virtual environment using pipenv (it can take a while, just be patient 🙂 ):

pipenv install

Create password and hash it (see the official documentation). After running the command below, type or paste-in your password:

pipenv run python -c "from notebook.auth import passwd; print(passwd())"

You should see an output similar to the following:

argon2:$argon2id$v=19$m=10240,t=10,p=8$9mD ...

Create Jupyter Notebook configuration file at ~/.jupyter/jupyter_notebook_config.py:

mkdir ~/.jupyter
vim ~/.jupyter/jupyter_notebook_config.py

Paste in the following configuration:

c.NotebookApp.allow_origin = '*'
c.NotebookApp.allow_remote_access = True
c.NotebookApp.base_url = '/hyperion'
c.NotebookApp.certfile = '/home/hyperion/.certs/jupcert.pem'
c.NotebookApp.keyfile = '/home/hyperion/.certs/jupkey.key'
c.NotebookApp.ip = 'localhost'
c.NotebookApp.open_browser = False
c.NotebookApp.password = u'argon2:$argon2id$v=19$m=102...<your hashed password here>'
c.NotebookApp.port = 8888
c.NotebookApp.trust_xheaders = True

---

Run Jupyter Notebook server as a service

Check what is the directory (ID) of your virtual environment. To get the virtual environment directory:

ls ~/.local/share/virtualenvs/

Now you can leave non-sudo user’s shell because we will need sudo command again. You can just type:

exit

Then, as a sudo user, create the service configuration file:

sudo vim /etc/systemd/system/jupyter.service

Change $USER to your (jupyter, i.e., non-sudo) username (e.g., hyperion), and change $VENV_ID to virtual environment ID (from the previous step).

The contents of the service file (/etc/systemd/system/jupyter.service) should be as follows:

[Unit]
Description=Jupyter Workplace

[Service]
Type=simple
PIDFile=/run/jupyter.pid
ExecStart=/home/$USER/.local/share/virtualenvs/$USER-$VENV_ID/bin/jupyter-notebook --config=/home/$USER/.jupyter/jupyter_notebook_config.py
User=$USER
Group=$USER
WorkingDirectory=/home/$USER
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Finally, start and enable the service:

sudo systemctl start jupyter.service
sudo systemctl enable jupyter.service

---

Additional apache settings

You can also set up automatic redirect of all HTTP requests to HTTPS. In order to do so with Apache you need to enable a rewrite module (also/formerly known as mod_rewrite:

sudo a2enmod rewrite

Then edit the apache’s jupyter configuration file:

sudo vim /etc/apache2/sites-available/jupyter.conf

and add the following code at the beginning of your file:

<VirtualHost *:80>
        DocumentRoot "/var/www/html"
        ServerName http://localhost
        ServerAdmin root@localhost
 
        RewriteEngine On
        RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
</VirtualHost>

Finally, restart the apache service:

sudo service apache2 restart

If you see no errors, you are all good, and the redirect should work.

---

Sources

• The official documentation
• Configuring Jupyter and Apache
• Source of the Apache configuration
• How to generate password with IPython
• Cover photo graphic