zhangyiss/the-littlest-jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/the-littlest-jupyterhub.git synced 2025-12-18 21:54:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

adopt myst

Browse Source 
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
2023-03-27 09:31:02 +02:00
parent a5e72046ab
commit de36cfc116
96 changed files with 4131 additions and 4491 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/topic/authenticator-configuration.md Normal file
View File

@@ -0,0 +1,89 @@
(topic-authenticator-configuration)=
# Configuring JupyterHub authenticators
Any [JupyterHub authenticator](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators)
can be used with TLJH. A number of them ship by default with TLJH:
1. [OAuthenticator](https://github.com/jupyterhub/oauthenticator) - Google, GitHub, CILogon,
GitLab, Globus, Mediawiki, auth0, generic OpenID connect (for KeyCloak, etc) and other
OAuth based authentication methods.
2. [LDAPAuthenticator](https://github.com/jupyterhub/ldapauthenticator) - LDAP & Active Directory.
3. [DummyAuthenticator](https://github.com/yuvipanda/jupyterhub-dummy-authenticator) - Any username,
one shared password. A {ref}`how-to guide on using DummyAuthenticator <howto/auth/dummy>` is also
available.
4. [FirstUseAuthenticator](https://github.com/yuvipanda/jupyterhub-firstuseauthenticator) - Users set
their password when they log in for the first time. Default authenticator used in TLJH.
5. [TmpAuthenticator](https://github.com/jupyterhub/tmpauthenticator) - Opens the JupyterHub to the
world, makes a new user every time someone logs in.
6. [NativeAuthenticator](https://native-authenticator.readthedocs.io/en/latest/) - Allow users to signup, add password security verification and block users after failed attempts oflogin.
We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
everything, this guide shows you how to use any authenticator you want with JupyterHub by following
the authenticator's documentation.
## Setting authenticator properties
JupyterHub authenticators are customized by setting _traitlet properties_. In the authenticator's
documentation, you will find these are usually represented as:
```python
c.<AuthenticatorName>.<property-name> = <some-value>
```
You can set these with `tljh-config` with:
```bash
sudo tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
```
### Example
[LDAPAuthenticator's documentation](https://github.com/jupyterhub/ldapauthenticator#required-configuration)
lists the various configuration options you can set for LDAPAuthenticator.
When the documentation asks you to set `LDAPAuthenticator.server_address`
to some value, you can do that with the following command:
```bash
sudo tljh-config set auth.LDAPAuthenticator.server_address 'my-ldap-server'
```
Most authenticators require you set multiple configuration options before you can
enable them. Read the authenticator's documentation carefully for more information.
## Enabling the authenticator
Once you have configured the authenticator as you want, you should then
enable it. Usually, the documentation for the authenticator would ask you to add
something like the following to your `jupyterhub_config.py` to enable it:
```python
c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
```
You can accomplish the same with `tljh-config`:
```bash
sudo tljh-config set auth.type <fully-qualified-authenticator-name>
```
Once enabled, you need to reload JupyterHub for the config to take effect.
```bash
sudo tljh-config reload
```
Try logging in a separate incognito window to check if your configuration works. This
lets you preserve your terminal in case there were errors. If there are
errors, {ref}`troubleshooting/logs` should help you debug them.
### Example
From the [documentation](https://github.com/jupyterhub/ldapauthenticator#usage) for
LDAPAuthenticator, we see that the fully qualified name is `ldapauthenticator.LDAPAuthenticator`.
Assuming you have already configured it, the following commands enable LDAPAuthenticator.
```bash
sudo tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
sudo tljh-config reload
```

95
docs/topic/authenticator-configuration.rst
View File

@@ -1,95 +0,0 @@
.. _topic/authenticator-configuration:
=====================================
Configuring JupyterHub authenticators
=====================================
Any `JupyterHub authenticator <https://github.com/jupyterhub/jupyterhub/wiki/Authenticators>`_
can be used with TLJH. A number of them ship by default with TLJH:
#. `OAuthenticator <https://github.com/jupyterhub/oauthenticator>`_ - Google, GitHub, CILogon,
GitLab, Globus, Mediawiki, auth0, generic OpenID connect (for KeyCloak, etc) and other
OAuth based authentication methods.
#. `LDAPAuthenticator <https://github.com/jupyterhub/ldapauthenticator>`_ - LDAP & Active Directory.
#. `DummyAuthenticator <https://github.com/yuvipanda/jupyterhub-dummy-authenticator>`_ - Any username,
one shared password. A :ref:`how-to guide on using DummyAuthenticator <howto/auth/dummy>` is also
available.
#. `FirstUseAuthenticator <https://github.com/yuvipanda/jupyterhub-firstuseauthenticator>`_ - Users set
their password when they log in for the first time. Default authenticator used in TLJH.
#. `TmpAuthenticator <https://github.com/jupyterhub/tmpauthenticator>`_ - Opens the JupyterHub to the
world, makes a new user every time someone logs in.
#. `NativeAuthenticator <https://native-authenticator.readthedocs.io/en/latest/>`_ - Allow users to signup, add password security verification and block users after failed attempts oflogin.
We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
everything, this guide shows you how to use any authenticator you want with JupyterHub by following
the authenticator's documentation.
Setting authenticator properties
================================
JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's
documentation, you will find these are usually represented as:
.. code-block:: python
c.<AuthenticatorName>.<property-name> = <some-value>
You can set these with ``tljh-config`` with:
.. code-block:: bash
sudo tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
Example
-------
`LDAPAuthenticator's documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
lists the various configuration options you can set for LDAPAuthenticator.
When the documentation asks you to set ``LDAPAuthenticator.server_address``
to some value, you can do that with the following command:
.. code-block:: bash
sudo tljh-config set auth.LDAPAuthenticator.server_address 'my-ldap-server'
Most authenticators require you set multiple configuration options before you can
enable them. Read the authenticator's documentation carefully for more information.
Enabling the authenticator
==========================
Once you have configured the authenticator as you want, you should then
enable it. Usually, the documentation for the authenticator would ask you to add
something like the following to your ``jupyterhub_config.py`` to enable it:
.. code-block:: python
c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
You can accomplish the same with ``tljh-config``:
.. code-block:: bash
sudo tljh-config set auth.type <fully-qualified-authenticator-name>
Once enabled, you need to reload JupyterHub for the config to take effect.
.. code-block:: bash
sudo tljh-config reload
Try logging in a separate incognito window to check if your configuration works. This
lets you preserve your terminal in case there were errors. If there are
errors, :ref:`troubleshooting/logs` should help you debug them.
Example
-------
From the `documentation <https://github.com/jupyterhub/ldapauthenticator#usage>`_ for
LDAPAuthenticator, we see that the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
Assuming you have already configured it, the following commands enable LDAPAuthenticator.
.. code-block:: bash
sudo tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
sudo tljh-config reload

135
docs/topic/customizing-installer.md Normal file
View File

@@ -0,0 +1,135 @@
(topic-customizing-installer)=
# Customizing the Installer
The installer can be customized with commandline parameters. The default installer
is executed as:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
<parameters>
```
This page documents the various options you can pass as commandline parameters to the installer.
(topic-customizing-installer-admin)=
## Serving a temporary "TLJH is building" page
`--show-progress-page` serves a temporary "TLJH is building" progress page while TLJH is building.
```{image} ../images/tljh-is-building-page.gif
:alt: Temporary progress page while TLJH is building
```
- The page will be accessible at `http://<tljh-public-ip>/index.html` in your browser.
When TLJH installation is complete, the progress page page will stop and you will be able
to access TLJH as usually at `http://<tljh-public-ip>`.
- From the progress page, you will also be able to access the installation logs, by clicking the
**Logs** button or by going directly to `http://<tljh-public-ip>/logs` in your browser.
To update the logs, refresh the page.
:::{note}
The `http://<tljh-public-ip>/index.html` page refreshes itself automatically every 30s.
When JupyterHub starts, a JupyterHub 404 HTTP error message (_Jupyter has lots of moons, but this is not one..._)
will be shown instead of the progress page. This means JupyterHub was started succesfully and you can access it
either by clicking the `Control Panel` button or by going to `http://<tljh-public-ip>/` directly.
:::
For example, to enable the progress page and add the first _admin_ user, you would run:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin --show-progress-page
```
## Adding admin users
`--admin <username>:<password>` adds user `<username>` to JupyterHub as an admin user
and sets its password to be `<password>`.
Although it is not recommended, it is possible to only set the admin username at this point
and set the admin password after the installation.
Also, the `--admin` flag can be repeated multiple times. For example, to add `admin-user1`
and `admin-user2` as admins when installing, depending if you would like to set their passwords
during install you would:
- set `admin-user1` with password `password-user1` and `admin-user2` with `password-user2` using:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2:password-user2
```
- set `admin-user1` and `admin-user2` to be admins, without any passwords at this stage, using:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1 --admin admin-user2
```
- set `admin-user1` with password `password-user1` and `admin-user2` with no password at this stage using:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2
```
## Installing python packages in the user environment
`--user-requirements-txt-url <url-to-requirements.txt>` installs packages specified
in the `requirements.txt` located at the given URL into the user environment at install
time. This is very useful when you want to set up a hub with a particular user environment
in one go.
For example, to install the latest requirements to run UC Berkeley's data8 course
in your new hub, you would run:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--user-requirements-txt-url https://raw.githubusercontent.com/data-8/materials-sp18/HEAD/requirements.txt
```
The URL **must** point to a working requirements.txt. If there are any errors, the installation
will fail.
:::{note}
When pointing to a file on GitHub, make sure to use the 'Raw' version. It should point to
`raw.githubusercontent.com`, not `github.com`.
:::
## Installing TLJH plugins
The Littlest JupyterHub can install additional _plugins_ that provide additional
features. They are most commonly used to install a particular _stack_ - such as
the [PANGEO Stack](https://github.com/yuvipanda/tljh-pangeo) for earth sciences
research, a stack for a particular class, etc. You can find more information about
writing plugins and a list of existing plugins at {ref}`contributing/plugins`.
`--plugin <plugin-to-install>` installs and activates a plugin. You can pass it
however many times you want. Since plugins are distributed as python packages,
`<plugin-to-install>` can be anything that can be passed to `pip install` -
`plugin-name-on-pypi==<version>` and `git+https://github.com/user/repo@tag`
are the most popular ones. Specifying a version or tag is highly recommended.
For example, to install the PANGEO Plugin version 0.1 (if version 0.1 existed)
in your new TLJH install, you would use:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--plugin git+https://github.com/yuvipanda/tljh-pangeo@v0.1
```
Multiple plugins can be installed at once with: `--plugin <first-plugin-to-install> <second-plugin-to-install>`.
:::{note}
Plugins are extremely powerful and can do a large number of arbitrary things.
Only install plugins you trust.
:::

140
docs/topic/customizing-installer.rst
View File

@@ -1,140 +0,0 @@
.. _topic/customizing-installer:
=========================
Customizing the Installer
=========================
The installer can be customized with commandline parameters. The default installer
is executed as:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
<parameters>
This page documents the various options you can pass as commandline parameters to the installer.
.. _topic/customizing-installer/admin:
Serving a temporary "TLJH is building" page
===========================================
``--show-progress-page`` serves a temporary "TLJH is building" progress page while TLJH is building.
.. image:: ../images/tljh-is-building-page.gif
:alt: Temporary progress page while TLJH is building
* The page will be accessible at ``http://<tljh-public-ip>/index.html`` in your browser.
When TLJH installation is complete, the progress page page will stop and you will be able
to access TLJH as usually at ``http://<tljh-public-ip>``.
* From the progress page, you will also be able to access the installation logs, by clicking the
**Logs** button or by going directly to ``http://<tljh-public-ip>/logs`` in your browser.
To update the logs, refresh the page.
.. note::
The ``http://<tljh-public-ip>/index.html`` page refreshes itself automatically every 30s.
When JupyterHub starts, a JupyterHub 404 HTTP error message (*Jupyter has lots of moons, but this is not one...*)
will be shown instead of the progress page. This means JupyterHub was started succesfully and you can access it
either by clicking the `Control Panel` button or by going to ``http://<tljh-public-ip>/`` directly.
For example, to enable the progress page and add the first *admin* user, you would run:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin --show-progress-page
Adding admin users
===================
``--admin <username>:<password>`` adds user ``<username>`` to JupyterHub as an admin user
and sets its password to be ``<password>``.
Although it is not recommended, it is possible to only set the admin username at this point
and set the admin password after the installation.
Also, the ``--admin`` flag can be repeated multiple times. For example, to add ``admin-user1``
and ``admin-user2`` as admins when installing, depending if you would like to set their passwords
during install you would:
* set ``admin-user1`` with password ``password-user1`` and ``admin-user2`` with ``password-user2`` using:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2:password-user2
* set ``admin-user1`` and ``admin-user2`` to be admins, without any passwords at this stage, using:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1 --admin admin-user2
* set ``admin-user1`` with password ``password-user1`` and ``admin-user2`` with no password at this stage using:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2
Installing python packages in the user environment
==================================================
``--user-requirements-txt-url <url-to-requirements.txt>`` installs packages specified
in the ``requirements.txt`` located at the given URL into the user environment at install
time. This is very useful when you want to set up a hub with a particular user environment
in one go.
For example, to install the latest requirements to run UC Berkeley's data8 course
in your new hub, you would run:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--user-requirements-txt-url https://raw.githubusercontent.com/data-8/materials-sp18/HEAD/requirements.txt
The URL **must** point to a working requirements.txt. If there are any errors, the installation
will fail.
.. note::
When pointing to a file on GitHub, make sure to use the 'Raw' version. It should point to
``raw.githubusercontent.com``, not ``github.com``.
Installing TLJH plugins
=======================
The Littlest JupyterHub can install additional *plugins* that provide additional
features. They are most commonly used to install a particular *stack* - such as
the `PANGEO Stack <https://github.com/yuvipanda/tljh-pangeo>`_ for earth sciences
research, a stack for a particular class, etc. You can find more information about
writing plugins and a list of existing plugins at :ref:`contributing/plugins`.
``--plugin <plugin-to-install>`` installs and activates a plugin. You can pass it
however many times you want. Since plugins are distributed as python packages,
``<plugin-to-install>`` can be anything that can be passed to ``pip install`` -
``plugin-name-on-pypi==<version>`` and ``git+https://github.com/user/repo@tag``
are the most popular ones. Specifying a version or tag is highly recommended.
For example, to install the PANGEO Plugin version 0.1 (if version 0.1 existed)
in your new TLJH install, you would use:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--plugin git+https://github.com/yuvipanda/tljh-pangeo@v0.1
Multiple plugins can be installed at once with: ``--plugin <first-plugin-to-install> <second-plugin-to-install>``.
.. note::
Plugins are extremely powerful and can do a large number of arbitrary things.
Only install plugins you trust.

91
docs/topic/escape-hatch.md Normal file
View File

@@ -0,0 +1,91 @@
(topic-escape-hatch)=
# Custom configuration snippets
The two main TLJH components are **JupyterHub** and **Traefik**.
- JupyterHub takes its configuration from the `jupyterhub_config.py` file.
- Traefik loads its:
- [static configuration](https://docs.traefik.io/v1.7/basics/#static-traefik-configuration)
from the `traefik.toml` file.
- [dynamic configuration](https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration)
from the `rules` directory.
The `jupyterhub_config.py` and `traefik.toml` files are created by TLJH during installation
and can be edited by the user only through `tljh-config`. The `rules` directory is also created
during install along with a `rules/rules.toml` file, to be used by JupyterHub to store the routing
table from users to their notebooks.
:::{note}
Any direct modification to these files is unsupported, and will cause hard to debug issues.
:::
But because sometimes TLJH needs to be customized in ways that are not officially
supported, an escape hatch has been introduced to allow easily extending the
configuration. Please follow the sections below for how to extend JupyterHub's
and Traefik's configuration outside of `tljh-config` scope.
## Extending `jupyterhub_config.py`
The `jupyterhub_config.d` directory lets you load multiple `jupyterhub_config.py`
snippets for your configuration.
- Any files in `/opt/tljh/config/jupyterhub_config.d` that end in `.py` will
be loaded in alphabetical order as python files to provide configuration for
JupyterHub.
- The configuration files can have any name, but they need to have the `.py`
extension and to respect this format.
- Any config that can go in a regular `jupyterhub_config.py` file is valid in
these files.
- They will be loaded _after_ any of the config options specified with `tljh-config`
are loaded.
Once you have created and defined your custom JupyterHub config file/s, just reload the
hub for the new configuration to take effect:
```bash
sudo tljh-config reload hub
```
## Extending `traefik.toml`
The `traefik_config.d` directory lets you load multiple `traefik.toml`
snippets for your configuration.
- Any files in `/opt/tljh/config/traefik_config.d` that end in `.toml` will be
loaded in alphabetical order to provide configuration for Traefik.
- The configuration files can have any name, but they need to have the `.toml`
extension and to respect this format.
- Any config that can go in a regular `traefik.toml` file is valid in these files.
- They will be loaded _after_ any of the config options specified with `tljh-config`
are loaded.
Once you have created and defined your custom Traefik config file/s, just reload the
proxy for the new configuration to take effect:
```bash
sudo tljh-config reload proxy
```
:::{warning}
This instructions might change when TLJH will switch to Traefik > 2.0
:::
## Extending `rules.toml`
`Traefik` is configured to load its routing table from the `/opt/tljh/state/rules`
directory. The existing `rules.toml` file inside this directory is used by
`jupyterhub-traefik-proxy` to add the JupyterHub routes from users to their notebook servers
and shouldn't be modified.
However, the routing table can be extended outside JupyterHub's scope using the `rules`
directory, by adding other dynamic configuration files with the desired routing rules.
:::{note}
Any files in `/opt/tljh/state/rules` that end in `.toml` will be hot reload by Traefik.
This means that there is no need to reload the proxy service for the rules to take effect.
:::
Checkout Traefik' docs about [dynamic configuration](https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration)
and how to provide dynamic configuration through
[multiple separated files](https://docs.traefik.io/v1.7/configuration/backends/file/#multiple-separated-files).

94
docs/topic/escape-hatch.rst
View File

@@ -1,94 +0,0 @@
.. _topic/escape-hatch:
=============================
Custom configuration snippets
=============================
The two main TLJH components are **JupyterHub** and **Traefik**.
* JupyterHub takes its configuration from the ``jupyterhub_config.py`` file.
* Traefik loads its:
* `static configuration <https://docs.traefik.io/v1.7/basics/#static-traefik-configuration>`_
from the ``traefik.toml`` file.
* `dynamic configuration <https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration>`_
from the ``rules`` directory.
The ``jupyterhub_config.py`` and ``traefik.toml`` files are created by TLJH during installation
and can be edited by the user only through ``tljh-config``. The ``rules`` directory is also created
during install along with a ``rules/rules.toml`` file, to be used by JupyterHub to store the routing
table from users to their notebooks.
.. note::
Any direct modification to these files is unsupported, and will cause hard to debug issues.
But because sometimes TLJH needs to be customized in ways that are not officially
supported, an escape hatch has been introduced to allow easily extending the
configuration. Please follow the sections below for how to extend JupyterHub's
and Traefik's configuration outside of ``tljh-config`` scope.
Extending ``jupyterhub_config.py``
==================================
The ``jupyterhub_config.d`` directory lets you load multiple ``jupyterhub_config.py``
snippets for your configuration.
* Any files in ``/opt/tljh/config/jupyterhub_config.d`` that end in ``.py`` will
be loaded in alphabetical order as python files to provide configuration for
JupyterHub.
* The configuration files can have any name, but they need to have the `.py`
extension and to respect this format.
* Any config that can go in a regular ``jupyterhub_config.py`` file is valid in
these files.
* They will be loaded *after* any of the config options specified with ``tljh-config``
are loaded.
Once you have created and defined your custom JupyterHub config file/s, just reload the
hub for the new configuration to take effect:
.. code-block:: bash
sudo tljh-config reload hub
Extending ``traefik.toml``
==========================
The ``traefik_config.d`` directory lets you load multiple ``traefik.toml``
snippets for your configuration.
* Any files in ``/opt/tljh/config/traefik_config.d`` that end in ``.toml`` will be
loaded in alphabetical order to provide configuration for Traefik.
* The configuration files can have any name, but they need to have the `.toml`
extension and to respect this format.
* Any config that can go in a regular ``traefik.toml`` file is valid in these files.
* They will be loaded *after* any of the config options specified with ``tljh-config``
are loaded.
Once you have created and defined your custom Traefik config file/s, just reload the
proxy for the new configuration to take effect:
.. code-block:: bash
sudo tljh-config reload proxy
.. warning:: This instructions might change when TLJH will switch to Traefik > 2.0
Extending ``rules.toml``
========================
``Traefik`` is configured to load its routing table from the ``/opt/tljh/state/rules``
directory. The existing ``rules.toml`` file inside this directory is used by
``jupyterhub-traefik-proxy`` to add the JupyterHub routes from users to their notebook servers
and shouldn't be modified.
However, the routing table can be extended outside JupyterHub's scope using the ``rules``
directory, by adding other dynamic configuration files with the desired routing rules.
.. note::
* Any files in ``/opt/tljh/state/rules`` that end in ``.toml`` will be hot reload by Traefik.
This means that there is no need to reload the proxy service for the rules to take effect.
Checkout Traefik' docs about `dynamic configuration <https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration>`_
and how to provide dynamic configuration through
`multiple separated files <https://docs.traefik.io/v1.7/configuration/backends/file/#multiple-separated-files>`_.

106
docs/topic/idle-culler.rst → docs/topic/idle-culler.md
View File

@@ -1,8 +1,6 @@
.. _topic/idle-culler:
(topic-idle-culler)=
=============================
Culling idle notebook servers
=============================
# Culling idle notebook servers
The idle culler automatically shuts down user notebook servers when they have
not been used for a certain time period, in order to reduce the total resource
@@ -11,109 +9,103 @@ usage on your JupyterHub.
The notebook server monitors activity internally
and notifies JupyterHub of recent activity at certain time intervals (the activity interval).
If JupyterHub has not been notified of any activity after a certain period (the idle timeout),
the server is considered to be *inactive (idle)* and will be culled (shutdown).
the server is considered to be _inactive (idle)_ and will be culled (shutdown).
The `idle culler <https://github.com/jupyterhub/jupyterhub-idle-culler>`_ is a JupyterHub service that is installed and enabled by default in TLJH.
The [idle culler](https://github.com/jupyterhub/jupyterhub-idle-culler) is a JupyterHub service that is installed and enabled by default in TLJH.
It can be configured using tljh-config. For advanced use-cases, like purging old user data,
the idle culler configuration can be extended beyond tljh-config options, using custom
`jupyterhub_config.py snippets <https://tljh.jupyter.org/en/latest/topic/escape-hatch.html?highlight=escape-hatch#extending-jupyterhub-config-py>`__.
[jupyterhub_config.py snippets](https://tljh.jupyter.org/en/latest/topic/escape-hatch.html?highlight=escape-hatch#extending-jupyterhub-config-py).
Default settings
================
## Default settings
By default, JupyterHub will ping the user notebook servers every 60s to check their
status. Every server found to be idle for more than 10 minutes will be culled.
.. code-block:: python
services.cull.every = 60
services.cull.timeout = 600
```python
services.cull.every = 60
services.cull.timeout = 600
```
Because the servers don't have a maximum age set, an active server will not be shut down
regardless of how long it has been up and running.
.. code-block:: python
services.cull.max_age = 0
```python
services.cull.max_age = 0
```
If after the culling process, there are users with no active notebook servers, by default,
the users will not be culled alongside their notebooks and will continue to exist.
.. code-block:: python
```python
services.cull.users = False
```
services.cull.users = False
Configuring the idle culler
===========================
## Configuring the idle culler
The available configuration options are:
Idle timeout
------------
### Idle timeout
The idle timeout is the maximum time (in seconds) a server can be inactive before it
will be culled. The timeout can be configured using:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.timeout <max-idle-sec-before-server-is-culled>
sudo tljh-config reload
```
sudo tljh-config set services.cull.timeout <max-idle-sec-before-server-is-culled>
sudo tljh-config reload
### Idle check interval
Idle check interval
-------------------
The idle check interval represents how frequent (in seconds) the Hub will
check if there are any idle servers to cull. It can be configured using:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.every <number-of-sec-this-check-is-done>
sudo tljh-config reload
```
sudo tljh-config set services.cull.every <number-of-sec-this-check-is-done>
sudo tljh-config reload
### Maximum age
Maximum age
-----------
The maximum age sets the time (in seconds) a server should be running.
The servers that exceed the maximum age, will be culled even if they are active.
A maximum age of 0, will deactivate this option.
The maximum age can be configured using:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.max_age <server-max-age>
sudo tljh-config reload
```
sudo tljh-config set services.cull.max_age <server-max-age>
sudo tljh-config reload
### User culling
User culling
------------
In addition to servers, it is also possible to cull the users. This is usually
suited for temporary-user cases such as *tmpnb*.
suited for temporary-user cases such as _tmpnb_.
User culling can be activated using the following command:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.users True
sudo tljh-config reload
```
sudo tljh-config set services.cull.users True
sudo tljh-config reload
### Concurrency
Concurrency
-----------
Deleting a lot of users at the same time can slow down the Hub.
The number of concurrent requests made to the Hub can be configured using:
.. code-block:: bash
sudo tljh-config set services.cull.concurrency <number-of-concurrent-hub-requests>
sudo tljh-config reload
```bash
sudo tljh-config set services.cull.concurrency <number-of-concurrent-hub-requests>
sudo tljh-config reload
```
Because TLJH it's used for a small number of users, the cases that may require to
modify the concurrency limit should be rare.
Disabling the idle culler
=========================
## Disabling the idle culler
The idle culling service is enabled by default. To disable it, use the following
command:
.. code-block:: bash
sudo tljh-config set services.cull.enabled False
sudo tljh-config reload
```bash
sudo tljh-config set services.cull.enabled False
sudo tljh-config reload
```

19
docs/topic/index.md Normal file
View File

@@ -0,0 +1,19 @@
# Topic Guides
Topic guides provide in-depth explanations of specific topics.
```{toctree}
:caption: Topic guides
:titlesonly: true
whentouse
requirements
security
customizing-installer
installer-actions
tljh-config
authenticator-configuration
escape-hatch
idle-culler
jupyterhub-configurator
```

20
docs/topic/index.rst
View File

@@ -1,20 +0,0 @@
============
Topic Guides
============
Topic guides provide in-depth explanations of specific topics.
.. toctree::
:titlesonly:
:caption: Topic guides
whentouse
requirements
security
customizing-installer
installer-actions
tljh-config
authenticator-configuration
escape-hatch
idle-culler
jupyterhub-configurator

218
docs/topic/installer-actions.md Normal file
View File

@@ -0,0 +1,218 @@
(topic-installer-actions)=
# What does the installer do?
This document details what exactly the installer does to the machine it is
run on.
## `apt` Packages installed
The packages `python3` and `python3-venv` are installed from the apt repositories.
## Hub environment
JupyterHub is run from a python3 virtual environment located in `/opt/tljh/hub`. It
uses the system's installed python and is owned by root. It also contains a binary install
of [traefik](http://traefik.io/). This virtual environment is completely managed by TLJH.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/hub
```
:::
## User environment
By default, a `mambaforge` conda environment is installed in `/opt/tljh/user`. This contains
the notebook interface used to launch all users, and the various packages available to all
users. The environment is owned by the `root` user. JupyterHub admins may use
to `sudo -E conda install` or `sudo -E pip install` packages into this environment.
This conda environment is added to `$PATH` for all users started with JupyterHub. If you
are using `ssh` instead, you can activate this environment by running the following:
```bash
source /opt/tljh/user/bin/activate
```
This should let you run various `conda` and `pip` commands. If you run into errors like
`Command 'conda' not found`, try prefixing your command with:
```bash
sudo env PATH=${PATH} <command>
```
By default, `sudo` does not respect any custom environments you have activated. The `env PATH=${PATH}`
'fixes' that.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/user
```
:::
## `tljh-config` symlink
We create a symlink from `/usr/bin/tljh-config` to `/opt/tljh/hub/bin/tljh-config`, so users
can run `sudo tljh-config <something>` from their terminal. While the user environment is added
to users' `$PATH` when they launch through JupyterHub, the hub environment is not. This makes it
hard to access the `tljh-config` command used to change most config parameters. Hence we symlink the
`tljh-config` command to `/usr/bin`, so it is directly accessible with `sudo tljh-config <command>`.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo unlink /usr/bin/tljh-config
```
:::
## `jupyterhub_config.d` directory for custom configuration snippets
Any files in /opt/tljh/config/jupyterhub_config.d that end in .py and are a valid
JupyterHub configuration will be loaded after any of the config options specified
with tljh-config are loaded.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/config
```
:::
## Systemd Units
TLJH places 2 systemd units on your computer. They all start on system startup.
1. `jupyterhub.service` - starts the JupyterHub service.
2. `traefik.service` - starts traefik proxy that manages HTTPS
In addition, each running Jupyter user gets their own systemd unit of the name `jupyter-<username>`.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
# stop the services
systemctl stop jupyterhub.service
systemctl stop traefik.service
systemctl stop jupyter-<username>
# disable the services
systemctl disable jupyterhub.service
systemctl disable traefik.service
# run this command for all the Jupyter users
systemctl disable jupyter-<username>
# remove the systemd unit
rm /etc/systemd/system/jupyterhub.service
rm /etc/systemd/system/traefik.service
# reset the state of all units
systemctl daemon-reload
systemctl reset-failed
```
:::
## State files
TLJH places 3 `jupyterhub.service` and 4 `traefik.service` state files in `/opt/tljh/state`.
These files save the state of JupyterHub and Traefik services and are meant
to be used and modified solely by these services.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/state
```
:::
## Progress page files
If you ran the TLJH installer with the `--show-progress-page` flag, then two files have been
added to your system to help serving the progress page:
- `/var/run/index.html` - the main progress page
- `/var/run/favicon.ico` - the JupyterHub icon
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm /var/run/index.html
sudo rm /var/run/favicon.ico
```
:::
## User groups
TLJH creates two user groups when installed:
1. `jupyterhub-users` contains all users managed by this JupyterHub
2. `jupyterhub-admins` contains all users with admin rights managed by this JupyterHub.
When a new JupyterHub user logs in, a unix user is created for them. The unix user is always added
to the `jupyterhub-users` group. If the user is an admin, they are added to the `jupyterhub-admins`
group whenever they start / stop their notebook server.
If you uninstall TLJH, you should probably remove all user accounts associated with both these
user groups, and then remove the groups themselves. You might have to archive or delete the home
directories of these users under `/home/`.
:::{note}
If you try to remove TLJH, in order to remove a user and its home directory, use:
```bash
sudo userdel -r <user>
```
:::
Keep in mind that the files located in other parts of the file system
will have to be searched for and deleted manually.
:::{note}
To remove the user groups units:
```bash
sudo delgroup jupyterhub-users
sudo delgroup jupyterhub-admins
# remove jupyterhub-admins from the sudoers group
sudo rm /etc/sudoers.d/jupyterhub-admins
```
:::
## Passwordless `sudo` for JupyterHub admins
`/etc/sudoers.d/jupyterhub-admins` is created to provide passwordless sudo for all JupyterHub
admins. We also set it up to inherit `$PATH` with `sudo -E`, to more easily call `conda`,
`pip`, etc.
## Removing TLJH
If trying to wipe out a fresh TLJH installation, follow the instructions on how to revert
each specific modification the TLJH installer does to the system.
:::{note}
If using a VM, the recommended way to remove TLJH is destroying the VM and start fresh.
:::
:::{warning}
Completely uninstalling TLJH after it has been used is a difficult task because it's
highly coupled to how the system changed after it has been used and modified by the users.
Thus, we cannot provide instructions on how to proceed in this case.
:::

214
docs/topic/installer-actions.rst
View File

@@ -1,214 +0,0 @@
.. _topic/installer-actions:
===========================
What does the installer do?
===========================
This document details what exactly the installer does to the machine it is
run on.
``apt`` Packages installed
==========================
The packages ``python3`` and ``python3-venv`` are installed from the apt repositories.
Hub environment
===============
JupyterHub is run from a python3 virtual environment located in ``/opt/tljh/hub``. It
uses the system's installed python and is owned by root. It also contains a binary install
of `traefik <http://traefik.io/>`_. This virtual environment is completely managed by TLJH.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/hub
User environment
================
By default, a ``mambaforge`` conda environment is installed in ``/opt/tljh/user``. This contains
the notebook interface used to launch all users, and the various packages available to all
users. The environment is owned by the ``root`` user. JupyterHub admins may use
to ``sudo -E conda install`` or ``sudo -E pip install`` packages into this environment.
This conda environment is added to ``$PATH`` for all users started with JupyterHub. If you
are using ``ssh`` instead, you can activate this environment by running the following:
.. code-block:: bash
source /opt/tljh/user/bin/activate
This should let you run various ``conda`` and ``pip`` commands. If you run into errors like
``Command 'conda' not found``, try prefixing your command with:
.. code-block:: bash
sudo env PATH=${PATH} <command>
By default, ``sudo`` does not respect any custom environments you have activated. The ``env PATH=${PATH}``
'fixes' that.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/user
``tljh-config`` symlink
========================
We create a symlink from ``/usr/bin/tljh-config`` to ``/opt/tljh/hub/bin/tljh-config``, so users
can run ``sudo tljh-config <something>`` from their terminal. While the user environment is added
to users' ``$PATH`` when they launch through JupyterHub, the hub environment is not. This makes it
hard to access the ``tljh-config`` command used to change most config parameters. Hence we symlink the
``tljh-config`` command to ``/usr/bin``, so it is directly accessible with ``sudo tljh-config <command>``.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo unlink /usr/bin/tljh-config
``jupyterhub_config.d`` directory for custom configuration snippets
===================================================================
Any files in /opt/tljh/config/jupyterhub_config.d that end in .py and are a valid
JupyterHub configuration will be loaded after any of the config options specified
with tljh-config are loaded.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/config
Systemd Units
=============
TLJH places 2 systemd units on your computer. They all start on system startup.
#. ``jupyterhub.service`` - starts the JupyterHub service.
#. ``traefik.service`` - starts traefik proxy that manages HTTPS
In addition, each running Jupyter user gets their own systemd unit of the name ``jupyter-<username>``.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
# stop the services
systemctl stop jupyterhub.service
systemctl stop traefik.service
systemctl stop jupyter-<username>
# disable the services
systemctl disable jupyterhub.service
systemctl disable traefik.service
# run this command for all the Jupyter users
systemctl disable jupyter-<username>
# remove the systemd unit
rm /etc/systemd/system/jupyterhub.service
rm /etc/systemd/system/traefik.service
# reset the state of all units
systemctl daemon-reload
systemctl reset-failed
State files
===========
TLJH places 3 `jupyterhub.service` and 4 `traefik.service` state files in `/opt/tljh/state`.
These files save the state of JupyterHub and Traefik services and are meant
to be used and modified solely by these services.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/state
Progress page files
===================
If you ran the TLJH installer with the `--show-progress-page` flag, then two files have been
added to your system to help serving the progress page:
* ``/var/run/index.html`` - the main progress page
* ``/var/run/favicon.ico`` - the JupyterHub icon
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm /var/run/index.html
sudo rm /var/run/favicon.ico
User groups
===========
TLJH creates two user groups when installed:
#. ``jupyterhub-users`` contains all users managed by this JupyterHub
#. ``jupyterhub-admins`` contains all users with admin rights managed by this JupyterHub.
When a new JupyterHub user logs in, a unix user is created for them. The unix user is always added
to the ``jupyterhub-users`` group. If the user is an admin, they are added to the ``jupyterhub-admins``
group whenever they start / stop their notebook server.
If you uninstall TLJH, you should probably remove all user accounts associated with both these
user groups, and then remove the groups themselves. You might have to archive or delete the home
directories of these users under ``/home/``.
.. note::
If you try to remove TLJH, in order to remove a user and its home directory, use:
.. code-block:: bash
sudo userdel -r <user>
Keep in mind that the files located in other parts of the file system
will have to be searched for and deleted manually.
.. note::
To remove the user groups units:
.. code-block:: bash
sudo delgroup jupyterhub-users
sudo delgroup jupyterhub-admins
# remove jupyterhub-admins from the sudoers group
sudo rm /etc/sudoers.d/jupyterhub-admins
Passwordless ``sudo`` for JupyterHub admins
============================================
``/etc/sudoers.d/jupyterhub-admins`` is created to provide passwordless sudo for all JupyterHub
admins. We also set it up to inherit ``$PATH`` with ``sudo -E``, to more easily call ``conda``,
``pip``, etc.
Removing TLJH
=============
If trying to wipe out a fresh TLJH installation, follow the instructions on how to revert
each specific modification the TLJH installer does to the system.
.. note::
If using a VM, the recommended way to remove TLJH is destroying the VM and start fresh.
.. warning::
Completely uninstalling TLJH after it has been used is a difficult task because it's
highly coupled to how the system changed after it has been used and modified by the users.
Thus, we cannot provide instructions on how to proceed in this case.

21
docs/topic/jupyterhub-configurator.md Normal file
View File

@@ -0,0 +1,21 @@
(topic-jupyterhub-configurator)=
# JupyterHub Configurator
The [JupyterHub configurator](https://github.com/yuvipanda/jupyterhub-configurator) allows admins to change a subset of hub settings via a GUI.
## Enabling the configurator
Because the configurator is under continue development and it might change over time, it is disabled by default in TLJH.
If you want to experiment with it, it can be enabled using `tljh-config`:
```bash
sudo tljh-config set services.configurator.enabled True
sudo tljh-config reload
```
## Accessing the Configurator
After enabling the configurator using `tljh-config`, the service will only be available to hub admins, from within the control panel.
The configurator can be accessed from under `Services` in the top navigation bar. It will ask to authenticate, so it knows the user is an admin.
Once done, the configurator interface will be available.

25
docs/topic/jupyterhub-configurator.rst
View File

@@ -1,25 +0,0 @@
.. _topic/jupyterhub-configurator:
=======================
JupyterHub Configurator
=======================
The `JupyterHub configurator <https://github.com/yuvipanda/jupyterhub-configurator>`_ allows admins to change a subset of hub settings via a GUI.
Enabling the configurator
=========================
Because the configurator is under continue development and it might change over time, it is disabled by default in TLJH.
If you want to experiment with it, it can be enabled using ``tljh-config``:
.. code-block:: bash
sudo tljh-config set services.configurator.enabled True
sudo tljh-config reload
Accessing the Configurator
==========================
After enabling the configurator using ``tljh-config``, the service will only be available to hub admins, from within the control panel.
The configurator can be accessed from under ``Services`` in the top navigation bar. It will ask to authenticate, so it knows the user is an admin.
Once done, the configurator interface will be available.

23
docs/topic/requirements.md Normal file
View File

@@ -0,0 +1,23 @@
(requirements)=
# Server Requirements
## Operating System
We require using Ubuntu >=20.04 as the base operating system for your server.
## Root access
Full `root` access to this server is required. This might be via `sudo`
(recommended) or by direct access to `root` (not recommended!)
## External IP
An external IP allows users on the internet to reach your JupyterHub. Most
VPS / Cloud providers give you a public IP address along with your server. If
you are hosting on a physical machine somewhere, talk to your system administrators
about how to get HTTP traffic from the world into your server.
## CPU / Memory / Disk Space
See how to {ref}`howto/admin/resource-estimation`

29
docs/topic/requirements.rst
View File

@@ -1,29 +0,0 @@
.. _requirements:
===================
Server Requirements
===================
Operating System
================
We require using Ubuntu >=20.04 as the base operating system for your server.
Root access
===========
Full ``root`` access to this server is required. This might be via ``sudo``
(recommended) or by direct access to ``root`` (not recommended!)
External IP
===========
An external IP allows users on the internet to reach your JupyterHub. Most
VPS / Cloud providers give you a public IP address along with your server. If
you are hosting on a physical machine somewhere, talk to your system administrators
about how to get HTTP traffic from the world into your server.
CPU / Memory / Disk Space
=========================
See how to :ref:`howto/admin/resource-estimation`

61
docs/topic/security.rst → docs/topic/security.md
View File

@@ -1,80 +1,69 @@
=======================
Security Considerations
=======================
# Security Considerations
The Littlest JupyterHub is in beta state & should not be used in security
critical situations. We will try to keep things as secure as possible, but
sometimes trade security for massive gains in convenience. This page contains
information about the security model of The Littlest JupyterHub.
System user accounts
====================
## System user accounts
Each JupyterHub user gets their own Unix user account created when they
first start their server. This protects users from each other, gives them a
home directory at a well known location, and allows sharing based on file system
permissions.
#. The unix user account created for a JupyterHub user named ``<username>`` is
``jupyter-<username>``. This prefix helps prevent clashes with users that
already exist - otherwise a user named ``root`` can trivially gain full root
access to your server. If the username (including the ``jupyter-`` prefix)
1. The unix user account created for a JupyterHub user named `<username>` is
`jupyter-<username>`. This prefix helps prevent clashes with users that
already exist - otherwise a user named `root` can trivially gain full root
access to your server. If the username (including the `jupyter-` prefix)
is longer than 26 characters, it is truncated at 26 characters & a 5 charcter
hash is appeneded to it. This keeps usernames under the linux username limit
of 32 characters while also reducing chances of collision.
#. A home directory is created for the user under ``/home/jupyter-<username>``.
#. The default permission of the home directory is change with ``o-rwx`` (remove
2. A home directory is created for the user under `/home/jupyter-<username>`.
3. The default permission of the home directory is change with `o-rwx` (remove
non-group members the ability to read, write or list files and folders in the
Home directory).
#. No password is set for this unix system user by default. The password used
4. No password is set for this unix system user by default. The password used
to log in to JupyterHub (if using an authenticator that requires a password)
is not related to the unix user's password in any form.
5. All users created by The Littlest JupyterHub are added to the user group
`jupyterhub-users`.
#. All users created by The Littlest JupyterHub are added to the user group
``jupyterhub-users``.
## `sudo` access for admins
``sudo`` access for admins
==========================
JupyterHub admin users are added to the user group ``jupyterhub-admins``,
which is granted complete root access to the whole server with the ``sudo``
JupyterHub admin users are added to the user group `jupyterhub-admins`,
which is granted complete root access to the whole server with the `sudo`
command on the terminal. No password required.
This is a **lot** of power, and they can do pretty much anything they want to
the server - look at other people's work, modify it, break the server in cool &
funky ways, etc. This also means **if an admin's credentials are compromised
funky ways, etc. This also means **if an admin's credentials are compromised
(easy to guess password, password re-use, etc) the entire JupyterHub is compromised.**
Off-boarding users securely
===========================
## Off-boarding users securely
When you delete users from the JupyterHub admin console, their unix user accounts
are **not** removed. This means they might continue to have access to the server
even after you remove them from JupyterHub. Admins should manually remove the user
from the server & archive their home directories as needed. For example, the
following command deletes the unix user associated with the JupyterHub user ``yuvipanda``.
following command deletes the unix user associated with the JupyterHub user `yuvipanda`.
.. code-block:: bash
sudo userdel jupyter-yuvipanda
```bash
sudo userdel jupyter-yuvipanda
```
If the user removed from the server is an admin, extra care must be taken
since they could have modified the system earlier to continue giving them
access.
Per-user ``/tmp``
=================
## Per-user `/tmp`
``/tmp`` is shared by all users in most computing systems, and this has been
`/tmp` is shared by all users in most computing systems, and this has been
a consistent source of security issues. The Littlest JupyterHub gives each
user their own ephemeral ``/tmp`` using the `PrivateTmp <https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateTmp>`_
user their own ephemeral `/tmp` using the [PrivateTmp](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateTmp)
feature of systemd.
HTTPS
=====
## HTTPS
Any internet-facing JupyterHub should use HTTPS to secure its traffic. For
information on how to use HTTPS with your JupyterHub, see :ref:`howto/admin/https`.
information on how to use HTTPS with your JupyterHub, see {ref}`howto/admin/https`.

246
docs/topic/tljh-config.md Normal file
View File

@@ -0,0 +1,246 @@
(topic-tljh-config)=
# Configuring TLJH with `tljh-config`
`tljh-config` is the commandline program used to make configuration
changes to TLJH.
## Running `tljh-config`
You can run `tljh-config` in two ways:
1. From inside a terminal in JupyterHub while logged in as an admin user.
This method is recommended.
2. By directly calling `/opt/tljh/hub/bin/tljh-config` as root when
logged in to the server via other means (such as SSH). This is an
advanced use case, and not covered much in this guide.
(tljh-set)=
## Set / Unset a configuration property
TLJH's configuration is organized in a nested tree structure. You can
set a particular property with the following command:
```bash
sudo tljh-config set <property-path> <value>
```
where:
1. `<property-path>` is a dot-separated path to the property you want
to set.
2. `<value>` is the value you want to set the property to.
For example, to set the password for the DummyAuthenticator, you
need to set the `auth.DummyAuthenticator.password` property. You would
do so with the following:
```bash
sudo tljh-config set auth.DummyAuthenticator.password mypassword
```
This can only set string and numerical properties, not lists.
To unset a configuration property you can use the following command:
```bash
sudo tljh-config unset <property-path>
```
Unsetting a configuration property removes the property from the configuration
file. If what you want is only to change the property's value, you should use
`set` and overwrite it with the desired value.
Some of the existing `<property-path>` are listed below by categories:
(tljh-base-url)=
### Base URL
> Use `base_url` to determine the base URL used by JupyterHub. This parameter will
> be passed straight to `c.JupyterHub.base_url`.
(tljh-set-auth)=
### Authentication
> Use `auth.type` to determine authenticator to use. All parameters
> in the config under `auth.{auth.type}` will be passed straight to the
> authenticators themselves.
(tljh-set-ports)=
### Ports
> Use `http.port` and `https.port` to set the ports that TLJH will listen on,
> which are 80 and 443 by default. However, if you change these, note that
> TLJH does a lot of other things to the system (with user accounts and sudo
> rules primarily) that might break security assumptions your other
> applications have, so use with extreme caution.
>
> ```bash
> sudo tljh-config set http.port 8080
> sudo tljh-config set https.port 8443
> sudo tljh-config reload proxy
> ```
(tljh-set-user-lists)=
### User Lists
- `users.allowed` takes in usernames to whitelist
- `users.banned` takes in usernames to blacklist
- `users.admin` takes in usernames to designate as admins
```bash
sudo tljh-config add-item users.allowed good-user_1
sudo tljh-config add-item users.allowed good-user_2
sudo tljh-config add-item users.banned bad-user_6
sudo tljh-config add-item users.admin admin-user_0
sudo tljh-config remove-item users.allowed good-user_2
```
(tljh-set-user-limits)=
### User Server Limits
- `limits.memory` Specifies the maximum memory that can be used by each
individual user. By default there is no memory limit. The limit can be
specified as an absolute byte value. You can use
the suffixes K, M, G or T to mean Kilobyte, Megabyte, Gigabyte or Terabyte
respectively. Setting it to `None` disables memory limits.
```bash
sudo tljh-config set limits.memory 4G
```
Even if you want individual users to use as much memory as possible,
it is still good practice to set a memory limit of 80-90% of total
physical memory. This prevents one user from being able to single
handedly take down the machine accidentally by OOMing it.
- `limits.cpu` A float representing the total CPU-cores each user can use.
By default there is no CPU limit.
1 represents one full CPU, 4 represents 4 full CPUs, 0.5 represents
half of one CPU, etc. This value is ultimately converted to a percentage and
rounded down to the nearest integer percentage,
i.e. 1.5 is converted to 150%, 0.125 is converted to 12%, etc.
Setting it to `None` disables CPU limits.
```bash
sudo tljh-config set limits.cpu 2
```
(tljh-set-user-env)=
### User Environment
> `user_environment.default_app` Set default application users are
> launched into. Currently can be set to the following values
> `jupyterlab` or `nteract`
>
> ```bash
> sudo tljh-config set user_environment.default_app jupyterlab
> ```
(tljh-set-extra-user-groups)=
## Extra User Groups
`users.extra_user_groups` is a configuration option that can be used
to automatically add a user to a specific group. By default, there are
no extra groups defined.
Users can be "paired" with the desired, **existing** groups using:
- `tljh-config set`, if only one user is to be added to the
desired group:
```bash
tljh-config set users.extra_user_groups.group1 user1
```
- `tljh-config add-item`, if multiple users are to be added to
the group:
```bash
tljh-config add-item users.extra_user_groups.group1 user1
tljh-config add-item users.extra_user_groups.group1 user2
```
(tljh-view-conf)=
## View current configuration
To see the current configuration, you can run the following command:
```bash
sudo tljh-config show
```
This will print the current configuration of your TLJH. This is very
useful when asking for support!
(tljh-reload-hub)=
## Reloading JupyterHub to apply configuration
After modifying the configuration, you need to reload JupyterHub for
it to take effect. You can do so with:
```bash
sudo tljh-config reload
```
This should not affect any running users. The JupyterHub will be
restarted and loaded with the new configuration.
(tljh-edit-yaml)=
## Advanced: `config.yaml`
`tljh-config` is a simple program that modifies the contents of the
`config.yaml` file located at `/opt/tljh/config/config.yaml`. `tljh-config`
is the recommended method of editing / viewing configuration since editing
YAML by hand in a terminal text editor is a large source of errors.
To learn more about the `tljh-config` usage, you can use the `--help` flag.
The `--help` flag can be used either directly, to get information about the
general usage of the command or after a positional argument. For example, using
it after an argument like `remove-item` gives information about this specific command.
```bash
sudo tljh-config --help
usage: tljh-config [-h] [--config-path CONFIG_PATH] {show,unset,set,add-item,remove-item,reload} ...
positional arguments:
{show,unset,set,add-item,remove-item,reload}
show Show current configuration
unset Unset a configuration property
set Set a configuration property
add-item Add a value to a list for a configuration property
remove-item Remove a value from a list for a configuration property
reload Reload a component to apply configuration change
optional arguments:
-h, --help show this help message and exit
--config-path CONFIG_PATH
Path to TLJH config.yaml file
```
```bash
sudo tljh-config remove-item --help
usage: tljh-config remove-item [-h] key_path value
positional arguments:
key_path Dot separated path to configuration key to remove value from
value Value to remove from key_path
optional arguments:
-h, --help show this help message and exit
```

271
docs/topic/tljh-config.rst
View File

@@ -1,271 +0,0 @@
.. _topic/tljh-config:
=====================================
Configuring TLJH with ``tljh-config``
=====================================
``tljh-config`` is the commandline program used to make configuration
changes to TLJH.
Running ``tljh-config``
=======================
You can run ``tljh-config`` in two ways:
#. From inside a terminal in JupyterHub while logged in as an admin user.
This method is recommended.
#. By directly calling ``/opt/tljh/hub/bin/tljh-config`` as root when
logged in to the server via other means (such as SSH). This is an
advanced use case, and not covered much in this guide.
.. _tljh-set:
Set / Unset a configuration property
====================================
TLJH's configuration is organized in a nested tree structure. You can
set a particular property with the following command:
.. code-block:: bash
sudo tljh-config set <property-path> <value>
where:
#. ``<property-path>`` is a dot-separated path to the property you want
to set.
#. ``<value>`` is the value you want to set the property to.
For example, to set the password for the DummyAuthenticator, you
need to set the ``auth.DummyAuthenticator.password`` property. You would
do so with the following:
.. code-block:: bash
sudo tljh-config set auth.DummyAuthenticator.password mypassword
This can only set string and numerical properties, not lists.
To unset a configuration property you can use the following command:
.. code-block:: bash
sudo tljh-config unset <property-path>
Unsetting a configuration property removes the property from the configuration
file. If what you want is only to change the property's value, you should use
``set`` and overwrite it with the desired value.
Some of the existing ``<property-path>`` are listed below by categories:
.. _tljh-base_url:
Base URL
--------
Use ``base_url`` to determine the base URL used by JupyterHub. This parameter will
be passed straight to ``c.JupyterHub.base_url``.
.. _tljh-set-auth:
Authentication
--------------
Use ``auth.type`` to determine authenticator to use. All parameters
in the config under ``auth.{auth.type}`` will be passed straight to the
authenticators themselves.
.. _tljh-set-ports:
Ports
-----
Use ``http.port`` and ``https.port`` to set the ports that TLJH will listen on,
which are 80 and 443 by default. However, if you change these, note that
TLJH does a lot of other things to the system (with user accounts and sudo
rules primarily) that might break security assumptions your other
applications have, so use with extreme caution.
.. code-block:: bash
sudo tljh-config set http.port 8080
sudo tljh-config set https.port 8443
sudo tljh-config reload proxy
.. _tljh-set-user-lists:
User Lists
----------
* ``users.allowed`` takes in usernames to whitelist
* ``users.banned`` takes in usernames to blacklist
* ``users.admin`` takes in usernames to designate as admins
.. code-block:: bash
sudo tljh-config add-item users.allowed good-user_1
sudo tljh-config add-item users.allowed good-user_2
sudo tljh-config add-item users.banned bad-user_6
sudo tljh-config add-item users.admin admin-user_0
sudo tljh-config remove-item users.allowed good-user_2
.. _tljh-set-user-limits:
User Server Limits
------------------
* ``limits.memory`` Specifies the maximum memory that can be used by each
individual user. By default there is no memory limit. The limit can be
specified as an absolute byte value. You can use
the suffixes K, M, G or T to mean Kilobyte, Megabyte, Gigabyte or Terabyte
respectively. Setting it to ``None`` disables memory limits.
.. code-block:: bash
sudo tljh-config set limits.memory 4G
Even if you want individual users to use as much memory as possible,
it is still good practice to set a memory limit of 80-90% of total
physical memory. This prevents one user from being able to single
handedly take down the machine accidentally by OOMing it.
* ``limits.cpu`` A float representing the total CPU-cores each user can use.
By default there is no CPU limit.
1 represents one full CPU, 4 represents 4 full CPUs, 0.5 represents
half of one CPU, etc. This value is ultimately converted to a percentage and
rounded down to the nearest integer percentage,
i.e. 1.5 is converted to 150%, 0.125 is converted to 12%, etc.
Setting it to ``None`` disables CPU limits.
.. code-block:: bash
sudo tljh-config set limits.cpu 2
.. _tljh-set-user-env:
User Environment
----------------
``user_environment.default_app`` Set default application users are
launched into. Currently can be set to the following values
``jupyterlab`` or ``nteract``
.. code-block:: bash
sudo tljh-config set user_environment.default_app jupyterlab
.. _tljh-set-extra-user-groups:
Extra User Groups
=================
``users.extra_user_groups`` is a configuration option that can be used
to automatically add a user to a specific group. By default, there are
no extra groups defined.
Users can be "paired" with the desired, **existing** groups using:
* ``tljh-config set``, if only one user is to be added to the
desired group:
.. code-block:: bash
tljh-config set users.extra_user_groups.group1 user1
* ``tljh-config add-item``, if multiple users are to be added to
the group:
.. code-block:: bash
tljh-config add-item users.extra_user_groups.group1 user1
tljh-config add-item users.extra_user_groups.group1 user2
.. _tljh-view-conf:
View current configuration
==========================
To see the current configuration, you can run the following command:
.. code-block:: bash
sudo tljh-config show
This will print the current configuration of your TLJH. This is very
useful when asking for support!
.. _tljh-reload-hub:
Reloading JupyterHub to apply configuration
===========================================
After modifying the configuration, you need to reload JupyterHub for
it to take effect. You can do so with:
.. code-block:: bash
sudo tljh-config reload
This should not affect any running users. The JupyterHub will be
restarted and loaded with the new configuration.
.. _tljh-edit-yaml:
Advanced: ``config.yaml``
=========================
``tljh-config`` is a simple program that modifies the contents of the
``config.yaml`` file located at ``/opt/tljh/config/config.yaml``. ``tljh-config``
is the recommended method of editing / viewing configuration since editing
YAML by hand in a terminal text editor is a large source of errors.
To learn more about the ``tljh-config`` usage, you can use the ``--help`` flag.
The ``--help`` flag can be used either directly, to get information about the
general usage of the command or after a positional argument. For example, using
it after an argument like ``remove-item`` gives information about this specific command.
.. code-block:: bash
sudo tljh-config --help
usage: tljh-config [-h] [--config-path CONFIG_PATH] {show,unset,set,add-item,remove-item,reload} ...
positional arguments:
{show,unset,set,add-item,remove-item,reload}
show Show current configuration
unset Unset a configuration property
set Set a configuration property
add-item Add a value to a list for a configuration property
remove-item Remove a value from a list for a configuration property
reload Reload a component to apply configuration change
optional arguments:
-h, --help show this help message and exit
--config-path CONFIG_PATH
Path to TLJH config.yaml file
.. code-block:: bash
sudo tljh-config remove-item --help
usage: tljh-config remove-item [-h] key_path value
positional arguments:
key_path Dot separated path to configuration key to remove value from
value Value to remove from key_path
optional arguments:
-h, --help show this help message and exit

26
docs/topic/whentouse.rst → docs/topic/whentouse.md
View File

@@ -1,34 +1,32 @@
.. _topic/whentouse:
(topic-whentouse)=
===================================
When to use The Littlest JupyterHub
===================================
# When to use The Littlest JupyterHub
This page is a brief guide to determining whether to use The Littlest JupyterHub
(TLJH) or `Zero to JupyterHub for Kubernetes <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_ (Z2JH).
(TLJH) or [Zero to JupyterHub for Kubernetes](https://zero-to-jupyterhub.readthedocs.io/en/latest/) (Z2JH).
Many of these ideas were first laid out in a
`blog post announcing TLJH <http://words.yuvi.in/post/the-littlest-jupyterhub/>`_.
[blog post announcing TLJH](http://words.yuvi.in/post/the-littlest-jupyterhub/).
`**The Littlest JupyterHub (TLJH)** <https://the-littlest-jupyterhub.readthedocs.io/en/latest/>`_ is an opinionated and pre-configured distribution
[\*\*The Littlest JupyterHub (TLJH)\*\*](https://the-littlest-jupyterhub.readthedocs.io/en/latest/) is an opinionated and pre-configured distribution
to deploy a JupyterHub on a **single machine** (in the cloud or on your own hardware).
It is designed to be a more lightweight and maintainable solution
for use-cases where size, scalability, and cost-savings are not a huge concern.
`**Zero to JupyterHub on Kubernetes** <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_ allows you
[\*\*Zero to JupyterHub on Kubernetes\*\*](https://zero-to-jupyterhub.readthedocs.io/en/latest/) allows you
to deploy JupyterHub on **Kubernetes**. This allows JupyterHub to scale to many thousands
of users, to flexibly grow/shrink the size of resources it needs, and to use
container technology in administering user sessions.
When to use TLJH vs. Z2JH
=========================
## When to use TLJH vs. Z2JH
The choice between TLJH and Z2JH ultimately comes down to only a few questions:
1. Do you want your hub and all users to live on a **single, larger machine** vs. spreading users on a **cluster of smaller machines** that are scaled up or down?
* If you can use a single machine, we recommend **The Littlest JupyterHub**.
* If you wish to use multiple machines, we recommend **Zero to JupyterHub for Kubernetes**.
- If you can use a single machine, we recommend **The Littlest JupyterHub**.
- If you wish to use multiple machines, we recommend **Zero to JupyterHub for Kubernetes**.
2. Do you **need to use container technology**?
* If no, we recommend **The Littlest JupyterHub**.
* If yes, we recommend **Zero to JupyterHub for Kubernetes**.
- If no, we recommend **The Littlest JupyterHub**.
- If yes, we recommend **Zero to JupyterHub for Kubernetes**.