mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
73 lines
3.2 KiB
Markdown
73 lines
3.2 KiB
Markdown
# 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](https://github.com/jupyterhub/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](https://github.com/jupyterhub/configurable-http-proxy) 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](https://hub.docker.com/r/jupyterhub/configurable-http-proxy/)
|
|
to run the proxy.
|
|
|
|
## See also
|
|
|
|
- [jupyterhub configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy)
|