Commit fbb028ae authored by Willi Rath's avatar Willi Rath

Merge branch 'add-crs-remarks' into 'master'

Unify spelling of JupyerLab

See merge request !2
parents ed7e1a5a ec44066b
# How to work with Jupyter everywhere
# How to work with JupyterLab everywhere
_This guide **will** walk you through the complete setup of JupyterLab and
one or more scientific Python computing environments on your local computer
or on a remote machine._
## Install the base environment and Jupyterlab
_This guild **will not** explain how to use the shell, how to connect to
remote machines via SSH, or how to make sure you have acces to the relevant
networks, e.g., via VPN._
_Currently, **only Linux / Unix** and **MacOSX** are covered._
## Install the base environment and JupyterLab
_This will show how to download the installer, install a minimal Python
environment, and start Jupyerlab. The installation will be (nearly) identical
for a local computer or for any Linux / Unix remote computer._
environment, and start JupyerLab. Execute the steps below on the computer
where the calculation should be performed (e.g., your local computer or a
computer in a remote computing centre)._
### Download and install Miniconda3
_(No matter if you want to work with Python 3, which you probably should, or
Python 2, the base environment should be Python 3.)_
Python 2, the **base environment should be Python 3**.)_
To download the latest installer, run
To download the latest installer
- on Linux:
- on Linux, run:
```bash
curl https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -o Miniconda3.sh
```
- on MaxOSX:
- on MaxOSX, run:
```bash
curl https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o Miniconda3.sh
```
......@@ -35,7 +47,7 @@ follow the instructions for Miniconda**3** and do _**not**_ make this
installation your standard Python.)
### Activating the base environment and installing Jupyterlab
### Activate the base environment and install JupyterLab
To activate the base environment, run:
```bash
......@@ -49,7 +61,7 @@ conda install jupyterlab nb_conda_kernels
```
### Start Jupyterlab
### Start JupyterLab
After activating the base environment with
```bash
......@@ -68,8 +80,17 @@ Copy/paste this URL into your browser when you connect for the first time,
```
Copy the URL (from your shell!) to your web browser. You should see Jupyter
lab.
Copy the URL (from your shell!) to your web browser. You should see JupyterLab.
---
---
_**Note** that at this point, you only have a minimal Python 3 installation with
a functional JupyterLab frontend. To perform scientific analyses, you need to add one
or more environments with a selection of scientific software._
---
---
## Add a scientific Python environment and use it
......@@ -92,17 +113,30 @@ conda create -n py3_std python=3 numpy matplotlib scipy ipykernel
```
_(Do **always** install `ipykernel` into the environment, to make sure that
Jupyter recognizes the new environment as a kernel.)_
JupyterLab recognizes the new environment as a kernel.)_
### Use the environment in Jupyterlab
### Use the environment in JupyterLab
Above, we created a new environment `py3_std`. To use it, activate the `base`
environment and start Jupyterlab. There, you should be able to create a new
environment and start JupyterLab. There, you should be able to create a new
notebook and choose the `py3_std` environment as its kernel.
---
---
_At this point, you know how to set up a full Python installation including a
JupyterLab front end in the `base` environment and one or more scientific
computing environments that can be used in real scientific analyses. The
instructions above work on any local or remote Linux / Unix or MacOSX machine.
Below, you'll learn how to connect to JupyterLab if you installed Python on a
remote machine that you can only connect to via SSH._
---
---
## Connect to Jupyterlab running on a remote machine
## Connect to JupyterLab running on a remote machine
_This will show how to connect to Jupyterlab if your web browser cannot
directly access its address._
......@@ -111,7 +145,7 @@ directly access its address._
### Start Jupyterlab on a remote machine
After installing Jupyter and your Python environments on a remote machine,
follow the instructions on how to [Start Jupyterlab][#start-jupyterlab] above.
follow the instructions on how to [Start JupyterLab](#start-jupyterlab) above.
But before pasting the URL provided by Jupyter into your browser, make sure to
follow the next steps.
......@@ -125,11 +159,14 @@ ssh -f -D localhost:54321 user@host.example.com sleep 15
chromium-browser --proxy-server="socks5://localhost:54321"
```
This will open an SSH session that provides a local network socket tunneling
all traffic through `host.example.com` and then tell chromium to use this
socket as aproxy server. (The next step provides a script that bundles this and
handles a few caveats like isolating the tunneled browser session from your
other activities on the internet.)
This will open an SSH session that provides a local network socket listening
on port `54321` that tunnels all traffic through `host.example.com` and then tell
chromium to use this socket as aproxy server. (The next step provides a script
that bundles this and handles a few caveats like isolating the tunneled browser
session from your other activities on the internet.)
_Note that instead of `54321`, we could have used any free non-privileged (number
between 1024 and 65535) port._
### Wrapped in a script
......@@ -151,9 +188,11 @@ Note that these steps will only work, if `host.example.com` is a known host in
continue and if you do, `host.example.com` will be added to `.ssh/known_hosts`.)
### Connect your browser to the remote Jupyterlab
### Connect your browser to the remote JupyterLab
Now, you can paste the URL provided by Jupyterlab into the tunneled browser.
Now, you can paste the URL (usually of the form
`http://localhost:8888/?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`)
provided by JupyterLab into the tunneled browser.
## Appendix: Jargon
......@@ -165,5 +204,5 @@ Now, you can paste the URL provided by Jupyterlab into the tunneled browser.
are collections of packages / versions that make it possible to switch
between different sets of software.
- [Jupyter lab](https://en.wikipedia.org/wiki/Project_Jupyter#Jupyter_Lab) is
an integrated computing environment
- [JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906) is
an integrated web-based computing environment
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment