| 1 |
(howto:config:user-env)= |
| 2 |
|
| 3 |
# Configuring user environments |
| 4 |
|
| 5 |
To deploy JupyterHub means you are providing Jupyter notebook environments for |
| 6 |
multiple users. Often, this includes a desire to configure the user |
| 7 |
environment in a custom way. |
| 8 |
|
| 9 |
Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook |
| 10 |
server, most configuration and documentation that applies to Jupyter Notebook |
| 11 |
applies to the single-user environments. Configuration of user environments |
| 12 |
typically does not occur through JupyterHub itself, but rather through system-wide |
| 13 |
configuration of Jupyter, which is inherited by `jupyterhub-singleuser`. |
| 14 |
|
| 15 |
**Tip:** When searching for configuration tips for JupyterHub user environments, you might want to remove JupyterHub from your search because there are a lot more people out there configuring Jupyter than JupyterHub and the configuration is the same. |
| 16 |
|
| 17 |
This section will focus on user environments, which includes the following: |
| 18 |
|
| 19 |
- [Installing packages](#installing-packages) |
| 20 |
- [Configuring Jupyter and IPython](#configuring-jupyter-and-ipython) |
| 21 |
- [Installing kernelspecs](#installing-kernelspecs) |
| 22 |
- [Using containers vs. multi-user hosts](#multi-user-hosts-vs-containers) |
| 23 |
|
| 24 |
## Installing packages |
| 25 |
|
| 26 |
To make packages available to users, you will typically install packages system-wide or in a shared environment. |
| 27 |
|
| 28 |
This installation location should always be in the same environment where |
| 29 |
`jupyterhub-singleuser` itself is installed in, and must be _readable and |
| 30 |
executable_ by your users. If you want your users to be able to install additional |
| 31 |
packages, the installation location must also be _writable_ by your users. |
| 32 |
|
| 33 |
If you are using a standard Python installation on your system, use the following command: |
| 34 |
|
| 35 |
```bash |
| 36 |
sudo python3 -m pip install numpy |
| 37 |
``` |
| 38 |
|
| 39 |
to install the numpy package in the default Python 3 environment on your system |
| 40 |
(typically `/usr/local`). |
| 41 |
|
| 42 |
You may also use conda to install packages. If you do, you should make sure |
| 43 |
that the conda environment has appropriate permissions for users to be able to |
| 44 |
run Python code in the env. The env must be _readable and executable_ by all |
| 45 |
users. Additionally it must be _writeable_ if you want users to install |
| 46 |
additional packages. |
| 47 |
|
| 48 |
## Configuring Jupyter and IPython |
| 49 |
|
| 50 |
[Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/configuring/config_overview.html) |
| 51 |
and [IPython](https://ipython.readthedocs.io/en/stable/development/config.html) |
| 52 |
have their own configuration systems. |
| 53 |
|
| 54 |
As a JupyterHub administrator, you will typically want to install and configure environments for all JupyterHub users. For example, let's say you wish for each student in a class to have the same user environment configuration. |
| 55 |
|
| 56 |
Jupyter and IPython support **"system-wide"** locations for configuration, which is the logical place to put global configuration that you want to affect all users. It's generally more efficient to configure user environments "system-wide", and it's a good practice to avoid creating files in the users' home directories. |
| 57 |
The typical locations for these config files are: |
| 58 |
|
| 59 |
- **system-wide** in `/etc/{jupyter|ipython}` |
| 60 |
- **env-wide** (environment wide) in `{sys.prefix}/etc/{jupyter|ipython}`. |
| 61 |
|
| 62 |
### Jupyter environment configuration priority |
| 63 |
|
| 64 |
When Jupyter runs in an environment (conda or virtualenv), it prefers to load configuration from the environment over each user's own configuration (e.g. in `~/.jupyter`). |
| 65 |
This may cause issues if you use a _shared_ conda environment or virtualenv for users, because e.g. jupyterlab may try to write information like workspaces or settings to the environment instead of the user's own directory. |
| 66 |
This could fail with something like `Permission denied: $PREFIX/etc/jupyter/lab`. |
| 67 |
|
| 68 |
To avoid this issue, set `JUPYTER_PREFER_ENV_PATH=0` in the user environment: |
| 69 |
|
| 70 |
```python |
| 71 |
c.Spawner.environment.update( |
| 72 |
{ |
| 73 |
"JUPYTER_PREFER_ENV_PATH": "0", |
| 74 |
} |
| 75 |
) |
| 76 |
``` |
| 77 |
|
| 78 |
which tells Jupyter to prefer _user_ configuration paths (e.g. in `~/.jupyter`) to configuration set in the environment. |
| 79 |
|
| 80 |
### Example: Enable an extension system-wide |
| 81 |
|
| 82 |
For example, to enable the `cython` IPython extension for all of your users, create the file `/etc/ipython/ipython_config.py`: |
| 83 |
|
| 84 |
```python |
| 85 |
c.InteractiveShellApp.extensions.append("cython") |
| 86 |
``` |
| 87 |
|
| 88 |
### Example: Enable a Jupyter notebook configuration setting for all users |
| 89 |
|
| 90 |
:::{note} |
| 91 |
These examples configure the Jupyter ServerApp, which is used by JupyterLab, the default in JupyterHub 2.0. |
| 92 |
|
| 93 |
If you are using the classing Jupyter Notebook server, |
| 94 |
the same things should work, |
| 95 |
with the following substitutions: |
| 96 |
|
| 97 |
- Search for `jupyter_server_config`, and replace with `jupyter_notebook_config` |
| 98 |
- Search for `NotebookApp`, and replace with `ServerApp` |
| 99 |
|
| 100 |
::: |
| 101 |
|
| 102 |
To enable Jupyter notebook's internal idle-shutdown behavior (requires notebook ≥ 5.4), set the following in the `/etc/jupyter/jupyter_server_config.py` file: |
| 103 |
|
| 104 |
```python |
| 105 |
# shutdown the server after no activity for an hour |
| 106 |
c.ServerApp.shutdown_no_activity_timeout = 60 * 60 |
| 107 |
# shutdown kernels after no activity for 20 minutes |
| 108 |
c.MappingKernelManager.cull_idle_timeout = 20 * 60 |
| 109 |
# check for idle kernels every two minutes |
| 110 |
c.MappingKernelManager.cull_interval = 2 * 60 |
| 111 |
``` |
| 112 |
|
| 113 |
## Installing kernelspecs |
| 114 |
|
| 115 |
You may have multiple Jupyter kernels installed and want to make sure that they are available to all of your users. This means installing kernelspecs either system-wide (e.g. in /usr/local/) or in the `sys.prefix` of JupyterHub |
| 116 |
itself. |
| 117 |
|
| 118 |
Jupyter kernelspec installation is system-wide by default, but some kernels |
| 119 |
may default to installing kernelspecs in your home directory. These will need |
| 120 |
to be moved system-wide to ensure that they are accessible. |
| 121 |
|
| 122 |
To see where your kernelspecs are, you can use the following command: |
| 123 |
|
| 124 |
```bash |
| 125 |
jupyter kernelspec list |
| 126 |
``` |
| 127 |
|
| 128 |
### Example: Installing kernels system-wide |
| 129 |
|
| 130 |
Let's assume that I have a Python 2 and Python 3 environment that I want to make sure are available, I can install their specs **system-wide** (in /usr/local) using the following command: |
| 131 |
|
| 132 |
```bash |
| 133 |
/path/to/python3 -m ipykernel install --prefix=/usr/local |
| 134 |
/path/to/python2 -m ipykernel install --prefix=/usr/local |
| 135 |
``` |
| 136 |
|
| 137 |
## Multi-user hosts vs. Containers |
| 138 |
|
| 139 |
There are two broad categories of user environments that depend on what |
| 140 |
Spawner you choose: |
| 141 |
|
| 142 |
- Multi-user hosts (shared system) |
| 143 |
- Container-based |
| 144 |
|
| 145 |
How you configure user environments for each category can differ a bit |
| 146 |
depending on what Spawner you are using. |
| 147 |
|
| 148 |
The first category is a **shared system (multi-user host)** where |
| 149 |
each user has a JupyterHub account, a home directory as well as being |
| 150 |
a real system user. In this example, shared configuration and installation |
| 151 |
must be in a 'system-wide' location, such as `/etc/`, or `/usr/local` |
| 152 |
or a custom prefix such as `/opt/conda`. |
| 153 |
|
| 154 |
When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or |
| 155 |
DockerSpawner), the 'system-wide' environment is really the container image used for users. |
| 156 |
|
| 157 |
In both cases, you want to _avoid putting configuration in user home |
| 158 |
directories_ because users can change those configuration settings. Also, home directories typically persist once they are created, thereby making it difficult for admins to update later. |
| 159 |
|
| 160 |
## Named servers |
| 161 |
|
| 162 |
By default, in a JupyterHub deployment, each user has one server only. |
| 163 |
|
| 164 |
JupyterHub can, however, have multiple servers per user. |
| 165 |
This is mostly useful in deployments where users can configure the environment in which their server will start (e.g. resource requests on an HPC cluster), so that a given user can have multiple configurations running at the same time, without having to stop and restart their own server. |
| 166 |
|
| 167 |
To allow named servers, include this code snippet in your config file: |
| 168 |
|
| 169 |
```python |
| 170 |
c.JupyterHub.allow_named_servers = True |
| 171 |
``` |
| 172 |
|
| 173 |
Named servers were implemented in the REST API in JupyterHub 0.8, |
| 174 |
and JupyterHub 1.0 introduces UI for managing named servers via the user home page: |
| 175 |
|
| 176 |
 |
| 177 |
|
| 178 |
as well as the admin page: |
| 179 |
|
| 180 |
 |
| 181 |
|
| 182 |
Named servers can be accessed, created, started, stopped, and deleted |
| 183 |
from these pages. Activity tracking is now per server as well. |
| 184 |
|
| 185 |
To limit the number of **named server** per user by setting a constant value, include this code snippet in your config file: |
| 186 |
|
| 187 |
```python |
| 188 |
c.JupyterHub.named_server_limit_per_user = 5 |
| 189 |
``` |
| 190 |
|
| 191 |
Alternatively, to use a callable/awaitable based on the handler object, include this code snippet in your config file: |
| 192 |
|
| 193 |
```python |
| 194 |
def named_server_limit_per_user_fn(handler): |
| 195 |
user = handler.current_user |
| 196 |
if user and user.admin: |
| 197 |
return 0 |
| 198 |
return 5 |
| 199 |
|
| 200 |
c.JupyterHub.named_server_limit_per_user = named_server_limit_per_user_fn |
| 201 |
``` |
| 202 |
|
| 203 |
This can be useful for quota service implementations. The example above limits the number of named servers for non-admin users only. |
| 204 |
|
| 205 |
If `named_server_limit_per_user` is set to `0`, no limit is enforced. |
| 206 |
|
| 207 |
When using named servers, Spawners may need additional configuration to take the `servername` into account. Whilst `KubeSpawner` takes the `servername` into account by default in [`pod_name_template`](https://jupyterhub-kubespawner.readthedocs.io/en/latest/spawner.html#kubespawner.KubeSpawner.pod_name_template), other Spawners may not. Check the documentation for the specific Spawner to see how singleuser servers are named, for example in `DockerSpawner` this involves modifying the [`name_template`](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/api/index.html) setting to include `servername`, eg. `"{prefix}-{username}-{servername}"`. |
| 208 |
|
| 209 |
(classic-notebook-ui)= |
| 210 |
|
| 211 |
## Switching back to the classic notebook |
| 212 |
|
| 213 |
By default, the single-user server launches JupyterLab, |
| 214 |
which is based on [Jupyter Server][]. |
| 215 |
|
| 216 |
This is the default server when running JupyterHub ≥ 2.0. |
| 217 |
To switch to using the legacy Jupyter Notebook server (notebook < 7.0), you can set the `JUPYTERHUB_SINGLEUSER_APP` environment variable |
| 218 |
(in the single-user environment) to: |
| 219 |
|
| 220 |
```bash |
| 221 |
export JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp' |
| 222 |
``` |
| 223 |
|
| 224 |
:::{note} |
| 225 |
|
| 226 |
``` |
| 227 |
JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp' |
| 228 |
``` |
| 229 |
|
| 230 |
is only valid for notebook < 7. notebook v7 is based on jupyter-server, |
| 231 |
and the default jupyter-server application must be used. |
| 232 |
Selecting the new notebook UI is no longer a matter of selecting the server app to launch, |
| 233 |
but only the default URL for users to visit. |
| 234 |
To use notebook v7 with JupyterHub, leave the default singleuser app config alone (or specify `JUPYTERHUB_SINGLEUSER_APP=jupyter-server`) and set the default _URL_ for user servers: |
| 235 |
|
| 236 |
```python |
| 237 |
c.Spawner.default_url = '/tree/' |
| 238 |
``` |
| 239 |
|
| 240 |
::: |
| 241 |
|
| 242 |
[jupyter server]: https://jupyter-server.readthedocs.io |
| 243 |
[jupyter notebook]: https://jupyter-notebook.readthedocs.io |
| 244 |
|
| 245 |
:::{versionchanged} 2.0 |
| 246 |
|
| 247 |
JupyterLab is now the default single-user UI, if available, |
| 248 |
which is based on the [Jupyter Server][], |
| 249 |
no longer the legacy [Jupyter Notebook][] server. |
| 250 |
JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`), |
| 251 |
and the Jupyter server could be selected by specifying the following: |
| 252 |
|
| 253 |
```python |
| 254 |
# jupyterhub_config.py |
| 255 |
c.Spawner.cmd = ["jupyter-labhub"] |
| 256 |
``` |
| 257 |
|
| 258 |
Alternatively, for an otherwise customized Jupyter Server app, |
| 259 |
set the environment variable using the following command: |
| 260 |
|
| 261 |
```bash |
| 262 |
export JUPYTERHUB_SINGLEUSER_APP='jupyter_server.serverapp.ServerApp' |
| 263 |
``` |
| 264 |
|
| 265 |
::: |