README.md 5.03 KB
Newer Older
Willi Rath's avatar
Willi Rath committed
1
# How to work with JupyterLab everywhere
Willi Rath's avatar
Willi Rath committed
2 3


Willi Rath's avatar
Willi Rath committed
4
## Install the base environment and JupyterLab
Willi Rath's avatar
Willi Rath committed
5 6

_This will show how to download the installer, install a minimal Python
Willi Rath's avatar
Willi Rath committed
7
environment, and start JupyerLab.  The installation will be (nearly) identical
Willi Rath's avatar
Willi Rath committed
8 9
for a local computer or for any Linux / Unix remote computer._

Willi Rath's avatar
Willi Rath committed
10 11 12
### Download and install Miniconda3

_(No matter if you want to work with Python 3, which you probably should, or
Willi Rath's avatar
Willi Rath committed
13
Python 2, the base environment should be Python 3.)_
Willi Rath's avatar
Willi Rath committed
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

To download the latest installer, run

- on Linux:
  ```bash
  curl https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -o Miniconda3.sh
  ```

- on MaxOSX:
  ```bash
  curl https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o Miniconda3.sh
  ```

To install, run (on both, Linux and MacOSX):
```bash
bash Miniconda3.sh -b -p ${HOME}/miniconda3
```

(If this fails, check
<https://conda.io/docs/user-guide/install/#regular-installation>, make sure to
Willi Rath's avatar
Willi Rath committed
34
follow the instructions for Miniconda**3** and do _**not**_ make this
Willi Rath's avatar
Willi Rath committed
35 36 37
installation your standard Python.)


Willi Rath's avatar
Willi Rath committed
38
### Activate the base environment and install JupyterLab
Willi Rath's avatar
Willi Rath committed
39 40 41 42 43 44 45 46 47 48 49 50 51

To activate the base environment, run:
```bash
source ${HOME}/miniconda3/bin/activate base
```

Then (and in the same terminal), install `jupyterlab` and `nb_conda_kernels`,
by running:
```bash
conda install jupyterlab nb_conda_kernels
```


Willi Rath's avatar
Willi Rath committed
52
### Start JupyterLab
Willi Rath's avatar
Willi Rath committed
53

54 55 56 57 58
After activating the base environment with
```bash
source ${HOME}/miniconda3/bin/activate base
```
run:
Willi Rath's avatar
Willi Rath committed
59 60 61 62 63 64 65 66 67 68 69 70
```bash
jupyter lab --no-browser
```

This will print a few lines to your screen and finally show something like:
```
Copy/paste this URL into your browser when you connect for the first time,
    to login with a token:
        http://localhost:8888/?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

```

Willi Rath's avatar
Willi Rath committed
71
Copy the URL (from your shell!) to your web browser.  You should see JupyterLab.
Willi Rath's avatar
Willi Rath committed
72

Willi Rath's avatar
Willi Rath committed
73 74 75 76 77 78 79

## Add a scientific Python environment and use it

_This will show how to add a Python environment that can be used for scientific
analyses._


80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
### Add a scientific environment

To add a new environment, first activate the `base` environment:
```bash
source ${HOME}/miniconda3/bin/activate base
```

Then, create an environment (called `py3_std` in this example, and containing
Python 3, `numpy`, `matplotlib`, `scipy`):
```bash
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.)_


Willi Rath's avatar
Willi Rath committed
97
### Use the environment in JupyterLab
98 99

Above, we created a new environment `py3_std`.  To use it, activate the `base`
Willi Rath's avatar
Willi Rath committed
100
environment and start JupyterLab.  There, you should be able to create a new
101 102 103
notebook and choose the `py3_std` environment as its kernel.


Willi Rath's avatar
Willi Rath committed
104
## Connect to JupyterLab running on a remote machine
Willi Rath's avatar
Willi Rath committed
105 106 107 108 109

_This will show how to connect to Jupyterlab if your web browser cannot
directly access its address._


Willi Rath's avatar
Willi Rath committed
110 111
### Start Jupyterlab on a remote machine

112
After installing Jupyter and your Python environments on a remote machine,
Willi Rath's avatar
Willi Rath committed
113
follow the instructions on how to (Start JupyterLab)[#start-jupyterlab] above.
114 115
But before pasting the URL provided by Jupyter into your browser, make sure to
follow the next steps.
Willi Rath's avatar
Willi Rath committed
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


### The essential steps

To let your browser see the network like it looks from a remote machine
(called `host.example.com` here), run the following:
```bash
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.)


### Wrapped in a script

Download the script (only needed once):
```bash
curl https://git.geomar.de/python/jupyter_on_HPC_setup_guide/raw/master/scripts/run_chromium_through_ssh_tunnel.sh -O
chmod a+x run_chromium_through_ssh_tunnel.sh
```

And run it to connect to `host.example.com`:
```bash
./run_chromium_through_ssh_tunnel.sh user@host.example.com
```

147 148 149 150 151
Note that these steps will only work, if `host.example.com` is a known host in 
`.ssh/known_hosts`. (To test this, simply create a ssh connection to 
`host.example.com`, if it is not yet a known host, you will be asked whether to 
continue and if you do, `host.example.com` will be added to `.ssh/known_hosts`.)

Willi Rath's avatar
Willi Rath committed
152

Willi Rath's avatar
Willi Rath committed
153
### Connect your browser to the remote JupyterLab
154

Willi Rath's avatar
Willi Rath committed
155
Now, you can paste the URL provided by JupyterLab into the tunneled browser.
156 157


Willi Rath's avatar
Willi Rath committed
158 159 160 161 162
## Appendix: Jargon

- `conda` is the package manager of the [Anaconda Python
  distribution](https://en.wikipedia.org/wiki/Anaconda_(Python_distribution))

Willi Rath's avatar
Willi Rath committed
163 164 165 166
- [conda environments](https://conda.io/docs/user-guide/tasks/manage-environments.html)
  are collections of packages / versions that make it possible to switch
  between different sets of software.

Willi Rath's avatar
Willi Rath committed
167 168
- [JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906) is
  an integrated web-based computing environment