mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-08 02:24:08 +00:00
f366b785a3
See https://github.com/jupyterhub/team-compass/issues/688 for context. I've also added `QUAY_USERNAME` and `QUAY_PASSWORD` to environment secrets, but *not* `env.REGISTRY`. I will do so once this gets merged.
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
(separate-proxy)=
|
|
|
|
# Running proxy separately from the hub
|
|
|
|
## Background
|
|
|
|
The thing which users directly connect to is the proxy, which by default is
|
|
`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-cases, although, everytime you restart the
|
|
hub, all user connections are also restarted. However, it is 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 waiting for their notebook server to start.
|
|
starting their notebook server.
|
|
|
|
The default JupyterHub proxy is
|
|
[configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy). If you are using a different proxy, such
|
|
as [Traefik](https://github.com/traefik/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 argument for this is:
|
|
|
|
```bash
|
|
$ 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 on how to do this is out of the scope of this tutorial. For example, it might be a
|
|
systemd service configured within another docker container). 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 options are configured in the hub if the hub is starting the proxy, so you
|
|
need to configure the options there.
|
|
|
|
## Docker image
|
|
|
|
You can use [jupyterhub configurable-http-proxy docker
|
|
image](https://quay.io/repository/jupyterhub/configurable-http-proxy)
|
|
to run the proxy.
|
|
|
|
## See also
|
|
|
|
- [jupyterhub configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy)
|