Bump to 2.0.0rc5

changelog for 2.0.0rc5

.github/workflows/release.yml

@@ -190,3 +190,23 @@ jobs:
           platforms: linux/amd64
           push: true
           tags: ${{ join(fromJson(steps.demotags.outputs.tags)) }}
+
+      # jupyterhub/singleuser
+      - name: Get list of jupyterhub/singleuser tags
+        id: singleusertags
+        uses: jupyterhub/action-major-minor-tag-calculator@v2
+        with:
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          prefix: "${{ env.REGISTRY }}jupyterhub/singleuser:"
+          defaultTag: "${{ env.REGISTRY }}jupyterhub/singleuser:noref"
+          branchRegex: ^\w[\w-.]*$
+
+      - name: Build and push jupyterhub/singleuser
+        uses: docker/build-push-action@e1b7f96249f2e4c8e4ac1519b9608c0d48944a1f # associated tag: v2.4.0
+        with:
+          build-args: |
+            JUPYTERHUB_VERSION=${{ github.ref_type == 'tag' && github.ref_name || format('git:{0}', github.sha) }}
+          context: singleuser
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ join(fromJson(steps.singleusertags.outputs.tags)) }}

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.29.0
+    rev: v2.29.1
     hooks:
       - id: pyupgrade
         args:
@@ -10,7 +10,7 @@ repos:
     hooks:
       - id: reorder-python-imports
   - repo: https://github.com/psf/black
-    rev: 21.10b0
+    rev: 21.11b1
     hooks:
       - id: black
   - repo: https://github.com/pre-commit/mirrors-prettier

docs/source/_static/rest-api.yml

@@ -6,7 +6,7 @@ info:
   description: The REST API for JupyterHub
   license:
     name: BSD-3-Clause
-  version: 2.0.0rc4
+  version: 2.0.0rc5
 servers:
   - url: /hub/api
 security:

docs/source/reference/api-only.md

@@ -0,0 +1,128 @@
+(api-only)=
+
+# Deploying JupyterHub in "API only mode"
+
+As a service for deploying and managing Jupyter servers for users, JupyterHub
+exposes this functionality _primarily_ via a [REST API](rest).
+For convenience, JupyterHub also ships with a _basic_ web UI built using that REST API.
+The basic web UI enables users to click a button to quickly start and stop their servers,
+and it lets admins perform some basic user and server management tasks.
+
+The REST API has always provided additional functionality beyond what is available in the basic web UI.
+Similarly, we avoid implementing UI functionality that is also not available via the API.
+With JupyterHub 2.0, the basic web UI will **always** be composed using the REST API.
+In other words, no UI pages should rely on information not available via the REST API.
+Previously, some admin UI functionality could only be achieved via admin pages,
+such as paginated requests.
+
+## Limited UI customization via templates
+
+The JupyterHub UI is customizable via extensible HTML [templates](templates),
+but this has some limited scope to what can be customized.
+Adding some content and messages to existing pages is well supported,
+but changing the page flow and what pages are available are beyond the scope of what is customizable.
+
+## Rich UI customization with REST API based apps
+
+Increasingly, JupyterHub is used purely as an API for managing Jupyter servers
+for other Jupyter-based applications that might want to present a different user experience.
+If you want a fully customized user experience,
+you can now disable the Hub UI and use your own pages together with the JupyterHub REST API
+to build your own web application to serve your users,
+relying on the Hub only as an API for managing users and servers.
+
+One example of such an application is [BinderHub][], which powers https://mybinder.org,
+and motivates many of these changes.
+
+BinderHub is distinct from a traditional JupyterHub deployment
+because it uses temporary users created for each launch.
+Instead of presenting a login page,
+users are presented with a form to specify what environment they would like to launch:
+
+![Binder launch form](../images/binderhub-form.png)
+
+When a launch is requested:
+
+1. an image is built, if necessary
+2. a temporary user is created,
+3. a server is launched for that user, and
+4. when running, users are redirected to an already running server with an auth token in the URL
+5. after the session is over, the user is deleted
+
+This means that a lot of JupyterHub's UI flow doesn't make sense:
+
+- there is no way for users to login
+- the human user doesn't map onto a JupyterHub `User` in a meaningful way
+- when a server isn't running, there isn't a 'restart your server' action available because the user has been deleted
+- users do not have any access to any Hub functionality, so presenting pages for those features would be confusing
+
+BinderHub is one of the motivating use cases for JupyterHub supporting being used _only_ via its API.
+We'll use BinderHub here as an example of various configuration options.
+
+[binderhub]: https://binderhub.readthedocs.io
+
+## Disabling Hub UI
+
+`c.JupyterHub.hub_routespec` is a configuration option to specify which URL prefix should be routed to the Hub.
+The default is `/` which means that the Hub will receive all requests not already specified to be routed somewhere else.
+
+There are three values that are most logical for `hub_routespec`:
+
+- `/` - this is the default, and used in most deployments.
+  It is also the only option prior to JupyterHub 1.4.
+- `/hub/` - this serves only Hub pages, both UI and API
+- `/hub/api` - this serves _only the Hub API_, so all Hub UI is disabled,
+  aside from the OAuth confirmation page, if used.
+
+If you choose a hub routespec other than `/`,
+the main JupyterHub feature you will lose is the automatic handling of requests for `/user/:username`
+when the requested server is not running.
+
+JupyterHub's handling of this request shows this page,
+telling you that the server is not running,
+with a button to launch it again:
+
+![screenshot of hub page for server not running](../images/server-not-running.png)
+
+If you set `hub_routespec` to something other than `/`,
+it is likely that you also want to register another destination for `/` to handle requests to not-running servers.
+If you don't, you will see a default 404 page from the proxy:
+
+![screenshot of CHP default 404](../images/chp-404.png)
+
+For mybinder.org, the default "start my server" page doesn't make sense,
+because when a server is gone, there is no restart action.
+Instead, we provide hints about how to get back to a link to start a _new_ server:
+
+![screenshot of mybinder.org 404](../images/binder-404.png)
+
+To achieve this, mybinder.org registers a route for `/` that goes to a custom endpoint
+that runs nginx and only serves this static HTML error page.
+This is set with
+
+```python
+c.Proxy.extra_routes = {
+    "/": "http://custom-404-entpoint/",
+}
+```
+
+You may want to use an alternate behavior, such as redirecting to a landing page,
+or taking some other action based on the requested page.
+
+If you use `c.JupyterHub.hub_routespec = "/hub/"`,
+then all the Hub pages will be available,
+and only this default-page-404 issue will come up.
+
+If you use `c.JupyterHub.hub_routespec = "/hub/api/"`,
+then only the Hub _API_ will be available,
+and all UI will be up to you.
+mybinder.org takes this last option,
+because none of the Hub UI pages really make sense.
+Binder users don't have any reason to know or care that JupyterHub happens
+to be an implementation detail of how their environment is managed.
+Seeing Hub error pages and messages in that situation is more likely to be confusing than helpful.
+
+:::{versionadded} 1.4
+
+`c.JupyterHub.hub_routespec` and `c.Proxy.extra_routes` are new in JupyterHub 1.4.
+:::

docs/source/reference/index.rst

@@ -21,6 +21,7 @@ what happens under-the-hood when you deploy and configure your JupyterHub.
    monitoring
    database
    templates
+   api-only
    ../events/index
    config-user-env
    config-examples

docs/source/reference/rest.md

@@ -1,3 +1,5 @@
+(rest-api)=
+
 # Using JupyterHub's REST API
 
 This section will give you information on:

jupyterhub/_version.py

@@ -2,7 +2,7 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 # version_info updated by running `tbump`
-version_info = (2, 0, 0, "rc4", "")
+version_info = (2, 0, 0, "rc5", "")
 
 # pep 440 version: no dot before beta/rc, but before .dev
 # 0.1.0rc1

pyproject.toml

@@ -11,7 +11,7 @@ target_version = [
 github_url = "https://github.com/jupyterhub/jupyterhub"
 
 [tool.tbump.version]
-current = "2.0.0rc4"
+current = "2.0.0rc5"
 
 # Example of a semver regexp.
 # Make sure this matches current_version before

singleuser/Dockerfile

@@ -6,7 +6,6 @@ FROM $BASE_IMAGE
 MAINTAINER Project Jupyter <jupyter@googlegroups.com>
 
 ADD install_jupyterhub /tmp/install_jupyterhub
-ARG JUPYTERHUB_VERSION=main
-# install pinned jupyterhub and ensure jupyterlab is installed
-RUN python3 /tmp/install_jupyterhub && \
-    python3 -m pip install jupyterlab
+ARG JUPYTERHUB_VERSION=git:HEAD
+# install pinned jupyterhub
+RUN python3 /tmp/install_jupyterhub

singleuser/hooks/build

@@ -1,4 +0,0 @@
-#!/bin/bash
-set -ex
-
-docker build --build-arg JUPYTERHUB_VERSION=$DOCKER_TAG -t $DOCKER_REPO:$DOCKER_TAG .

singleuser/hooks/post_push

@@ -1,21 +0,0 @@
-#!/bin/bash
-set -ex
-
-function get_hub_version() {
-  rm -f hub_version
-  V=$1
-  docker run --rm -v $PWD:/version -u $(id -u) -i $DOCKER_REPO:$DOCKER_TAG sh -c 'jupyterhub --version > /version/hub_version'
-  hub_xyz=$(cat hub_version)
-  split=( ${hub_xyz//./ } )
-  hub_xy="${split[0]}.${split[1]}"
-  # add .dev on hub_xy so it's 1.0.dev
-  if [[ ! -z "${split[3]:-}" ]]; then
-    hub_xy="${hub_xy}.${split[3]}"
-  fi
-}
-# tag e.g. 0.9 with main
-get_hub_version
-docker tag $DOCKER_REPO:$DOCKER_TAG $DOCKER_REPO:$hub_xy
-docker push $DOCKER_REPO:$hub_xy
-docker tag $DOCKER_REPO:$DOCKER_TAG $DOCKER_REPO:$hub_xyz
-docker push $DOCKER_REPO:$hub_xyz

singleuser/install_jupyterhub

@@ -3,19 +3,22 @@ import os
 from subprocess import check_call
 import sys
 
-V = os.environ['JUPYTERHUB_VERSION']
+version = os.environ['JUPYTERHUB_VERSION']
 
 pip_install = [
-    sys.executable, '-m', 'pip', 'install', '--no-cache', '--upgrade',
-    '--upgrade-strategy', 'only-if-needed',
+    sys.executable,
+    '-m',
+    'pip',
+    'install',
+    '--no-cache',
+    '--upgrade',
+    '--upgrade-strategy',
+    'only-if-needed',
 ]
-if V in {'main', 'HEAD'}:
-    req = 'https://github.com/jupyterhub/jupyterhub/archive/HEAD.tar.gz'
+if version.startswith("git:"):
+    ref = version.partition(":")[-1]
+    req = f"https://github.com/jupyterhub/jupyterhub/archive/{ref}.tar.gz"
 else:
-    version_info = [ int(part) for part in V.split('.') ]
-    version_info[-1] += 1
-    upper_bound = '.'.join(map(str, version_info))
-    vs = '>=%s,<%s' % (V, upper_bound)
-    req = 'jupyterhub%s' % vs
+    req = f"jupyterhub=={version}"
 
 check_call(pip_install + [req])