Debian Codegraph @

docs/source/howto/configuration/config-user-env.md

raw
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 ![named servers on the home page](/images/named-servers-home.png)
177
178 as well as the admin page:
179
180 ![named servers on the admin page](/images/named-servers-admin.png)
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 :::