Running proxy separately from the hub#
Background#
The thing which users directly connect to is the proxy, by default
configurable-http-proxy. The proxy either redirects users to the
hub (for login and managing servers), or to their own single-user
servers. Thus, as long as the proxy stays running, access to existing
servers continues, even if the hub itself restarts or goes down.
When you first configure the hub, you may not even realize this because the proxy is automatically managed by the hub. This is great for getting started and even most use, but everytime you restart the hub, all user connections also get restarted. But it’s also simple to run the proxy as a service separate from the hub, so that you are free to reconfigure the hub while only interrupting users who are currently actively starting the hub.
The default JupyterHub proxy is configurable-http-proxy, and that page has some docs. If you are using a different proxy, such as Traefik, these instructions are probably not relevant to you.
Configuration options#
c.JupyterHub.cleanup_servers = False should be set, which tells the
hub to not stop servers when the hub restarts (this is useful even if
you don’t run the proxy separately).
c.ConfigurableHTTPProxy.should_start = False should be set, which
tells the hub that the proxy should not be started (because you start
it yourself).
c.ConfigurableHTTPProxy.auth_token = "CONFIGPROXY_AUTH_TOKEN" should be set to a
token for authenticating communication with the proxy.
c.ConfigurableHTTPProxy.api_url = 'http://localhost:8001' should be
set to the URL which the hub uses to connect to the proxy’s API.
Proxy configuration#
You need to configure a service to start the proxy. An example
command line for this is configurable-http-proxy --ip=127.0.0.1 --port=8000 --api-ip=127.0.0.1 --api-port=8001 --default-target=http://localhost:8081 --error-target=http://localhost:8081/hub/error. (Details for how to
do this is out of scope for this tutorial - for example it might be a
systemd service on within another docker cotainer). The proxy has no
configuration files, all configuration is via the command line and
environment variables.
--api-ip and --api-port (which tells the proxy where to listen) should match the hub’s ConfigurableHTTPProxy.api_url.
--ip, -port, and other options configure the user connections to the proxy.
--default-target and --error-target should point to the hub, and used when users navigate to the proxy originally.
You must define the environment variable CONFIGPROXY_AUTH_TOKEN to
match the token given to c.ConfigurableHTTPProxy.auth_token.
You should check the configurable-http-proxy options to see what other options are needed, for example SSL options. Note that these are configured in the hub if the hub is starting the proxy - you need to move the options to here.
Docker image#
You can use jupyterhub configurable-http-proxy docker image to run the proxy.