Chapter 8 JupyterLab

This document shows how to pull and run a JupyterLab server locally and remotely.

8.1 Run Jupyter Lab Locally

This guide assumes you meet the following requirements in your personal machine (eg. laptop):

You have admin rights over your machine
You are running either Windows 10 Pro, macOS, or Linux

Assuming Docker is up and running (check setup_docker.md for that), you can pull an “image”, which will let you run containers, by typing on a command line (Terminal.app or PowerShell are both good options):

docker pull darribas/gds:4.0

Upon executing the above command you will see output providing information regarding the download progress. Once the above command has finished installing your GDS stack, you are ready to go! To get a Jupyter session started, you can follow these steps:

Run on the same terminal as above the following command:

docker run --rm -ti --user root -e NB_UID=$UID -e NB_GID=100 -p 8888:8888 -v ${PWD}:/home/jovyan/work darribas/gds:4.0

The command above spins up a container of the gds image, version 4.0 and ensures it is connected through two main bridges:

Mapping your laptop’s file system from where you have launched the command (${PWD}) to a folder called work on the home directory of the container. When you login to Jupyter (see below), you will see a work folder and, if you click into it, you should see the content of your laptops folder in there.
Mapping port 8888 from the container to your laptop, so you can connect to it through a browser.

It is important to know this command starts a Jupyter server on your machine and keeps it running, so please do not quit the window until you are done using Jupyter, otherwise it will crash.

Open your favorite browser (preferably Firefox or Chrome) and point it to localhost:8888

You will be asked for a password or a token. To find the correct one, check the terminal where you started the docker run ... command in 1) and look for the long token in the logs. Your prompt should look something (albeit not exactly) like this:

 docker run --rm -ti -p 8888:8888 -v ${PWD}:/home/jovyan/work darribas/gds:4.0
 Executing the command: jupyter notebook
 [I 11:38:40.234 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
 [I 11:38:41.328 NotebookApp] Loading IPython parallel extension
 [I 11:38:41.612 NotebookApp] JupyterLab extension loaded from /opt/conda/lib/python3.7/site-packages/jupyterlab
 [I 11:38:41.612 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
 [I 11:38:43.091 NotebookApp] Serving notebooks from local directory: /home/jovyan
 [I 11:38:43.091 NotebookApp] The Jupyter Notebook is running at:
 [I 11:38:43.091 NotebookApp] http://ee20e7549b49:8888/?token=4dc814ee44c64383d5d32dfd439fe62bbc17d9803d9ae434
 [I 11:38:43.091 NotebookApp]  or http://127.0.0.1:8888/?token=4dc814ee44c64383d5d32dfd439fe62bbc17d9803d9ae434
 [I 11:38:43.091 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
 [C 11:38:43.114 NotebookApp]

     To access the notebook, open this file in a browser:
         file:///home/jovyan/.local/share/jupyter/runtime/nbserver-6-open.html
     Or copy and paste one of these URLs:
         http://ee20e7549b49:8888/?token=4dc814ee44c64383d5d32dfd439fe62bbc17d9803d9ae434
      or http://127.0.0.1:8888/?token=4dc814ee44c64383d5d32dfd439fe62bbc17d9803d9ae434

The token you want to copy is the long series of letter and numbers right after ?token=, starting by 4dc814ee.

The token should let you into your Jupyter Lab session. Congratulations! You can then access the files in your computer through the work directory on the left-side pane.

8.2 Run Jupyter Lab Remotely

It is also possible to start a Jupyter server as above but, instead of run it on your local machine, it can run on a remote machine and you connect to that through your browser over the internet. The process in this context is a bit more intricate because you need to ensure that the connection is secure, but overall it follows a similar pattern. The following steps below assume you can login to the remote server where you want to run Jupyter through ssh and the serve already has a Docker image installed, ready to be run.

Launch the container:
```
docker run --rm -ti --user root -e NB_UID=$UID -e NB_GID=100 -p <mapping_port>:8888 -v ${PWD}:/home/jovyan/work darribas/gds:4.1 start.sh  
```
Note we are appending start.sh so it drops us into the command line of the container rather than launching the server directly
Run jupyter notebook --generate-config
Generate password as in the official tutorial
Since we will be using the created password we shall also enable SSL (secure sockets layer). SSL is a protocol for web browsers and servers that allows for the authentication, encryption and decryption of data sent over the Internet. Therefore, by enabling SSL our password won’t be sent unencypted by our browser when we login to the server. We shall generate a self-signed SSL certificate with:
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out mycert.pem
```

Next we shall update the /home/jovyan/.jupyter/jupyter_notebook_config.py file:

# Set options for certfile, ip, password, and toggle off
# browser auto-opening
c.NotebookApp.certfile = u'/home/jovyan/mycert.pem'
c.NotebookApp.keyfile = u'/home/jovyan/mykey.key'
# Set ip to '*' to bind on all interfaces (ips) for the public server
c.NotebookApp.ip = '*'
c.NotebookApp.password = u'sha1:bcd259ccf...<your hashed password here>'
c.NotebookApp.open_browser = False

# It is a good idea to set a known, fixed port for server access
c.NotebookApp.port = 8888

Launch secure Lab: jupyter lab
On your own machine (laptop/tablet), log in to https://<server.ip.address>:<mapping_port> with the password you have set. Since we are using SSL make sure you specify https:// in your browser.

8.2.1 Self-signed Certificate Warnings

Upon accessing the notebook server your browser might warn you that your self-signed certificate is insecure or unrecognized. A fully compliant self-signed certificate is required to prevent these warnins. One approach towards solving this issue is to acquire a free SSL certificate via Let’s Encrypt.

8.3 Using sudo within a container

For the above image password authentication has been disabled for the NB_USER jovyan. However, you might want to install additional programs using a package management tool (e.g., apt). To do so you can grant the within-container NB_USER passwordless sudo access by adding -e GRANT_SUDO=yes and –user root when launching the image:

docker run --rm -ti -e GRANT_SUDO=yes --user root -e NB_UID=$UID -e NB_GID=100 -p 8889:8888 -v ${PWD}:/home/jovyan/work darribas/gds:4.1 start.sh

8.4 Useful Python Docker Images

gds_env: a containerised platform for Geographid Data Science in Jupyter (Python & R)
jupyter-stacks: official Jupyter stacks (the gds_env is based on these)

8.5 Practical

Follow the steps in the Remote Install section to run jupyter lab on one of the remote servers.

Note that you will need to use the command line editing software nano to edit update jupyter_notebook_config.py:

nano /home/jovyan/.jupyter/jupyter_notebook_config.py

A guide to using nano can be found here.