-
Notifications
You must be signed in to change notification settings - Fork 3
/
07_JupyterLab.Rmd
164 lines (124 loc) · 8.16 KB
/
07_JupyterLab.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
# JupyterLab
This document shows how to pull and run a JupyterLab server locally and
remotely.
## Run Jupyter Lab Locally
This guide assumes you meet the following requirements in your personal
machine (eg. laptop):
1. You have admin rights over your machine
1. You are running either Windows 10 Pro, macOS, or Linux
Assuming Docker is up and running (check [`setup_docker.md`](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:
1. Run on the same terminal as above the following command:
```shell
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.
2. Open your favorite browser (preferably Firefox or Chrome) and point it to
`localhost:8888`
3. 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:
```shell
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`.
4. 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.
## 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.
- Login to the remote machine:
```
ssh <username>@<server.ip.address>
```
1. Launch the container:
```shell
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
1. Run `jupyter notebook --generate-config`
1. Generate password as in the official [tutorial](http://jupyter-notebook.readthedocs.io/en/stable/public_server.html#preparing-a-hashed-password)
1. 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:
```shell
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out mycert.pem
```
1. Next we shall update the `/home/jovyan/.jupyter/jupyter_notebook_config.py` file:
```python
# 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
```
1. Launch secure Lab: `jupyter lab`
1. 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.
### 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](https://jupyter-notebook.readthedocs.io/en/stable/public_server.html#using-let-s-encrypt).
## 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:
```shell
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
```
## Useful Python Docker Images
- [`gds_env`](https://github.com/darribas/gds_env): a containerised platform
for Geographid Data Science in Jupyter (Python & R)
- [`jupyter-stacks`](https://github.com/jupyter/docker-stacks): official
Jupyter stacks (the `gds_env` is based on these)
## 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:
```shell
nano /home/jovyan/.jupyter/jupyter_notebook_config.py
```
A guide to using nano can be found [here](https://www.howtogeek.com/howto/42980/the-beginners-guide-to-nano-the-linux-command-line-text-editor/).