Using traefik-proxy with TOML configuration files¶

jupyterhub-traefik-proxy can be used with simple toml configuration files, for smaller, single-node deployments such as The Littlest JupyterHub.

How-To install TraefikTomlProxy¶

Install jupyterhub
Install jupyterhub-traefik-proxy
Install traefik

You can find the full installation guide and examples in the Introduction section

How-To enable TraefikTomlProxy¶

You can enable JupyterHub to work with TraefikTomlProxy in jupyterhub_config.py, using the proxy_class configuration option.

You can choose to:

use the traefik_toml entrypoint, new in JupyterHub 1.0, e.g.:
```
c.JupyterHub.proxy_class = "traefik_toml"
```

use the TraefikTomlProxy object, in which case, you have to import the module, e.g.:

from jupyterhub_traefik_proxy import TraefikTomlProxy
c.JupyterHub.proxy_class = TraefikTomlProxy

Traefik configuration¶

Traefik’s configuration is divided into two parts:

The static configuration (loaded only at the beginning)
The dynamic configuration (can be hot-reloaded, without restarting the proxy), where the routing table will be updated continuously.

Traefik allows us to have one file for the static configuration (the traefik.toml) and one or several files for the routes, that traefik would watch.

Note !

TraefikTomlProxy, uses two configuration files: one file for the routes (rules.toml), and one for the static configuration (traefik.toml).

By default, Traefik will search for traefik.toml and rules.toml in the following places:

/etc/traefik/
$HOME/.traefik/
. the working directory

You can override this in TraefikTomlProxy, by modifying the toml_static_config_file argument:

c.TraefikTomlProxy.toml_static_config_file="/path/to/static_config_filename.toml"

Similarly, you can override the dynamic configuration file by modifying the toml_dynamic_config_file argument:

c.TraefikTomlProxy.toml_dynamic_config_file="/path/to/dynamic_config_filename.toml"

Note !

When JupyterHub starts the proxy, it writes the static config once, then only edits the routes config file.

When JupyterHub does not start the proxy, the user is totally responsible for the static config and JupyterHub is responsible exclusively for the routes.¶

Externally managed TraefikTomlProxy¶

When TraefikTomlProxy is externally managed, service managers like systemd or docker will be responsible for starting and stopping the proxy.

If TraefikTomlProxy is used as an externally managed service, then make sure you follow the steps enumerated below:

Let JupyterHub know that the proxy being used is TraefikTomlProxy, using the proxy_class configuration option:
```
c.JupyterHub.proxy_class = "traefik_toml"
```
Configure TraeficTomlProxy in jupyterhub_config.py

JupyterHub configuration file, jupyterhub_config.py must specify at least:
- That the proxy is externally managed
- The traefik api credentials
- The dynamic configuration file, if different from rules.toml or if this file is located in another place than traefik’s default search directories (etc/traefik/, $HOME/.traefik/, the working directory)
Example configuration:
```
# JupyterHub shouldn't start the proxy, it's already running
c.TraefikTomlProxy.should_start = False

# if not the default:
c.TraefikTomlProxy.toml_dynamic_config_file = "somefile.toml"

# traefik api credentials
c.TraefikTomlProxy.traefik_api_username = "abc"
c.TraefikTomlProxy.traefik_api_password = "xxx"
```
Ensure traefik.toml

The static configuration file, traefik.toml must configure at least:
- The default entrypoint
- The api entrypoint (and authenticate it)
- The websockets protocol
- The dynamic configuration file to watch (make sure this configuration file exists, even if empty before the proxy is launched)

Example setup¶

This is an example setup for using JupyterHub and TraefikTomlProxy managed by another service than JupyterHub.

Configure the proxy through the JupyterHub configuration file, jupyterhub_config.py, e.g.:

from jupyterhub_traefik_proxy import TraefikTomlProxy

# mark the proxy as externally managed
c.TraefikTomlProxy.should_start = False

# traefik api endpoint login password
c.TraefikTomlProxy.traefik_api_password = "admin"

# traefik api endpoint login username
c.TraefikTomlProxy.traefik_api_username = "api_admin"

# traefik's dynamic configuration file
c.TraefikTomlProxy.toml_dynamic_config_file = "path/to/rules.toml"

# configure JupyterHub to use TraefikTomlProxy
c.JupyterHub.proxy_class = TraefikTomlProxy

Create a traefik static configuration file, traefik.toml, e.g.:

# the default entrypoint
defaultentrypoints = ["http"]

# the api entrypoint
[api]
dashboard = true
entrypoint = "auth_api"

# websockets protocol
[wss]
protocol = "http"

# the port on localhost where traefik accepts http requests
[entryPoints.http]
address = ":8000"

# the port on localhost where the traefik api and dashboard can be found
[entryPoints.auth_api]
address = ":8099"

# authenticate the traefik api entrypoint
[entryPoints.auth_api.auth.basic]
users = [ "api_admin:$apr1$eS/j3kum$q/X2khsIEG/bBGsteP.x./",]

# the dynamic configuration file
[file]
filename = "rules.toml"
watch = true

Start traefik with the configuration specified above, e.g.:
```
$ traefik -c traefik.toml
```

On this page