hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 07:23:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4097 from Mackenzie-OO7/fix-typos

Browse Source 
Modifications to URLs docs
This commit is contained in:
Min RK
2022-10-20 09:03:20 +02:00
committed by GitHub
parent 30e652f59e e82bd5a96b
commit b0c2dd01a1
1 changed files with 42 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/source/reference/urls.md
View File

@@ -2,13 +2,13 @@
This document describes how JupyterHub routes requests. This document describes how JupyterHub routes requests.
This does not include the [REST API](./rest.md) urls. This does not include the [REST API](./rest.md) URLs.
In general, all URLs can be prefixed with `c.JupyterHub.base_url` to In general, all URLs can be prefixed with `c.JupyterHub.base_url` to
run the whole JupyterHub application on a prefix. run the whole JupyterHub application on a prefix.
All authenticated handlers redirect to `/hub/login` to login users All authenticated handlers redirect to `/hub/login` to log-in users
prior to being redirected back to the originating page. before being redirected back to the originating page.
The returned request should preserve all query parameters. The returned request should preserve all query parameters.
## `/` ## `/`
@@ -25,12 +25,12 @@ This is an authenticated URL.
This handler redirects users to the default URL of the application, This handler redirects users to the default URL of the application,
which defaults to the user's default server. which defaults to the user's default server.
That is, it redirects to `/hub/spawn` if the user's server is not running, That is, the handler redirects to `/hub/spawn` if the user's server is not running,
or the server itself (`/user/:name`) if the server is running. or to the server itself (`/user/:name`) if the server is running.
This default url behavior can be customized in two ways: This default URL behavior can be customized in two ways:
To redirect users to the JupyterHub home page (`/hub/home`) First, to redirect users to the JupyterHub home page (`/hub/home`)
instead of spawning their server, instead of spawning their server,
set `redirect_to_server` to False: set `redirect_to_server` to False:
@@ -40,7 +40,7 @@ c.JupyterHub.redirect_to_server = False
This might be useful if you have a Hub where you expect This might be useful if you have a Hub where you expect
users to be managing multiple server configurations users to be managing multiple server configurations
and automatic spawning is not desirable. but automatic spawning is not desirable.
Second, you can customise the landing page to any page you like, Second, you can customise the landing page to any page you like,
such as a custom service you have deployed e.g. with course information: such as a custom service you have deployed e.g. with course information:
@@ -57,7 +57,7 @@ By default, the Hub home page has just one or two buttons
for starting and stopping the user's server. for starting and stopping the user's server.
If named servers are enabled, there will be some additional If named servers are enabled, there will be some additional
tools for management of named servers. tools for management of the named servers.
_Version added: 1.0_ named server UI is new in 1.0. _Version added: 1.0_ named server UI is new in 1.0.
@@ -65,34 +65,34 @@ _Version added: 1.0_ named server UI is new in 1.0.
This is the JupyterHub login page. This is the JupyterHub login page.
If you have a form-based username+password login, If you have a form-based username+password login,
such as the default PAMAuthenticator, such as the default [PAMAuthenticator](https://en.wikipedia.org/wiki/Pluggable_authentication_module),
this page will render the login form. this page will render the login form.
![A login form](../images/login-form.png) ![A login form](../images/login-form.png)
If login is handled by an external service, If login is handled by an external service,
e.g. with OAuth, this page will have a button, e.g. with OAuth, this page will have a button,
declaring "Login with ..." which users can click declaring "Log in with ..." which users can click
to login with the chosen service. to log in with the chosen service.
![A login redirect button](../images/login-button.png) ![A login redirect button](../images/login-button.png)
If you want to skip the user-interaction to initiate logging in If you want to skip the user interaction and initiate login
via the button, you can set via the button, you can set:
```python ```python
c.Authenticator.auto_login = True c.Authenticator.auto_login = True
``` ```
This can be useful when the user is "already logged in" via some mechanism, This can be useful when the user is "already logged in" via some mechanism.
but a handshake via redirects is necessary to complete the authentication with JupyterHub. However, a handshake via `redirects` is necessary to complete the authentication with JupyterHub.
## `/hub/logout` ## `/hub/logout`
Visiting `/hub/logout` clears cookies from the current browser. Visiting `/hub/logout` clears [cookies](https://en.wikipedia.org/wiki/HTTP_cookie) from the current browser.
Note that **logging out does not stop a user's server(s)** by default. Note that **logging out does not stop a user's server(s)** by default.
If you would like to shutdown user servers on logout, If you would like to shut down user servers on logout,
you can enable this behavior with: you can enable this behavior with:
```python ```python
@@ -105,8 +105,8 @@ does not mean the user is no longer actively using their server from another mac
## `/user/:username[/:servername]` ## `/user/:username[/:servername]`
If a user's server is running, this URL is handled by the user's given server, If a user's server is running, this URL is handled by the user's given server,
not the Hub. not by the Hub.
The username is the first part and, if using named servers, The username is the first part, and if using named servers,
the server name is the second part. the server name is the second part.
If the user's server is _not_ running, this will be redirected to `/hub/user/:username/...` If the user's server is _not_ running, this will be redirected to `/hub/user/:username/...`
@@ -120,11 +120,11 @@ if the specified server were running).
Handling this URL is the most complicated condition in JupyterHub, Handling this URL is the most complicated condition in JupyterHub,
because there can be many states: because there can be many states:
1. server is not active 1. the server is not active
a. user matches a. user matches
b. user doesn't match b. user doesn't match
2. server is ready 2. the server is ready
3. server is pending, but not ready 3. the server is pending, but not ready
If the server is pending spawn, If the server is pending spawn,
the browser will be redirected to `/hub/spawn-pending/:username/:servername` the browser will be redirected to `/hub/spawn-pending/:username/:servername`
@@ -140,39 +140,37 @@ Some checks are performed and a delay is added before redirecting back to `/user
If something is really wrong, this can result in a redirect loop. If something is really wrong, this can result in a redirect loop.
Visiting this page will never result in triggering the spawn of servers Visiting this page will never result in triggering the spawn of servers
without additional user action (i.e. clicking the link on the page) without additional user action (i.e. clicking the link on the page).
![Visiting a URL for a server that's not running](../images/not-running.png) ![Visiting a URL for a server that's not running](../images/not-running.png)
_Version changed: 1.0_ _Version changed: 1.0_
Prior to 1.0, this URL itself was responsible for spawning servers, Prior to 1.0, this URL itself was responsible for spawning servers.
and served the progress page if it was pending, If the progress page was pending, the URL redirected it to running servers.
redirected to running servers, and This was useful because it made sure that the requested servers were restarted after they stopped.
This was useful because it made sure that requested servers were restarted after they stopped, However, it could also be harmful because unused servers would continuously be restarted if e.g.
but could also be harmful because unused servers would continuously be restarted if e.g. an idle JupyterLab frontend that constantly makes polling requests was openly pointed at it.
an idle JupyterLab frontend were open pointed at it,
which constantly makes polling requests.
### Special handling of API requests ### Special handling of API requests
Requests to `/user/:username[/:servername]/api/...` are assumed to be Requests to `/user/:username[/:servername]/api/...` are assumed to be
from applications connected to stopped servers. from applications connected to stopped servers.
These are failed with 503 and an informative JSON error message These requests fail with a `503` status code and an informative JSON error message
indicating how to spawn the server. that indicates how to spawn the server.
This is meant to help applications such as JupyterLab This is meant to help applications such as JupyterLab,
that are connected to a server that has stopped. that are connected to a server that has stopped.
_Version changed: 1.0_ _Version changed: 1.0_
JupyterHub 0.9 failed these API requests with status 404, JupyterHub version 0.9 failed these API requests with status `404`,
but 1.0 uses 503. but version 1.0 uses 503.
## `/user-redirect/...` ## `/user-redirect/...`
This URL is for sharing a URL that will redirect a user The `/user-redirect/...` URL is for sharing a URL that will redirect a user
to a path on their own default server. to a path on their own default server.
This is useful when users have the same file at the same URL on their servers, This is useful when different users have the same file at the same URL on their servers,
and you want a single link to give to any user that will open that file on their server. and you want a single link to give to any user that will open that file on their server.
e.g. a link to `/user-redirect/notebooks/Index.ipynb` e.g. a link to `/user-redirect/notebooks/Index.ipynb`
@@ -194,7 +192,7 @@ that is intended to make it possible.
### `/hub/spawn[/:username[/:servername]]` ### `/hub/spawn[/:username[/:servername]]`
Requesting `/hub/spawn` will spawn the default server for the current user. Requesting `/hub/spawn` will spawn the default server for the current user.
If `username` and optionally `servername` are specified, If the `username` and optionally `servername` are specified,
then the specified server for the specified user will be spawned. then the specified server for the specified user will be spawned.
Once spawn has been requested, Once spawn has been requested,
the browser is redirected to `/hub/spawn-pending/...`. the browser is redirected to `/hub/spawn-pending/...`.
@@ -207,7 +205,7 @@ and a POST request will trigger the actual spawn and redirect.
_Version added: 1.0_ _Version added: 1.0_
1.0 adds the ability to specify username and servername. 1.0 adds the ability to specify `username` and `servername`.
Prior to 1.0, only `/hub/spawn` was recognized for the default server. Prior to 1.0, only `/hub/spawn` was recognized for the default server.
_Version changed: 1.0_ _Version changed: 1.0_
@@ -247,7 +245,7 @@ against the [JupyterHub REST API](./rest.md).
Administrators can take various administrative actions from this page: Administrators can take various administrative actions from this page:
1. add/remove users - add/remove users
2. grant admin privileges - grant admin privileges
3. start/stop user servers - start/stop user servers
4. shutdown JupyterHub itself - shutdown JupyterHub itself