hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-07 10:04:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1969 from willingc/edit-userenv

Browse Source 
Edit and reflow user environment reference
This commit is contained in:
Min RK
2018-06-13 09:49:23 +02:00
committed by GitHub
parent 681d3ce2d8 37f4c4429e
commit edd8e21f71
1 changed files with 87 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/source/reference/config-user-env.md
View File

@@ -1,35 +1,51 @@
# Configuring user environments
Deploying JupyterHub means you are providing Jupyter notebook environments for multiple users.
Often, this includes a desire to configure the user environment in some way.
Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook server, most configuration and documentation that applies to Jupyter applies to the single-user environments.
Configuration of user environments typically does not occur through JupyterHub itself,
but rather through system-wide configuration of Jupyter,
which is inherited by `jupyterhub-singleuser`.
Deploying JupyterHub means you are providing Jupyter notebook environments for
multiple users. Often, this includes a desire to configure the user
environment in some way.
**Tip:** When searching for configuration tips for JupyterHub,
try removing JupyterHub from your search because there are a lot more people out there configuring Jupyter than JupyterHub and the configuration is the same.
Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook
server, most configuration and documentation that applies to Jupyter Notebook
applies to the single-user environments. Configuration of user environments
typically does not occur through JupyterHub itself, but rather through system-
wide configuration of Jupyter, which is inherited by `jupyterhub-singleuser`.
**Tip:** When searching for configuration tips for JupyterHub user
environments, try removing JupyterHub from your search because there are a lot
more people out there configuring Jupyter than JupyterHub and the
configuration is the same.
This section will focus on user environments, including:
- Installing packages
- Configuring Jupyter and IPython
- Installing kernelspecs
- Using containers vs. multi-user hosts
## Installing packages
To make packages available to users,
This generally means installing packages system-wide or in a shared environment.
It should always be in the same environment that `jupyterhub-singleuser` itself is installed in,
and must be readable and executable by your users.
If you want users to be able to install additional packages,
it must also be *writable* by your users.
To make packages available to users, you generally will install packages
system-wide or in a shared environment.
This installation location should always be in the same environment that
`jupyterhub-singleuser` itself is installed in, and must be *readable and
executable* by your users. If you want users to be able to install additional
packages, it must also be *writable* by your users.
If you are using a standard system Python install, you would use:
If you are using a standard system Python install,
this means using:
```bash
sudo python3 -m pip install numpy
```
to install numpy in the default system Python 3 environment (typically `/usr/local`).
to install the numpy package in the default system Python 3 environment
(typically `/usr/local`).
You can also use conda to install packages, but you should make sure that the conda environment has appropriate permissions for users to be able to run Python code in the env.
You may also use conda to install packages. If you do, you should make sure
that the conda environment has appropriate permissions for users to be able to
run Python code in the env.
## Configuring Jupyter and IPython
@@ -37,12 +53,21 @@ You can also use conda to install packages, but you should make sure that the co
[Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/config_overview.html)
and [IPython](https://ipython.readthedocs.io/en/stable/development/config.html)
have their own configuration systems.
As an administrator, it is a good idea to avoid creating files in users' home directories.
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.
The typical locations for these config files are system-wide in `/etc/{jupyter|ipython}`
or env-wide in `{sys.prefix}/etc/{jupyter|ipython}`.
As a JupyterHub administrator, you will typically want to install and configure
environments for all JupyterHub users. For example, you wish for each student in
a class to have the same user environment configuration.
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 idea to avoid creating files in users' home directories.
The typical locations for these config files are:
- **system-wide** in `/etc/{jupyter|ipython}`
- **env-wide** (environment wide) in `{sys.prefix}/etc/{jupyter|ipython}`.
### Example: Enable an extension system-wide
For example, to enable the `cython` IPython extension for all of your users,
create the file `/etc/ipython/ipython_config.py`:
@@ -51,9 +76,11 @@ create the file `/etc/ipython/ipython_config.py`:
c.InteractiveShellApp.extensions.append("cython")
```
To enable Jupyter notebook's internal idle-shutdown behavior
(requires notebook ≥ 5.4),
in `/etc/jupyter/jupyter_notebook_config.py`:
### Example: Enable a Jupyter notebook configuration setting for all users
To enable Jupyter notebook's internal idle-shutdown behavior (requires
notebook ≥ 5.4), set the following in the `/etc/jupyter/jupyter_notebook_config.py`
file:
```python
# shutdown the server after no activity for an hour
@@ -67,20 +94,25 @@ c.MappingKernelManager.cull_interval = 2 * 60
## Installing kernelspecs
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 itself.
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
itself.
Jupyter kernelspec installation is system wide by default, but some kernels
may default to installing kernelspecs in your home directory. These will need
to be moved system-wide to ensure that they are accessible.
Jupyter kernelspec installation is system wide by default,
but some kernels may default to installing kernelspecs in your home directory.
These will need to be moved system-wide to ensure that they are accessible.
You can see where your kernelspecs are with:
```bash
jupyter kernelspec list
```
Assuming 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) with:
### Example: Installing kernels system-wide
Assuming 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) with:
```bash
/path/to/python3 -m IPython kernel install --prefix=/usr/local
@@ -88,18 +120,28 @@ Assuming I have a Python 2 and Python 3 environment that I want to make sure are
```
## Containers vs multi-user hosts
## Multi-user hosts vs. Containers
There are two broad categories of user environments that depend on what Spawner you choose,
and how you configure user environments can differ a bit depending on what you are using.
The first category is a shared system where each user has an account and a home directory and a real system user.
In this example, shared configuration and installation must be in a 'system-wide' location, such as `/etc/` or `/usr/local` or a custom prefix
such as `/opt/conda`.
There are two broad categories of user environments that depend on what
Spawner you choose:
In container-based Spawners (e.g. KubeSpawner or DockerSpawner),
the 'system-wide' environment is really the image you are using for users.
- Multi-user hosts (shared sytem)
- Container-based
In both cases, you want to avoid putting configuration in user home directories
because users can change those,
and home directories typically persist once they are created,
so difficult for admins to update later.
How you configure user environments for each category can differ a bit
depending on what Spawner you are using.
The first category is a **shared system (multi-user host)** where
each user has a JupyterHub account and a home directory as well as being
a real system user. In this example, shared configuration and installation
must be in a 'system-wide' location, such as `/etc/` or `/usr/local`
or a custom prefix such as `/opt/conda`.
When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or
DockerSpawner), the 'system-wide' environment is really the container image
which you are using for users.
In both cases, you want to *avoid putting configuration in user home
directories* because users can change those configuration settings. Also,
home directories typically persist once they are created, so they are
difficult for admins to update later.