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

Document traefik config escape hatch

Browse Source
This commit is contained in:
GeorgianaElena
2020-06-05 15:03:02 +03:00
parent acc1eea251
commit 6409e29fa8
1 changed files with 61 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,17 +1,65 @@
.. _topic/escape-hatch:
========================================
Custom ``jupyterhub_config.py`` snippets
========================================
Sometimes you need to customize TLJH in ways that are not officially supported.
We provide an easy escape hatch for those cases with a ``jupyterhub_conf.d``
directory that lets you load multiple ``jupyterhub_config.py`` snippets for
your configuration. You need to create the directory when you use it for
the first time.
=============================
Custom configuration snippets
=============================
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. 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.
The two main TLJH components are **JupyterHub** and **Traefik**.
* JupyterHub takes its configuration from the ``jupyterhub_config.py`` file.
* Traefik takes its configuration from the ``traefik.toml`` file.
These files are created by TLJH during installation and can be edited by the
user only through ``tljh-config``, so any direct modification to these files,
will be overwritten by TLJH when the components are reloaded.
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