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

Add docs

Browse Source
This commit is contained in:
GeorgianaElena
2020-06-21 13:09:50 +03:00
parent b368b9716d
commit 3527517165
1 changed files with 31 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -8,11 +8,19 @@ Custom configuration snippets
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.
* 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.
These files are created by TLJH during installation and can be edited by the
user only through ``tljh-config``. Any direct modification to these files
is unsupported, and will cause hard to debug issues.
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
@@ -65,3 +73,22 @@ proxy for the new configuration to take effect:
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>`_.