From 6409e29fa8bc1602f3f68b05e2cbd95d6a58890f Mon Sep 17 00:00:00 2001 From: GeorgianaElena Date: Fri, 5 Jun 2020 15:03:02 +0300 Subject: [PATCH] Document traefik config escape hatch --- docs/topic/escape-hatch.rst | 74 ++++++++++++++++++++++++++++++------- 1 file changed, 61 insertions(+), 13 deletions(-) diff --git a/docs/topic/escape-hatch.rst b/docs/topic/escape-hatch.rst index d6beea0..608003d 100644 --- a/docs/topic/escape-hatch.rst +++ b/docs/topic/escape-hatch.rst @@ -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