Bump to 5.0.0b1

changelog for 5.0, add migration doc

.dockerignore

@@ -5,6 +5,5 @@ jupyterhub.sqlite
 jupyterhub_config.py
 node_modules
 docs
-.git
 dist
 build

.github/workflows/registry-overviews.yml

@@ -0,0 +1,54 @@
+name: Update Registry overviews
+
+env:
+  OWNER: ${{ github.repository_owner }}
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/registry-overviews.yml"
+
+      - "README.md"
+      - "onbuild/README.md"
+      - "demo-image/README.md"
+      - "singleuser/README.md"
+  workflow_dispatch:
+
+jobs:
+  update-overview:
+    runs-on: ubuntu-latest
+    name: update-overview (${{matrix.image}})
+    if: github.repository_owner == 'jupyterhub'
+
+    steps:
+      - name: Checkout Repo ⚡️
+        uses: actions/checkout@v4
+
+      - name: Push README to Registry 🐳
+        uses: christian-korneck/update-container-description-action@d36005551adeaba9698d8d67a296bd16fa91f8e8 # v1
+        env:
+          DOCKER_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKER_PASS: ${{ secrets.DOCKERHUB_TOKEN }}
+        with:
+          destination_container_repo: ${{ env.OWNER }}/${{ matrix.image }}
+          provider: dockerhub
+          short_description: ${{ matrix.description }}
+          readme_file: ${{ matrix.readme_file }}
+
+    strategy:
+      matrix:
+        include:
+          - image: jupyterhub
+            description: "JupyterHub: multi-user Jupyter notebook server"
+            readme_file: README.md
+          - image: jupyterhub-onbuild
+            description: onbuild version of JupyterHub images
+            readme_file: onbuild/README.md
+          - image: jupyterhub-demo
+            description: Demo JupyterHub Docker image with a quick overview of what JupyterHub is and how it works
+            readme_file: demo-image/README.md
+          - image: singleuser
+            description: "single-user docker images for use with JupyterHub and DockerSpawner see also: jupyter/docker-stacks"
+            readme_file: singleuser/README.md

.github/workflows/release.yml

@@ -30,16 +30,16 @@ on:
 
 jobs:
   build-release:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
-          node-version: "14"
+          node-version: "20"
 
       - name: install build requirements
         run: |
@@ -67,7 +67,7 @@ jobs:
           docker run --rm -v $PWD/dist:/dist:ro docker.io/library/python:3.9-slim-bullseye bash -c 'pip install /dist/jupyterhub-*.tar.gz'
 
       # ref: https://github.com/actions/upload-artifact#readme
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: jupyterhub-${{ github.sha }}
           path: "dist/*"
@@ -83,8 +83,8 @@ jobs:
           twine upload --skip-existing dist/*
 
   publish-docker:
-    runs-on: ubuntu-20.04
-    timeout-minutes: 20
+    runs-on: ubuntu-22.04
+    timeout-minutes: 30
 
     services:
       # So that we can test this in PRs/branches
@@ -97,39 +97,35 @@ jobs:
       - name: Should we push this image to a public registry?
         run: |
           if [ "${{ startsWith(github.ref, 'refs/tags/') || (github.ref == 'refs/heads/main') }}" = "true" ]; then
-              # Empty => Docker Hub
-              echo "REGISTRY=" >> $GITHUB_ENV
+              echo "REGISTRY=quay.io/" >> $GITHUB_ENV
           else
               echo "REGISTRY=localhost:5000/" >> $GITHUB_ENV
           fi
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       # Setup docker to build for multiple platforms, see:
       # https://github.com/docker/build-push-action/tree/v2.4.0#usage
       # https://github.com/docker/build-push-action/blob/v2.4.0/docs/advanced/multi-platform.md
       - name: Set up QEMU (for docker buildx)
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v3
 
       - name: Set up Docker Buildx (for multi-arch builds)
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
         with:
           # Allows pushing to registry on localhost:5000
           driver-opts: network=host
 
       - name: Setup push rights to Docker Hub
         # This was setup by...
-        # 1. Creating a Docker Hub service account "jupyterhubbot"
-        # 2. Creating a access token for the service account specific to this
-        #    repository: https://hub.docker.com/settings/security
-        # 3. Making the account part of the "bots" team, and granting that team
-        #    permissions to push to the relevant images:
-        #    https://hub.docker.com/orgs/jupyterhub/teams/bots/permissions
-        # 4. Registering the username and token as a secret for this repo:
-        #    https://github.com/jupyterhub/jupyterhub/settings/secrets/actions
+        # 1. Creating a [Robot Account](https://quay.io/organization/jupyterhub?tab=robots) in the JupyterHub
+        # .  Quay.io org
+        # 2. Giving it enough permissions to push to the jupyterhub and singleuser images
+        # 3. Putting the robot account's username and password in GitHub actions environment
         if: env.REGISTRY != 'localhost:5000/'
         run: |
-          docker login -u "${{ secrets.DOCKERHUB_USERNAME }}" -p "${{ secrets.DOCKERHUB_TOKEN }}"
+          docker login -u "${{ secrets.QUAY_USERNAME }}" -p "${{ secrets.QUAY_PASSWORD }}" "${{ env.REGISTRY }}"
+          docker login -u "${{ secrets.DOCKERHUB_USERNAME }}" -p "${{ secrets.DOCKERHUB_TOKEN }}" docker.io
 
       # image: jupyterhub/jupyterhub
       #
@@ -142,15 +138,17 @@ jobs:
       # If GITHUB_TOKEN isn't available (e.g. in PRs) returns no tags [].
       - name: Get list of jupyterhub tags
         id: jupyterhubtags
-        uses: jupyterhub/action-major-minor-tag-calculator@v2
+        uses: jupyterhub/action-major-minor-tag-calculator@v3
         with:
           githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: "${{ env.REGISTRY }}jupyterhub/jupyterhub:"
+          prefix: >-
+            ${{ env.REGISTRY }}jupyterhub/jupyterhub:
+            jupyterhub/jupyterhub:
           defaultTag: "${{ env.REGISTRY }}jupyterhub/jupyterhub:noref"
           branchRegex: ^\w[\w-.]*$
 
       - name: Build and push jupyterhub
-        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
+        uses: docker/build-push-action@v5
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -163,15 +161,17 @@ jobs:
       #
       - name: Get list of jupyterhub-onbuild tags
         id: onbuildtags
-        uses: jupyterhub/action-major-minor-tag-calculator@v2
+        uses: jupyterhub/action-major-minor-tag-calculator@v3
         with:
           githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: "${{ env.REGISTRY }}jupyterhub/jupyterhub-onbuild:"
+          prefix: >-
+            ${{ env.REGISTRY }}jupyterhub/jupyterhub-onbuild:
+            jupyterhub/jupyterhub-onbuild:
           defaultTag: "${{ env.REGISTRY }}jupyterhub/jupyterhub-onbuild:noref"
           branchRegex: ^\w[\w-.]*$
 
       - name: Build and push jupyterhub-onbuild
-        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
+        uses: docker/build-push-action@v5
         with:
           build-args: |
             BASE_IMAGE=${{ fromJson(steps.jupyterhubtags.outputs.tags)[0] }}
@@ -184,15 +184,17 @@ jobs:
       #
       - name: Get list of jupyterhub-demo tags
         id: demotags
-        uses: jupyterhub/action-major-minor-tag-calculator@v2
+        uses: jupyterhub/action-major-minor-tag-calculator@v3
         with:
           githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: "${{ env.REGISTRY }}jupyterhub/jupyterhub-demo:"
+          prefix: >-
+            ${{ env.REGISTRY }}jupyterhub/jupyterhub-demo:
+            jupyterhub/jupyterhub-demo:
           defaultTag: "${{ env.REGISTRY }}jupyterhub/jupyterhub-demo:noref"
           branchRegex: ^\w[\w-.]*$
 
       - name: Build and push jupyterhub-demo
-        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
+        uses: docker/build-push-action@v5
         with:
           build-args: |
             BASE_IMAGE=${{ fromJson(steps.onbuildtags.outputs.tags)[0] }}
@@ -208,15 +210,17 @@ jobs:
       #
       - name: Get list of jupyterhub/singleuser tags
         id: singleusertags
-        uses: jupyterhub/action-major-minor-tag-calculator@v2
+        uses: jupyterhub/action-major-minor-tag-calculator@v3
         with:
           githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: "${{ env.REGISTRY }}jupyterhub/singleuser:"
+          prefix: >-
+            ${{ env.REGISTRY }}jupyterhub/singleuser:
+            jupyterhub/singleuser:
           defaultTag: "${{ env.REGISTRY }}jupyterhub/singleuser:noref"
           branchRegex: ^\w[\w-.]*$
 
       - name: Build and push jupyterhub/singleuser
-        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
+        uses: docker/build-push-action@v5
         with:
           build-args: |
             JUPYTERHUB_VERSION=${{ github.ref_type == 'tag' && github.ref_name || format('git:{0}', github.sha) }}

.github/workflows/support-bot.yml

@@ -12,7 +12,7 @@ jobs:
   action:
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/support-requests@v3
+      - uses: dessant/support-requests@v4
         with:
           github-token: ${{ github.token }}
           support-label: "support"

.github/workflows/test-docs.yml

@@ -36,31 +36,35 @@ env:
 
 jobs:
   validate-rest-api-definition:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
 
       - name: Validate REST API definition
-        uses: char0n/swagger-editor-validate@v1.3.2
-        with:
-          definition-file: docs/source/_static/rest-api.yml
+        run: |
+          npx @redocly/cli lint
 
   test-docs:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # make rediraffecheckdiff requires git history to compare current
           # commit with the main branch and previous releases.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
       - name: Install requirements
         run: |
-          pip install -r docs/requirements.txt pytest
+          pip install -e . -r docs/requirements.txt pytest
 
       - name: pytest docs/
         run: |

.github/workflows/test-jsx.yml

@@ -25,28 +25,24 @@ permissions:
 jobs:
   # The ./jsx folder contains React based source code files that are to compile
   # to share/jupyterhub/static/js/admin-react.js. The ./jsx folder includes
-  # tests also has tests that this job is meant to run with `yarn test`
+  # tests also has tests that this job is meant to run with `npm test`
   # according to the documentation in jsx/README.md.
   test-jsx-admin-react:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 5
 
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: "14"
+          node-version: "20"
 
-      - name: Install yarn
-        run: |
-          npm install -g yarn
-
-      - name: yarn
+      - name: install jsx
         run: |
           cd jsx
-          yarn
+          npm ci
 
-      - name: yarn test
+      - name: test
         run: |
           cd jsx
-          yarn test
+          npm test

.github/workflows/test.yml

@@ -36,7 +36,7 @@ permissions:
 jobs:
   # Run "pytest jupyterhub/tests" in various configurations
   pytest:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 15
 
     strategy:
@@ -65,7 +65,7 @@ jobs:
         #   unencrypted HTTP
         #
         # main_dependencies:
-        #   Tests everything when the we use the latest available dependencies
+        #   Tests everything when we use the latest available dependencies
         #   from: traitlets.
         #
         # NOTE: Since only the value of these parameters are presented in the
@@ -74,7 +74,7 @@ jobs:
         # Python versions available at:
         #   https://github.com/actions/python-versions/blob/HEAD/versions-manifest.json
         include:
-          - python: "3.7"
+          - python: "3.8"
             oldest_dependencies: oldest_dependencies
             legacy_notebook: legacy_notebook
           - python: "3.8"
@@ -84,12 +84,15 @@ jobs:
             db: mysql
           - python: "3.10"
             db: postgres
-          - python: "3.11"
+          - python: "3.12"
             subdomain: subdomain
             serverextension: serverextension
           - python: "3.11"
             ssl: ssl
             serverextension: serverextension
+          - python: "3.11"
+            jupyverse: jupyverse
+            subset: singleuser
           - python: "3.11"
             subdomain: subdomain
             noextension: noextension
@@ -101,6 +104,9 @@ jobs:
           - python: "3.11"
             browser: browser
           - python: "3.11"
+            subdomain: subdomain
+            browser: browser
+          - python: "3.12"
             main_dependencies: main_dependencies
 
     steps:
@@ -130,37 +136,39 @@ jobs:
           elif [ "${{ matrix.noextension }}" != "" ]; then
               echo "JUPYTERHUB_SINGLEUSER_EXTENSION=0" >> $GITHUB_ENV
           fi
-      - uses: actions/checkout@v3
-      # NOTE: actions/setup-node@v3 make use of a cache within the GitHub base
+          if [ "${{ matrix.jupyverse }}" != "" ]; then
+              echo "JUPYTERHUB_SINGLEUSER_APP=jupyverse" >> $GITHUB_ENV
+          fi
+      - uses: actions/checkout@v4
+      # NOTE: actions/setup-node@v4 make use of a cache within the GitHub base
       #       environment and setup in a fraction of a second.
-      - name: Install Node v14
-        uses: actions/setup-node@v3
+      - name: Install Node
+        uses: actions/setup-node@v4
         with:
-          node-version: "14"
+          node-version: "20"
       - name: Install Javascript dependencies
         run: |
           npm install
           npm install -g configurable-http-proxy yarn
           npm list
 
-      # NOTE: actions/setup-python@v4 make use of a cache within the GitHub base
+      # NOTE: actions/setup-python@v5 make use of a cache within the GitHub base
       #       environment and setup in a fraction of a second.
       - name: Install Python ${{ matrix.python }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "${{ matrix.python }}"
 
       - name: Install Python dependencies
         run: |
           pip install --upgrade pip
-          pip install -e ".[test]"
 
           if [ "${{ matrix.oldest_dependencies }}" != "" ]; then
-            # take any dependencies in requirements.txt such as tornado>=5.0
-            # and transform them to tornado==5.0 so we can run tests with
-            # the earliest-supported versions
-            cat requirements.txt | grep '>=' | sed -e 's@>=@==@g' > oldest-requirements.txt
-            pip install -r oldest-requirements.txt
+            # frozen env with oldest dependencies
+            # make sure our `>=` pins really do express our minimum supported versions
+            pip install -r ci/oldest-dependencies/requirements.old -e .
+          else
+            pip install -e ".[test]"
           fi
 
           if [ "${{ matrix.main_dependencies }}" != "" ]; then
@@ -176,6 +184,10 @@ jobs:
           if [ "${{ matrix.jupyter_server }}" != "" ]; then
               pip install "jupyter_server==${{ matrix.jupyter_server }}"
           fi
+          if [ "${{ matrix.jupyverse }}" != "" ]; then
+              pip install "jupyverse[jupyterlab,auth-jupyterhub]"
+              pip install -e .
+          fi
           if [ "${{ matrix.db }}" == "mysql" ]; then
               pip install mysqlclient
           fi
@@ -241,14 +253,14 @@ jobs:
         run: |
           pytest -k "${{ matrix.subset }}" --maxfail=2 --cov=jupyterhub jupyterhub/tests
 
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
 
   docker-build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: build images
         run: |

.gitignore

@@ -12,6 +12,8 @@ docs/source/rbac/scope-table.md
 docs/source/reference/metrics.md
 
 .ipynb_checkpoints
+.virtual_documents
+
 jsx/build/
 # ignore config file at the top-level of the repo
 # but not sub-dirs
@@ -19,8 +21,9 @@ jsx/build/
 jupyterhub_cookie_secret
 jupyterhub.sqlite
 jupyterhub.sqlite*
-package-lock.json
 share/jupyterhub/static/components
+share/jupyterhub/static/css/style.css
+share/jupyterhub/static/css/style.css.map
 share/jupyterhub/static/css/style.min.css
 share/jupyterhub/static/css/style.min.css.map
 share/jupyterhub/static/js/admin-react.js*
@@ -37,3 +40,5 @@ docs/source/reference/metrics.rst
 oldest-requirements.txt
 jupyterhub-proxy.pid
 examples/server-api/service-token
+
+*.hot-update*

.pre-commit-config.yaml

@@ -14,53 +14,44 @@ ci:
   autoupdate_schedule: monthly
 
 repos:
-  # Autoformat: Python code, syntax patterns are modernized
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.4.0
+  # autoformat and lint Python code
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.5
     hooks:
-      - id: pyupgrade
-        args:
-          - --py37-plus
-
-  # Autoformat: Python code
-  - repo: https://github.com/PyCQA/autoflake
-    rev: v2.1.1
-    hooks:
-      - id: autoflake
-        # args ref: https://github.com/PyCQA/autoflake#advanced-usage
-        args:
-          - --in-place
-
-  # Autoformat: Python code
-  - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-
-  # Autoformat: Python code
-  - repo: https://github.com/psf/black
-    rev: 23.3.0
-    hooks:
-      - id: black
+      - id: ruff
+        types_or:
+          - python
+          - jupyter
+        args: ["--fix", "--show-fixes"]
+      - id: ruff-format
+        types_or:
+          - python
+          - jupyter
 
   # Autoformat: markdown, yaml, javascript (see the file .prettierignore)
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0-alpha.9-for-vscode
+    rev: v4.0.0-alpha.8
     hooks:
       - id: prettier
+        exclude: .*/templates/.*
+
+  # autoformat HTML templates
+  - repo: https://github.com/djlint/djLint
+    rev: v1.34.1
+    hooks:
+      - id: djlint-reformat-jinja
+        files: ".*templates/.*.html"
+        types_or: ["html"]
+      - id: djlint-jinja
+        files: ".*templates/.*.html"
+        types_or: ["html"]
 
   # Autoformat and linting, misc. details
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: end-of-file-fixer
         exclude: share/jupyterhub/static/js/admin-react.js
       - id: requirements-txt-fixer
       - id: check-case-conflict
       - id: check-executables-have-shebangs
-
-  # Linting: Python code (see the file .flake8)
-  - repo: https://github.com/PyCQA/flake8
-    rev: "6.0.0"
-    hooks:
-      - id: flake8

.prettierignore

@@ -1,3 +1,4 @@
 share/jupyterhub/templates/
 share/jupyterhub/static/js/admin-react.js
 jupyterhub/singleuser/templates/
+docs/source/_templates/

.readthedocs.yaml

@@ -8,13 +8,14 @@ sphinx:
   configuration: docs/source/conf.py
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    nodejs: "16"
-    python: "3.9"
+    nodejs: "20"
+    python: "3.11"
 
 python:
   install:
+    - path: .
     - requirements: docs/requirements.txt
 
 formats:

Dockerfile

@@ -6,7 +6,7 @@
 #
 # Option 1:
 #
-# FROM jupyterhub/jupyterhub:latest
+# FROM quay.io/jupyterhub/jupyterhub:latest
 #
 # And put your configuration file jupyterhub_config.py in /srv/jupyterhub/jupyterhub_config.py.
 #
@@ -14,10 +14,10 @@
 #
 # Or you can create your jupyterhub config and database on the host machine, and mount it with:
 #
-# docker run -v $PWD:/srv/jupyterhub -t jupyterhub/jupyterhub
+# docker run -v $PWD:/srv/jupyterhub -t quay.io/jupyterhub/jupyterhub
 #
 # NOTE
-# If you base on jupyterhub/jupyterhub-onbuild
+# If you base on quay.io/jupyterhub/jupyterhub-onbuild
 # your jupyterhub_config.py will be added automatically
 # from your docker directory.
 
@@ -44,6 +44,8 @@ RUN apt-get update -qq \
     build-essential \
     ca-certificates \
     curl \
+    git \
+    gnupg \
     locales \
     python3-dev \
     python3-pip \
@@ -52,10 +54,13 @@ RUN apt-get update -qq \
  && python3 -m pip install --no-cache-dir --upgrade setuptools pip build wheel
 # Ubuntu 22.04 comes with Nodejs 12 which is too old for building JupyterHub JS
 # It's fine at runtime though (used only by configurable-http-proxy)
-RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+ARG NODE_MAJOR=20
+RUN mkdir -p /etc/apt/keyrings \
+ && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+ && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
+ && apt-get update \
  && apt-get install -yqq --no-install-recommends \
-    nodejs \
- && npm install --global yarn
+    nodejs
 
 WORKDIR /src/jupyterhub
 # copy everything except whats in .dockerignore, its a
@@ -67,6 +72,11 @@ ARG PIP_CACHE_DIR=/tmp/pip-cache
 RUN --mount=type=cache,target=${PIP_CACHE_DIR} \
     python3 -m build --wheel
 
+# verify installed files
+RUN --mount=type=cache,target=${PIP_CACHE_DIR} \
+    python3 -m pip install ./dist/*.whl \
+ && cd ci \
+ && python3 check_installed_data.py
 
 ######################################################################
 # All other wheels required by JupyterHub, some are platform specific

MANIFEST.in

@@ -1,29 +1,13 @@
-include README.md
-include COPYING.md
-include setupegg.py
-include bower-lite
-include package.json
+# using setuptools-scm means we only need to handle _non-tracked files here_
+
 include package-lock.json
-include *requirements.txt
-include Dockerfile
 
-graft onbuild
-graft jsx
-graft jupyterhub
-graft scripts
+# include untracked js/css artifacts, components
 graft share
-graft singleuser
-graft ci
 
-# Documentation
-graft docs
-prune docs/node_modules
-
-# Intermediate javascript files
-prune jsx/node_modules
-prune jsx/build
-
-# prune some large unused files from components
+# prune some large unused files from components.
+# these patterns affect source distributions (sdists)
+# we have stricter exclusions from installation in setup.py:get_data_files
 prune share/jupyterhub/static/components/bootstrap/dist/css
 exclude share/jupyterhub/static/components/bootstrap/dist/fonts/*.svg
 prune share/jupyterhub/static/components/font-awesome/css
@@ -33,11 +17,3 @@ prune share/jupyterhub/static/components/jquery/external
 prune share/jupyterhub/static/components/jquery/src
 prune share/jupyterhub/static/components/moment/lang
 prune share/jupyterhub/static/components/moment/min
-
-# Patterns to exclude from any directory
-global-exclude *~
-global-exclude *.pyc
-global-exclude *.pyo
-global-exclude .git
-global-exclude .ipynb_checkpoints
-global-exclude .bower.json

README.md

@@ -14,7 +14,6 @@
 [![Latest conda-forge version](https://img.shields.io/conda/vn/conda-forge/jupyterhub?logo=conda-forge)](https://anaconda.org/conda-forge/jupyterhub)
 [![Documentation build status](https://img.shields.io/readthedocs/jupyterhub?logo=read-the-docs)](https://jupyterhub.readthedocs.org/en/latest/)
 [![GitHub Workflow Status - Test](https://img.shields.io/github/workflow/status/jupyterhub/jupyterhub/Test?logo=github&label=tests)](https://github.com/jupyterhub/jupyterhub/actions)
-[![DockerHub build status](https://img.shields.io/docker/build/jupyterhub/jupyterhub?logo=docker&label=build)](https://hub.docker.com/r/jupyterhub/jupyterhub/tags)
 [![Test coverage of code](https://codecov.io/gh/jupyterhub/jupyterhub/branch/main/graph/badge.svg)](https://codecov.io/gh/jupyterhub/jupyterhub)
 [![GitHub](https://img.shields.io/badge/issue_tracking-github-blue?logo=github)](https://github.com/jupyterhub/jupyterhub/issues)
 [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/c/jupyterhub)
@@ -57,7 +56,7 @@ for administration of the Hub and its users.
 ### Check prerequisites
 
 - A Linux/Unix based system
-- [Python](https://www.python.org/downloads/) 3.6 or greater
+- [Python](https://www.python.org/downloads/) 3.8 or greater
 - [nodejs/npm](https://www.npmjs.com/)
 
   - If you are using **`conda`**, the nodejs and npm dependencies will be installed for
@@ -160,10 +159,10 @@ To start the Hub on a specific url and port `10.0.1.2:443` with **https**:
 
 ## Docker
 
-A starter [**docker image for JupyterHub**](https://hub.docker.com/r/jupyterhub/jupyterhub/)
+A starter [**docker image for JupyterHub**](https://quay.io/repository/jupyterhub/jupyterhub)
 gives a baseline deployment of JupyterHub using Docker.
 
-**Important:** This `jupyterhub/jupyterhub` image contains only the Hub itself,
+**Important:** This `quay.io/jupyterhub/jupyterhub` image contains only the Hub itself,
 with no configuration. In general, one needs to make a derivative image, with
 at least a `jupyterhub_config.py` setting up an Authenticator and/or a Spawner.
 To run the single-user servers, which may be on the same system as the Hub or
@@ -171,7 +170,7 @@ not, Jupyter Notebook version 4 or greater must be installed.
 
 The JupyterHub docker image can be started with the following command:
 
-    docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub
+    docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub
 
 This command will create a container named `jupyterhub` that you can
 **stop and resume** with `docker stop/start`.

bower-lite

@@ -7,6 +7,7 @@ bower-lite
 Since Bower's on its way out,
 stage frontend dependencies from node_modules into components
 """
+
 import json
 import os
 import shutil

ci/init-db.sh

@@ -21,7 +21,7 @@ fi
 # Configure a set of databases in the database server for upgrade tests
 # this list must be in sync with versions in test_db.py:test_upgrade
 set -x
-for SUFFIX in '' _upgrade_110 _upgrade_122 _upgrade_130 _upgrade_150 _upgrade_211; do
+for SUFFIX in '' _upgrade_110 _upgrade_122 _upgrade_130 _upgrade_150 _upgrade_211 _upgrade_311; do
     $SQL_CLIENT "DROP DATABASE jupyterhub${SUFFIX};" 2>/dev/null || true
     $SQL_CLIENT "CREATE DATABASE jupyterhub${SUFFIX} ${EXTRA_CREATE_DATABASE_ARGS:-};"
 done

ci/oldest-dependencies/oldest-dependencies.txt

@@ -0,0 +1,13 @@
+alembic==1.4
+async_generator==1.9
+certipy==0.1.2
+importlib_metadata==3.6; python_version < '3.10'
+jinja2==2.11.0
+jupyter_telemetry==0.1.0
+oauthlib==3.0
+pamela==1.1.0; sys_platform != 'win32'
+prometheus_client==0.5.0
+psutil==5.6.5; sys_platform == 'win32'
+SQLAlchemy==1.4.1
+tornado==5.1
+traitlets==4.3.2

ci/oldest-dependencies/requirements.in

@@ -0,0 +1,20 @@
+# oldest-dependencies.txt is autogenerated.
+# recreate with:
+#     cat requirements.txt | grep '>=' | sed -e 's@>=@==@g' > ci/legacy-env/oldest-dependencies.txt
+-r ./oldest-dependencies.txt
+# then `pip-compile` with Python 3.8
+# below are additional pins to make this a working test env
+# these are extracted from jupyterhub[test]
+beautifulsoup4
+coverage
+playwright
+pytest
+pytest-cov
+pytest-asyncio==0.17.*
+requests-mock
+virtualenv
+
+# and any additional pins to make this a working test env
+# e.g. pinning down a transitive dependency
+notebook==6.*
+markupsafe==2.0.*

ci/oldest-dependencies/requirements.old

@@ -0,0 +1,285 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile --output-file=requirements.old
+#
+alembic==1.4.0
+    # via -r ./oldest-dependencies.txt
+appnope==0.1.3
+    # via
+    #   ipykernel
+    #   ipython
+argon2-cffi==23.1.0
+    # via notebook
+argon2-cffi-bindings==21.2.0
+    # via argon2-cffi
+async-generator==1.9
+    # via -r ./oldest-dependencies.txt
+attrs==23.1.0
+    # via
+    #   jsonschema
+    #   referencing
+backcall==0.2.0
+    # via ipython
+beautifulsoup4==4.12.2
+    # via -r requirements.in
+bleach==6.0.0
+    # via nbconvert
+certifi==2023.7.22
+    # via requests
+certipy==0.1.2
+    # via -r ./oldest-dependencies.txt
+cffi==1.15.1
+    # via
+    #   argon2-cffi-bindings
+    #   cryptography
+charset-normalizer==3.2.0
+    # via requests
+coverage[toml]==7.3.1
+    # via
+    #   -r requirements.in
+    #   pytest-cov
+cryptography==41.0.4
+    # via pyopenssl
+debugpy==1.8.0
+    # via ipykernel
+decorator==5.1.1
+    # via
+    #   ipython
+    #   traitlets
+defusedxml==0.7.1
+    # via nbconvert
+distlib==0.3.7
+    # via virtualenv
+entrypoints==0.4
+    # via
+    #   jupyter-client
+    #   nbconvert
+exceptiongroup==1.1.3
+    # via pytest
+fastjsonschema==2.18.0
+    # via nbformat
+filelock==3.12.4
+    # via virtualenv
+greenlet==2.0.2
+    # via
+    #   playwright
+    #   sqlalchemy
+idna==3.4
+    # via requests
+importlib-metadata==3.6.0 ; python_version < "3.10"
+    # via -r ./oldest-dependencies.txt
+importlib-resources==6.1.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+iniconfig==2.0.0
+    # via pytest
+ipykernel==6.4.2
+    # via notebook
+ipython==7.34.0
+    # via ipykernel
+ipython-genutils==0.2.0
+    # via
+    #   ipykernel
+    #   notebook
+    #   traitlets
+jedi==0.19.0
+    # via ipython
+jinja2==2.11.0
+    # via
+    #   -r ./oldest-dependencies.txt
+    #   nbconvert
+    #   notebook
+jsonschema==4.19.1
+    # via
+    #   jupyter-telemetry
+    #   nbformat
+jsonschema-specifications==2023.7.1
+    # via jsonschema
+jupyter-client==7.2.0
+    # via
+    #   ipykernel
+    #   nbclient
+    #   notebook
+jupyter-core==5.0.0
+    # via
+    #   jupyter-client
+    #   nbconvert
+    #   nbformat
+    #   notebook
+jupyter-telemetry==0.1.0
+    # via -r ./oldest-dependencies.txt
+jupyterlab-pygments==0.2.2
+    # via nbconvert
+mako==1.2.4
+    # via alembic
+markupsafe==2.0.1
+    # via
+    #   -r requirements.in
+    #   jinja2
+    #   mako
+matplotlib-inline==0.1.6
+    # via
+    #   ipykernel
+    #   ipython
+mistune==0.8.4
+    # via nbconvert
+nbclient==0.5.11
+    # via nbconvert
+nbconvert==6.0.7
+    # via notebook
+nbformat==5.3.0
+    # via
+    #   nbclient
+    #   nbconvert
+    #   notebook
+nest-asyncio==1.5.8
+    # via
+    #   jupyter-client
+    #   nbclient
+notebook==6.1.6
+    # via -r requirements.in
+oauthlib==3.0.0
+    # via -r ./oldest-dependencies.txt
+packaging==23.1
+    # via pytest
+pamela==1.1.0 ; sys_platform != "win32"
+    # via -r ./oldest-dependencies.txt
+pandocfilters==1.5.0
+    # via nbconvert
+parso==0.8.3
+    # via jedi
+pexpect==4.8.0
+    # via ipython
+pickleshare==0.7.5
+    # via ipython
+pkgutil-resolve-name==1.3.10
+    # via jsonschema
+platformdirs==3.10.0
+    # via
+    #   jupyter-core
+    #   virtualenv
+playwright==1.38.0
+    # via -r requirements.in
+pluggy==1.3.0
+    # via pytest
+prometheus-client==0.5.0
+    # via
+    #   -r ./oldest-dependencies.txt
+    #   notebook
+prompt-toolkit==3.0.39
+    # via ipython
+ptyprocess==0.7.0
+    # via
+    #   pexpect
+    #   terminado
+pycparser==2.21
+    # via cffi
+pyee==9.0.4
+    # via playwright
+pygments==2.16.1
+    # via
+    #   ipython
+    #   nbconvert
+pyopenssl==23.2.0
+    # via certipy
+pytest==7.4.2
+    # via
+    #   -r requirements.in
+    #   pytest-asyncio
+    #   pytest-cov
+pytest-asyncio==0.17.2
+    # via -r requirements.in
+pytest-cov==4.1.0
+    # via -r requirements.in
+python-dateutil==2.8.2
+    # via
+    #   alembic
+    #   jupyter-client
+python-editor==1.0.4
+    # via alembic
+python-json-logger==2.0.7
+    # via jupyter-telemetry
+pyzmq==25.1.1
+    # via
+    #   jupyter-client
+    #   notebook
+referencing==0.30.2
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+requests==2.31.0
+    # via requests-mock
+requests-mock==1.11.0
+    # via -r requirements.in
+rpds-py==0.10.3
+    # via
+    #   jsonschema
+    #   referencing
+ruamel-yaml==0.17.32
+    # via jupyter-telemetry
+ruamel-yaml-clib==0.2.7
+    # via ruamel-yaml
+send2trash==1.8.2
+    # via notebook
+six==1.16.0
+    # via
+    #   bleach
+    #   python-dateutil
+    #   requests-mock
+    #   traitlets
+soupsieve==2.5
+    # via beautifulsoup4
+sqlalchemy==1.4.1
+    # via
+    #   -r ./oldest-dependencies.txt
+    #   alembic
+terminado==0.13.3
+    # via notebook
+testpath==0.6.0
+    # via nbconvert
+tomli==2.0.1
+    # via
+    #   coverage
+    #   pytest
+tornado==5.1
+    # via
+    #   -r ./oldest-dependencies.txt
+    #   ipykernel
+    #   jupyter-client
+    #   notebook
+    #   terminado
+traitlets==4.3.2
+    # via
+    #   -r ./oldest-dependencies.txt
+    #   ipykernel
+    #   ipython
+    #   jupyter-client
+    #   jupyter-core
+    #   jupyter-telemetry
+    #   matplotlib-inline
+    #   nbclient
+    #   nbconvert
+    #   nbformat
+    #   notebook
+typing-extensions==4.8.0
+    # via
+    #   playwright
+    #   pyee
+urllib3==2.0.5
+    # via requests
+virtualenv==20.24.5
+    # via -r requirements.in
+wcwidth==0.2.6
+    # via prompt-toolkit
+webencodings==0.5.1
+    # via bleach
+zipp==3.17.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

demo-image/Dockerfile

@@ -3,7 +3,7 @@
 # This should only be used for demo or testing and not as a base image to build on.
 #
 # It includes the notebook package and it uses the DummyAuthenticator and the SimpleLocalProcessSpawner.
-ARG BASE_IMAGE=jupyterhub/jupyterhub-onbuild
+ARG BASE_IMAGE=quay.io/jupyterhub/jupyterhub-onbuild
 FROM ${BASE_IMAGE}
 
 # Install the notebook package

demo-image/jupyterhub_config.py

@@ -1,6 +1,6 @@
 # Configuration file for jupyterhub-demo
 
-c = get_config()
+c = get_config()  # noqa
 
 # Use DummyAuthenticator and SimpleSpawner
 c.JupyterHub.spawner_class = "simple"

docs/requirements.txt

@@ -1,13 +1,6 @@
-# We install the jupyterhub package to help autodoc-traits inspect it and
-# generate documentation.
-#
-# FIXME: If there is a way for this requirements.txt file to pass a flag that
-#        the build system can intercept to not build the javascript artifacts,
-#        then do so so. That would mean that installing the documentation can
-#        avoid needing node/npm installed.
-#
---editable .
-
+# docs also require jupyterhub itself to be installed
+# don't depend on it here, as that often results in a duplicate
+# installation of jupyterhub that's already installed
 autodoc-traits
 jupyterhub-sphinx-theme
 myst-parser>=0.19

docs/source/_templates/page.html

@@ -0,0 +1,2 @@
+{%- set _meta = meta | default({}) %}
+{%- extends _meta.page_template | default('!page.html') %}

docs/source/_templates/redoc.html

@@ -0,0 +1,36 @@
+{%- extends "!layout.html" %}
+{# not sure why, but theme CSS prevents scrolling within redoc content
+ # If this were fixed, we could keep the navbar and footer
+ #}
+{% block css %}
+{% endblock css %}
+{% block docs_navbar %}
+{% endblock docs_navbar %}
+{% block footer %}
+{% endblock footer %}
+{# djlint: off #}
+{%- block body_tag -%}<body>{%- endblock body_tag %}
+{# djlint: on #}
+{%- block extrahead %}
+  {{ super() }}
+  <link href="{{ pathto('_static/redoc-fonts.css', 1) }}" rel="stylesheet" />
+  <script src="{{ pathto('_static/redoc.js', 1) }}"></script>
+{%- endblock extrahead %}
+{%- block content %}
+  <redoc id="redoc-spec"></redoc>
+  <script>
+    if (location.protocol === "file:") {
+      document.body.innerText = "Rendered API specification doesn't work with file: protocol. Use sphinx-autobuild to do local builds of the docs, served over HTTP."
+    } else {
+      Redoc.init(
+        "{{ pathto('_static/rest-api.yml', 1) }}", {
+          {
+            meta.redoc_options |
+              default ({})
+          }
+        },
+        document.getElementById("redoc-spec"),
+      );
+    }
+  </script>
+{%- endblock content %}

docs/source/conf.py

@@ -6,14 +6,20 @@ import contextlib
 import datetime
 import io
 import os
+import re
 import subprocess
+from pathlib import Path
+from urllib.request import urlretrieve
 
 from docutils import nodes
+from ruamel.yaml import YAML
 from sphinx.directives.other import SphinxDirective
+from sphinx.util import logging
 
 import jupyterhub
 from jupyterhub.app import JupyterHub
 
+logger = logging.getLogger(__name__)
 # -- Project information -----------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 #
@@ -42,6 +48,10 @@ source_suffix = [".md"]
 # default_role let's use use `foo` instead of ``foo`` in rST
 default_role = "literal"
 
+docs = Path(__file__).parent.parent.absolute()
+docs_source = docs / "source"
+rest_api_yaml = docs_source / "_static" / "rest-api.yml"
+
 
 # -- MyST configuration ------------------------------------------------------
 # ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
@@ -60,6 +70,8 @@ myst_enable_extensions = [
 myst_substitutions = {
     # date example: Dev 07, 2022
     "date": datetime.date.today().strftime("%b %d, %Y").title(),
+    "node_min": "12",
+    "python_min": "3.8",
     "version": jupyterhub.__version__,
 }
 
@@ -119,10 +131,102 @@ class HelpAllDirective(SphinxDirective):
         return [par]
 
 
+class RestAPILinksDirective(SphinxDirective):
+    """Directive to populate link targets for the REST API
+
+    The resulting nodes resolve xref targets,
+    but are not actually rendered in the final result
+    which is handled by a custom template.
+    """
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        targets = []
+        yaml = YAML(typ="safe")
+        with rest_api_yaml.open() as f:
+            api = yaml.load(f)
+        for path, path_spec in api["paths"].items():
+            for method, operation in path_spec.items():
+                operation_id = operation.get("operationId")
+                if not operation_id:
+                    logger.warning(f"No operation id for {method} {path}")
+                    continue
+                # 'id' is the id on the page (must match redoc anchor)
+                # 'name' is the name of the ref for use in our documents
+                target = nodes.target(
+                    ids=[f"operation/{operation_id}"],
+                    names=[f"rest-api-{operation_id}"],
+                )
+                targets.append(target)
+                self.state.document.note_explicit_target(target, target)
+
+        return targets
+
+
+templates_path = ["_templates"]
+
+
+def stage_redoc_js(app, exception):
+    """Download redoc.js to our static files"""
+    if app.builder.name != "html":
+        logger.info(f"Skipping redoc download for builder: {app.builder.name}")
+        return
+
+    out_static = Path(app.builder.outdir) / "_static"
+
+    redoc_version = "2.1.3"
+    redoc_url = (
+        f"https://cdn.redoc.ly/redoc/v{redoc_version}/bundles/redoc.standalone.js"
+    )
+    dest = out_static / "redoc.js"
+    if not dest.exists():
+        logger.info(f"Downloading {redoc_url} -> {dest}")
+        urlretrieve(redoc_url, dest)
+
+    # stage fonts for redoc from google fonts
+    fonts_css_url = "https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
+    fonts_css_file = out_static / "redoc-fonts.css"
+    fonts_dir = out_static / "fonts"
+    fonts_dir.mkdir(exist_ok=True)
+    if not fonts_css_file.exists():
+        logger.info(f"Downloading {fonts_css_url} -> {fonts_css_file}")
+        urlretrieve(fonts_css_url, fonts_css_file)
+
+    # For each font external font URL,
+    # download the font and rewrite to a local URL
+    # The downloaded TTF fonts have license info in their metadata
+    with open(fonts_css_file) as f:
+        fonts_css = f.read()
+
+    fonts_css_changed = False
+    for font_url in re.findall(r'url\((https?[^\)]+)\)', fonts_css):
+        fonts_css_changed = True
+        filename = font_url.rpartition("/")[-1]
+        dest = fonts_dir / filename
+        local_url = str(dest.relative_to(fonts_css_file.parent))
+        fonts_css = fonts_css.replace(font_url, local_url)
+        if not dest.exists():
+            logger.info(f"Downloading {font_url} -> {dest}")
+            urlretrieve(font_url, dest)
+
+    if fonts_css_changed:
+        # rewrite font css with local URLs
+        with open(fonts_css_file, "w") as f:
+            logger.info(f"Rewriting URLs in {fonts_css_file}")
+            f.write(fonts_css)
+
+
 def setup(app):
+    app.connect("build-finished", stage_redoc_js)
     app.add_css_file("custom.css")
     app.add_directive("jupyterhub-generate-config", ConfigDirective)
     app.add_directive("jupyterhub-help-all", HelpAllDirective)
+    app.add_directive("jupyterhub-rest-api-links", RestAPILinksDirective)
 
 
 # -- Read The Docs -----------------------------------------------------------
@@ -131,8 +235,7 @@ def setup(app):
 # pre-requisite steps for "make html" from here if needed.
 #
 if os.environ.get("READTHEDOCS"):
-    docs = os.path.dirname(os.path.dirname(__file__))
-    subprocess.check_call(["make", "metrics", "scopes"], cwd=docs)
+    subprocess.check_call(["make", "metrics", "scopes"], cwd=str(docs))
 
 
 # -- Spell checking ----------------------------------------------------------
@@ -182,12 +285,14 @@ html_context = {
 linkcheck_ignore = [
     r"(.*)github\.com(.*)#",  # javascript based anchors
     r"(.*)/#%21(.*)/(.*)",  # /#!forum/jupyter - encoded anchor edge case
+    r"https?://(.*\.)?example\.(org|com)(/.*)?",  # example links
     r"https://github.com/[^/]*$",  # too many github usernames / searches in changelog
     "https://github.com/jupyterhub/jupyterhub/pull/",  # too many PRs in changelog
     "https://github.com/jupyterhub/jupyterhub/compare/",  # too many comparisons in changelog
     r"https?://(localhost|127.0.0.1).*",  # ignore localhost references in auto-links
-    r".*/rest-api.html#.*",  # ignore javascript-resolved internal rest-api links
-    r"https://jupyter.chameleoncloud.org",  # FIXME: ignore (presumably) short-term SSL issue
+    r"https://linux.die.net/.*",  # linux.die.net seems to block requests from CI with 403 sometimes
+    # don't check links to unpublished advisories
+    r"https://github.com/jupyterhub/jupyterhub/security/advisories/.*",
 ]
 linkcheck_anchors_ignore = [
     "/#!",

docs/source/contributing/setup.md

@@ -12,18 +12,18 @@ development.
 ### Install Python
 
 JupyterHub is written in the [Python](https://python.org) programming language and
-requires you have at least version 3.6 installed locally. If you haven’t
+requires you have at least version {{python_min}} installed locally. If you haven’t
 installed Python before, the recommended way to install it is to use
 [Miniforge](https://github.com/conda-forge/miniforge#download).
 
 ### Install nodejs
 
-[NodeJS 12+](https://nodejs.org/en/) is required for building some JavaScript components.
+[NodeJS {{node_min}}+](https://nodejs.org/en/) is required for building some JavaScript components.
 `configurable-http-proxy`, the default proxy implementation for JupyterHub, is written in Javascript.
 If you have not installed NodeJS before, we recommend installing it in the `miniconda` environment you set up for Python.
 You can do so with `conda install nodejs`.
 
-Many in the Jupyter community use \[`nvm`\](<https://github.com/nvm-sh/nvm>) to
+Many in the Jupyter community use [`nvm`](https://github.com/nvm-sh/nvm) to
 managing node dependencies.
 
 ### Install git
@@ -59,7 +59,7 @@ a more detailed discussion.
    python -V
    ```
 
-   This should return a version number greater than or equal to 3.6.
+   This should return a version number greater than or equal to {{python_min}}.
 
    ```bash
    npm -v
@@ -67,10 +67,10 @@ a more detailed discussion.
 
    This should return a version number greater than or equal to 5.0.
 
-3. Install `configurable-http-proxy` (required to run and test the default JupyterHub configuration) and `yarn` (required to build some components):
+3. Install `configurable-http-proxy` (required to run and test the default JupyterHub configuration):
 
    ```bash
-   npm install -g configurable-http-proxy yarn
+   npm install -g configurable-http-proxy
    ```
 
    If you get an error that says `Error: EACCES: permission denied`, you might need to prefix the command with `sudo`.
@@ -78,7 +78,7 @@ a more detailed discussion.
    If you do not have access to sudo, you may instead run the following commands:
 
    ```bash
-   npm install configurable-http-proxy yarn
+   npm install configurable-http-proxy
    export PATH=$PATH:$(pwd)/node_modules/.bin
    ```
 
@@ -87,7 +87,7 @@ a more detailed discussion.
    If you are using conda you can instead run:
 
    ```bash
-   conda install configurable-http-proxy yarn
+   conda install configurable-http-proxy
    ```
 
 4. Install an editable version of JupyterHub and its requirements for
@@ -98,20 +98,13 @@ a more detailed discussion.
    python3 -m pip install --editable ".[test]"
    ```
 
-5. Set up a database.
-
-   The default database engine is `sqlite` so if you are just trying
-   to get up and running quickly for local development that should be
-   available via [Python](https://docs.python.org/3.5/library/sqlite3.html).
-   See [The Hub's Database](hub-database) for details on other supported databases.
-
-6. You are now ready to start JupyterHub!
+5. You are now ready to start JupyterHub!
 
    ```bash
    jupyterhub
    ```
 
-7. You can access JupyterHub from your browser at
+6. You can access JupyterHub from your browser at
    `http://localhost:8000` now.
 
 Happy developing!
@@ -130,6 +123,14 @@ configuration:
 jupyterhub -f testing/jupyterhub_config.py
 ```
 
+The test configuration enables a few things to make testing easier:
+
+- use 'dummy' authentication and 'simple' spawner
+- named servers are enabled
+- listen only on localhost
+- 'admin' is an admin user, if you want to test the admin page
+- disable caching of static files
+
 The default JupyterHub [authenticator](PAMAuthenticator)
 & [spawner](LocalProcessSpawner)
 require your system to have user accounts for each user you want to log in to
@@ -146,6 +147,29 @@ SimpleLocalProcessSpawner. If you are working on just authenticator-related
 parts, use only SimpleLocalProcessSpawner. Similarly, if you are working on
 just spawner-related parts, use only DummyAuthenticator.
 
+## Building frontend components
+
+The testing configuration file also disables caching of static files,
+which allows you to edit and rebuild these files without restarting JupyterHub.
+
+If you are working on the admin react page, which is in the `jsx` directory, you can run:
+
+```bash
+cd jsx
+npm install
+npm run build:watch
+```
+
+to continuously rebuild the admin page, requiring only a refresh of the page.
+
+If you are working on the frontend SCSS files, you can run the same `build:watch` command
+in the _top level_ directory of the repo:
+
+```bash
+npm install
+npm run build:watch
+```
+
 ## Troubleshooting
 
 This section lists common ways setting up your development environment may
@@ -173,3 +197,46 @@ python3 setup.py js    # fetch updated client-side js
 python3 setup.py css   # recompile CSS from LESS sources
 python3 setup.py jsx   # build React admin app
 ```
+
+### Failed to bind XXX to `http://127.0.0.1:<port>/<path>`
+
+This error can happen when there's already an application or a service using this
+port.
+
+Use the following command to find out which service is using this port.
+
+```bash
+lsof -P -i TCP:<port> -sTCP:LISTEN
+```
+
+If nothing shows up, it likely means there's a system service that uses it but
+your current user cannot list it. Reuse the same command with sudo.
+
+```bash
+sudo lsof -P -i TCP:<port> -sTCP:LISTEN
+```
+
+Depending on the result of the above commands, the most simple solution is to
+configure JupyterHub to use a different port for the service that is failing.
+
+As an example, the following is a frequently seen issue:
+
+`Failed to bind hub to http://127.0.0.1:8081/hub/`
+
+Using the procedure described above, start with:
+
+```bash
+lsof -P -i TCP:8081 -sTCP:LISTEN
+```
+
+and if nothing shows up:
+
+```bash
+sudo lsof -P -i TCP:8081 -sTCP:LISTEN
+```
+
+Finally, depending on your findings, you can apply the following change and start JupyterHub again:
+
+```python
+c.JupyterHub.hub_port = 9081 # Or any other free port
+```

docs/source/explanation/database.md

@@ -82,7 +82,7 @@ Additionally, there is usually _very_ little load on the database itself.
 By far the most taxing activity on the database is the 'list all users' endpoint, primarily used by the [idle-culling service](https://github.com/jupyterhub/jupyterhub-idle-culler).
 Database-based optimizations have been added to make even these operations feasible for large numbers of users:
 
-1. State filtering on [GET /hub/api/users?state=active](../reference/rest-api.html#/default/get_users){.external},
+1. State filtering on [GET /hub/api/users?state=active](rest-api-get-users),
    which limits the number of results in the query to only the relevant subset (added in JupyterHub 1.3), rather than all users.
 2. [Pagination](api-pagination) of all list endpoints, allowing the request of a large number of resources to be more fairly balanced with other Hub activities across multiple requests (added in 2.0).
 
@@ -143,14 +143,14 @@ We recommend using PostgreSQL for production if you are unsure whether to use
 MySQL or PostgreSQL or if you do not have a strong preference.
 There is additional configuration required for MySQL that is not needed for PostgreSQL.
 
-For example, to connect to a postgres database with psycopg2:
+For example, to connect to a PostgreSQL database with psycopg2:
 
-1. install psycopg2: `pip instal psycopg2` (or `psycopg2-binary` to avoid compilation, which is [not recommended for production][psycopg2-binary])
+1. install psycopg2: `pip install psycopg2` (or `psycopg2-binary` to avoid compilation, which is [not recommended for production][psycopg2-binary])
 2. set authentication via environment variables `PGUSER` and `PGPASSWORD`
 3. configure [](JupyterHub.db_url):
 
    ```python
-   c.JupyterHub.db_url = "postgres+psycopg2://my-postgres-server:5432/my-db-name"
+   c.JupyterHub.db_url = "postgresql+psycopg2://my-postgres-server:5432/my-db-name"
    ```
 
 [psycopg2-binary]: https://www.psycopg.org/docs/install.html#psycopg-vs-psycopg-binary

docs/source/explanation/oauth.md

@@ -1,3 +1,5 @@
+(jupyterhub-oauth)=
+
 # JupyterHub and OAuth
 
 JupyterHub uses [OAuth 2](https://oauth.net/2/) as an internal mechanism for authenticating users.

docs/source/explanation/websecurity.md

@@ -16,7 +16,8 @@ works.
 
 JupyterHub is designed to be a _simple multi-user server for modestly sized
 groups_ of **semi-trusted** users. While the design reflects serving
-semi-trusted users, JupyterHub can also be suitable for serving **untrusted** users.
+semi-trusted users, JupyterHub can also be suitable for serving **untrusted** users,
+but **is not suitable for untrusted users** in its default configuration.
 
 As a result, using JupyterHub with **untrusted** users means more work by the
 administrator, since much care is required to secure a Hub, with extra caution on
@@ -52,33 +53,69 @@ ensure that:
     their single-user server;
   - the modification of the configuration of the notebook server
     (the `~/.jupyter` or `JUPYTER_CONFIG_DIR` directory).
+  - unrestricted selection of the base environment (e.g. the image used in container-based Spawners)
 
 If any additional services are run on the same domain as the Hub, the services
 **must never** display user-authored HTML that is neither _sanitized_ nor _sandboxed_
-(e.g. IFramed) to any user that lacks authentication as the author of a file.
+to any user that lacks authentication as the author of a file.
+
+### Sharing access to servers
+
+Because sharing access to servers (via `access:servers` scopes or the sharing feature in JupyterHub 5) by definition means users can serve each other files, enabling sharing is not suitable for untrusted users without also enabling per-user domains.
+
+JupyterHub does not enable any sharing by default.
 
 ## Mitigate security issues
 
 The several approaches to mitigating security issues with configuration
 options provided by JupyterHub include:
 
-### Enable subdomains
+(subdomains)=
+
+### Enable user subdomains
 
 JupyterHub provides the ability to run single-user servers on their own
-subdomains. This means the cross-origin protections between servers has the
-desired effect, and user servers and the Hub are protected from each other. A
-user's single-user server will be at `username.jupyter.mydomain.com`. This also
-requires all user subdomains to point to the same address, which is most easily
-accomplished with wildcard DNS. Since this spreads the service across multiple
-domains, you will need wildcard SSL as well. Unfortunately, for many
-institutional domains, wildcard DNS and SSL are not available. **If you do plan
-to serve untrusted users, enabling subdomains is highly encouraged**, as it
-resolves the cross-site issues.
+domains. This means the cross-origin protections between servers has the
+desired effect, and user servers and the Hub are protected from each other.
+
+**Subdomains are the only way to reliably isolate user servers from each other.**
+
+To enable subdomains, set:
+
+```python
+c.JupyterHub.subdomain_host = "https://jupyter.example.org"
+```
+
+When subdomains are enabled, each user's single-user server will be at e.g. `https://username.jupyter.example.org`.
+This also requires all user subdomains to point to the same address,
+which is most easily accomplished with wildcard DNS, where a single A record points to your server and a wildcard CNAME record points to your A record:
+
+```
+A        jupyter.example.org  192.168.1.123
+CNAME  *.jupyter.example.org  jupyter.example.org
+```
+
+Since this spreads the service across multiple domains, you will likely need wildcard SSL as well,
+matching `*.jupyter.example.org`.
+
+Unfortunately, for many institutional domains, wildcard DNS and SSL may not be available.
+
+We also **strongly encourage** serving JupyterHub and user content on a domain that is _not_ a subdomain of any sensitive content.
+For reasoning, see [GitHub's discussion of moving user content to github.io from \*.github.com](https://github.blog/2013-04-09-yummy-cookies-across-domains/).
+
+**If you do plan to serve untrusted users, enabling subdomains is highly encouraged**,
+as it resolves many security issues, which are difficult to unavoidable when JupyterHub is on a single-domain.
+
+:::{important}
+JupyterHub makes no guarantees about protecting users from each other unless subdomains are enabled.
+
+If you want to protect users from each other, you **_must_** enable per-user domains.
+:::
 
 ### Disable user config
 
 If subdomains are unavailable or undesirable, JupyterHub provides a
-configuration option `Spawner.disable_user_config`, which can be set to prevent
+configuration option `Spawner.disable_user_config = True`, which can be set to prevent
 the user-owned configuration files from being loaded. After implementing this
 option, `PATH`s and package installation are the other things that the
 admin must enforce.
@@ -88,21 +125,24 @@ admin must enforce.
 For most Spawners, `PATH` is not something users can influence, but it's important that
 the Spawner should _not_ evaluate shell configuration files prior to launching the server.
 
-### Isolate packages using virtualenv
+### Isolate packages in a read-only environment
 
-Package isolation is most easily handled by running the single-user server in
-a virtualenv with disabled system-site-packages. The user should not have
-permission to install packages into this environment.
+The user must not have permission to install packages into the environment where the singleuser-server runs.
+On a shared system, package isolation is most easily handled by running the single-user server in
+a root-owned virtualenv with disabled system-site-packages.
+The user must not have permission to install packages into this environment.
+The same principle extends to the images used by container-based deployments.
+If users can select the images in which their servers run, they can disable all security for their own servers.
 
-It is important to note that the control over the environment only affects the
-single-user server, and not the environment(s) in which the user's kernel(s)
+It is important to note that the control over the environment is only required for the
+single-user server, and not the environment(s) in which the users' kernel(s)
 may run. Installing additional packages in the kernel environment does not
 pose additional risk to the web application's security.
 
 ### Encrypt internal connections with SSL/TLS
 
-By default, all communications on the server, between the proxy, hub, and single
--user notebooks are performed unencrypted. Setting the `internal_ssl` flag in
+By default, all communications within JupyterHub—between the proxy, hub, and single
+-user notebooks—are performed unencrypted. Setting the `internal_ssl` flag in
 `jupyterhub_config.py` secures the aforementioned routes. Turning this
 feature on does require that the enabled `Spawner` can use the certificates
 generated by the `Hub` (the default `LocalProcessSpawner` can, for instance).
@@ -116,6 +156,104 @@ Unix permissions to the communication sockets thereby restricting
 communication to the socket owner. The `internal_ssl` option will eventually
 extend to securing the `tcp` sockets as well.
 
+### Mitigating same-origin deployments
+
+While per-user domains are **required** for robust protection of users from each other,
+you can mitigate many (but not all) cross-user issues.
+First, it is critical that users cannot modify their server environments, as described above.
+Second, it is important that users do not have `access:servers` permission to any server other than their own.
+
+If users can access each others' servers, additional security measures must be enabled, some of which come with distinct user-experience costs.
+
+Without the [Same-Origin Policy] (SOP) protecting user servers from each other,
+each user server is considered a trusted origin for requests to each other user server (and the Hub itself).
+Servers _cannot_ meaningfully distinguish requests originating from other user servers,
+because SOP implies a great deal of trust, losing many restrictions applied to cross-origin requests.
+
+That means pages served from each user server can:
+
+1. arbitrarily modify the path in the Referer
+2. make fully authorized requests with cookies
+3. access full page contents served from the hub or other servers via popups
+
+JupyterHub uses distinct xsrf tokens stored in cookies on each server path to attempt to limit requests across.
+This has limitations because not all requests are protected by these XSRF tokens,
+and unless additional measures are taken, the XSRF tokens from other user prefixes may be retrieved.
+
+[Same-Origin Policy]: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy
+
+For example:
+
+- `Content-Security-Policy` header must prohibit popups and iframes from the same origin.
+  The following Content-Security-Policy rules are _insecure_ and readily enable users to access each others' servers:
+
+  - `frame-ancestors: 'self'`
+  - `frame-ancestors: '*'`
+  - `sandbox allow-popups`
+
+- Ideally, pages should use the strictest `Content-Security-Policy: sandbox` available,
+  but this is not feasible in general for JupyterLab pages, which need at least `sandbox allow-same-origin allow-scripts` to work.
+
+The default Content-Security-Policy for single-user servers is
+
+```
+frame-ancestors: 'none'
+```
+
+which prohibits iframe embedding, but not pop-ups.
+
+A more secure Content-Security-Policy that has some costs to user experience is:
+
+```
+frame-ancestors: 'none'; sandbox allow-same-origin allow-scripts
+```
+
+`allow-popups` is not disabled by default because disabling it breaks legitimate functionality, like "Open this in a new tab", and the "JupyterHub Control Panel" menu item.
+To reiterate, the right way to avoid these issues is to enable per-user domains, where none of these concerns come up.
+
+Note: even this level of protection requires administrators maintaining full control over the user server environment.
+If users can modify their server environment, these methods are ineffective, as users can readily disable them.
+
+### Cookie tossing
+
+Cookie tossing is a technique where another server on a subdomain or peer subdomain can set a cookie
+which will be read on another domain.
+This is not relevant unless there are other user-controlled servers on a peer domain.
+
+"Domain-locked" cookies avoid this issue, but have their own restrictions:
+
+- JupyterHub must be served over HTTPS
+- All secure cookies must be set on `/`, not on sub-paths, which means they are shared by all JupyterHub components in a single-domain deployment.
+
+As a result, this option is only recommended when per-user subdomains are enabled,
+to prevent sending all jupyterhub cookies to all user servers.
+
+To enable domain-locked cookies, set:
+
+```python
+c.JupyterHub.cookie_host_prefix_enabled = True
+```
+
+```{versionadded} 4.1
+
+```
+
+### Forced-login
+
+Jupyter servers can share links with `?token=...`.
+JupyterHub prior to 5.0 will accept this request and persist the token for future requests.
+This is useful for enabling admins to create 'fully authenticated' links bypassing login.
+However, it also means users can share their own links that will log other users into their own servers,
+enabling them to serve each other notebooks and other arbitrary HTML, depending on server configuration.
+
+```{versionadded} 4.1
+Setting environment variable `JUPYTERHUB_ALLOW_TOKEN_IN_URL=0` in the single-user environment can opt out of accepting token auth in URL parameters.
+```
+
+```{versionadded} 5.0
+Accepting tokens in URLs is disabled by default, and `JUPYTERHUB_ALLOW_TOKEN_IN_URL=1` environment variable must be set to _allow_ token auth in URL parameters.
+```
+
 ## Security audits
 
 We recommend that you do periodic reviews of your deployment's security. It's

docs/source/faq/troubleshooting.md

@@ -46,13 +46,13 @@ things like inspect other users' servers or modify the user list at runtime).
 ### JupyterHub Docker container is not accessible at localhost
 
 Even though the command to start your Docker container exposes port 8000
-(`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`),
+(`docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub`),
 it is possible that the IP address itself is not accessible/visible. As a result,
 when you try http://localhost:8000 in your browser, you are unable to connect
 even though the container is running properly. One workaround is to explicitly
 tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this
 command:
-`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000`
+`docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000`
 
 ### How can I kill ports from JupyterHub-managed services that have been orphaned?
 
@@ -347,12 +347,12 @@ In order to resolve this issue, there are two potential options.
 
 ### Where do I find Docker images and Dockerfiles related to JupyterHub?
 
-Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/).
-The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/)
+Docker images can be found at the [JupyterHub organization on Quay.io](https://quay.io/organization/jupyterhub).
+The Docker image [jupyterhub/singleuser](https://quay.io/repository/jupyterhub/singleuser)
 provides an example single-user notebook server for use with DockerSpawner.
 
 Additional single-user notebook server images can be found at the [Jupyter
-organization on DockerHub](https://hub.docker.com/r/jupyter/) and information
+organization on Quay.io](https://quay.io/organization/jupyter) and information
 about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks).
 
 ### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner?

docs/source/howto/configuration/config-proxy.md

@@ -79,7 +79,7 @@ server {
     location / {
         proxy_pass http://127.0.0.1:8000;
         proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_host;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 
         # websocket headers

docs/source/howto/configuration/config-user-env.md

@@ -45,7 +45,7 @@ additional packages.
 
 ## Configuring Jupyter and IPython
 
-[Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/config_overview.html)
+[Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/configuring/config_overview.html)
 and [IPython](https://ipython.readthedocs.io/en/stable/development/config.html)
 have their own configuration systems.
 
@@ -212,13 +212,31 @@ By default, the single-user server launches JupyterLab,
 which is based on [Jupyter Server][].
 
 This is the default server when running JupyterHub ≥ 2.0.
-To switch to using the legacy Jupyter Notebook server, you can set the `JUPYTERHUB_SINGLEUSER_APP` environment variable
+To switch to using the legacy Jupyter Notebook server (notebook < 7.0), you can set the `JUPYTERHUB_SINGLEUSER_APP` environment variable
 (in the single-user environment) to:
 
 ```bash
 export JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp'
 ```
 
+:::{note}
+
+```
+JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp'
+```
+
+is only valid for notebook < 7. notebook v7 is based on jupyter-server,
+and the default jupyter-server application must be used.
+Selecting the new notebook UI is no longer a matter of selecting the server app to launch,
+but only the default URL for users to visit.
+To use notebook v7 with JupyterHub, leave the default singleuser app config alone (or specify `JUPYTERHUB_SINGLEUSER_APP=jupyter-server`) and set the default _URL_ for user servers:
+
+```python
+c.Spawner.default_url = '/tree/'
+```
+
+:::
+
 [jupyter server]: https://jupyter-server.readthedocs.io
 [jupyter notebook]: https://jupyter-notebook.readthedocs.io
 

docs/source/howto/rest.md

@@ -24,6 +24,7 @@ such as:
 
 - Checking which users are active
 - Adding or removing users
+- Adding or removing services
 - Stopping or starting single user notebook servers
 - Authenticating services
 - Communicating with an individual Jupyter server's REST API
@@ -98,9 +99,46 @@ In JupyterHub 2.0,
 specific permissions are now defined as '**scopes**',
 and can be assigned both at the user/service level,
 and at the individual token level.
+The previous behavior is represented by the scope `inherit`,
+and is still the default behavior for requesting a token if limited permissions are not specified.
 
 This allows e.g. a user with full admin permissions to request a token with limited permissions.
 
+In JupyterHub 5.0, you can specify scopes for a token when requesting it via the `/hub/tokens` page as a space-separated list.
+In JupyterHub 3.0 and later, you can also request tokens with limited scopes via the JupyterHub API (provided you already have a token!):
+
+```python
+import json
+from urllib.parse import quote
+
+import requests
+
+def request_token(
+    username, *, api_token, scopes=None, expires_in=0, hub_url="http://127.0.0.1:8081"
+):
+    """Request a new token for a user"""
+    request_body = {}
+    if expires_in:
+        request_body["expires_in"] = expires_in
+    if scopes:
+        request_body["scopes"] = scopes
+    url = hub_url.rstrip("/") + f"/hub/api/users/{quote(username)}/tokens"
+    r = requests.post(
+        url,
+        data=json.dumps(request_body),
+        headers={"Authorization": f"token {api_token}"},
+    )
+    if r.status_code >= 400:
+        # extract error message for nicer error messages
+        r.reason = r.json().get("message", r.text)
+    r.raise_for_status()
+    # response is a dict and will include the token itself in the 'token' field,
+    # as well as other fields about the token
+    return r.json()
+
+request_token("myusername", scopes=["list:users"], api_token="abc123")
+```
+
 ## Updating to admin services
 
 ```{note}
@@ -164,7 +202,7 @@ Authorization header.
 ### Use requests
 
 Using the popular Python [requests](https://docs.python-requests.org)
-library, an API GET request is made, and the request sends an API token for
+library, an API GET request is made to [/users](rest-api-get-users), and the request sends an API token for
 authorization. The response contains information about the users, here's example code to make an API request for the users of a JupyterHub deployment
 
 ```python
@@ -182,7 +220,7 @@ r.raise_for_status()
 users = r.json()
 ```
 
-This example provides a slightly more complicated request, yet the
+This example provides a slightly more complicated request (to [/groups/formgrade-data301/users](rest-api-post-group-users)), yet the
 process is very similar:
 
 ```python
@@ -216,7 +254,7 @@ provided by notebook servers managed by JupyterHub if it has the necessary `acce
 
 Pagination is available through the `offset` and `limit` query parameters on
 list endpoints, which can be used to return ideally sized windows of results.
-Here's example code demonstrating pagination on the `GET /users`
+Here's example code demonstrating pagination on the [`GET /users`](rest-api-get-users)
 endpoint to fetch the first 20 records.
 
 ```python
@@ -315,12 +353,18 @@ hub:
 
 With that setting in place, a new named-server is activated like this:
 
+```{parsed-literal}
+[POST /api/users/:username/servers/:servername](rest-api-post-user-server-name)
+```
+
+e.g.
+
 ```bash
 curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverA>"
 curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverB>"
 ```
 
-The same servers can be stopped by substituting `DELETE` for `POST` above.
+The same servers can be [stopped](rest-api-delete-user-server-name) by substituting `DELETE` for `POST` above.
 
 ### Some caveats for using named-servers
 

docs/source/howto/separate-proxy.md

@@ -70,7 +70,7 @@ need to configure the options there.
 ## Docker image
 
 You can use [jupyterhub configurable-http-proxy docker
-image](https://hub.docker.com/r/jupyterhub/configurable-http-proxy/)
+image](https://quay.io/repository/jupyterhub/configurable-http-proxy)
 to run the proxy.
 
 ## See also

docs/source/howto/upgrading-v5.md

@@ -0,0 +1,144 @@
+(upgrading-v5)=
+
+# Upgrading to JupyterHub 5
+
+This document describes the specific considerations.
+For general upgrading tips, see the [docs on upgrading jupyterhub](upgrading).
+
+You can see the [changelog](changelog) for more detailed information.
+
+## Python version
+
+JupyterHub 5 requires Python 3.8.
+Make sure you have at least Python 3.8 in your user and hub environments before upgrading.
+
+## Database upgrades
+
+JupyterHub 5 does have a database schema upgrade,
+so you should backup your database and run `jupyterhub upgrade-db` after upgrading and before starting JupyterHub.
+The updated schema only adds some columns, so is one that should be not too disruptive to roll back if you need to.
+
+## User subdomains
+
+All JupyterHub deployments which care about protecting users from each other are encouraged to enable per-user domains, if possible,
+as this provides the best isolation between user servers.
+
+To enable subdomains, set:
+
+```python
+c.JupyterHub.subdomain_host = "https://myjupyterhub.example.org"
+```
+
+If you were using subdomains before, some user servers and all services will be on different hosts in the default configuration.
+
+JupyterHub 5 allows complete customization of the subdomain scheme via the new {attr}`.JupyterHub.subdomain_hook`,
+and changes the default subdomain scheme.
+.
+
+You can provide a completely custom subdomain scheme, or select one of two default implementations by name: `idna` or `legacy`. `idna` is the default.
+
+The new default behavior can be selected explicitly via:
+
+```python
+c.JupyterHub.subdomain_hook = "idna"
+```
+
+Or to delay any changes to URLs for your users, you can opt-in to the pre-5.0 behavior with:
+
+```python
+c.JupyterHub.subdomain_hook = "legacy"
+```
+
+The key differences of the new `idna` scheme:
+
+- It should always produce valid domains, regardless of username (not true for the legacy scheme when using characters that might need escaping or usernames that are long)
+- each Service gets its own subdomain on `service--` rather than sharing `services.`
+
+Below is a table of examples of users and services with their domains with the old and new scheme, assuming the configuration:
+
+```python
+c.JupyterHub.subdomain_host = "https://jupyter.example.org"
+```
+
+| kind    | name               | legacy                                                     | idna                                                                                                  |
+| ------- | ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| user    | laudna             | `laudna.jupyter.example.org`                               | `laudna.jupyter.example.org`                                                                          |
+| service | bells              | `services.jupyter.example.org`                             | `bells--service.jupyter.example.org`                                                                  |
+| user    | jester@mighty.nein | `jester_40mighty.nein.jupyter.example.org` (may not work!) | `u-jestermi--8037680.jupyter.example.org` (not as pretty, but guaranteed to be valid and not collide) |
+
+## Tokens in URLs
+
+JupyterHub 5 does not accept `?token=...` URLs by default in single-user servers.
+These URLs allow one user to force another to login as them,
+which can be the start of an inter-user attack.
+
+There is a valid use case for producing links which allow starting a fully authenticated session,
+so you may still opt in to this behavior by setting:
+
+```python
+c.Spawner.environment.update({"JUPYTERHUB_ALLOW_TOKEN_IN_URL": "1"})
+```
+
+if you are not concerned about protecting your users from each other.
+If you have subdomains enabled, the threat is substantially reduced.
+
+## Sharing
+
+The big new feature in JupyterHub 5.0 is sharing.
+Check it out in [the sharing docs](sharing-tutorial).
+
+## Authenticator.allow_all and allow_existing_users
+
+Prior to JupyterHub 5, JupyterHub Authenticators had the _implicit_ default behavior to allow any user who successfully authenticates to login **if no users are explicitly allowed** (i.e. `allowed_users` is empty on the base class).
+This behavior was considered a too-permissive default in Authenticators that source large user pools like OAuthenticator, which would accept e.g. all users with a Google account by default.
+As a result, OAuthenticator 16 introduced two configuration options: `allow_all` and `allow_existing_users`.
+
+JupyterHub 5 adopts these options for all Authenticators:
+
+1. `Authenticator.allow_all` (default: False)
+2. `Authenticator.allow_existing_users` (default: True if allowed_users is non-empty, False otherwise)
+
+having the effect that _some_ allow configuration is required for anyone to be able to login.
+If you want to preserve the pre-5.0 behavior with no explicit `allow` configuration, set:
+
+```python
+c.Authenticator.allow_all = True
+```
+
+`allow_existing_users` defaults are meant to be backward-compatible, but you can now _explicitly_ allow or not based on presence in the database by setting `Authenticator.allow_existing_users` to True or False.
+
+:::{seealso}
+
+[Authenticator config docs](authenticators) for details on these and other Authenticator options.
+:::
+
+## Bootstrap 5
+
+JupyterHub uses the CSS framework [bootstrap](https://getbootstrap.com), which is upgraded from 3.4 to 5.3.
+If you don't have any custom HTML templates, you are likely to only see relatively minor aesthetic changes.
+If you have custom HTML templates or spawner options forms, they may need some updating to look right.
+
+See the bootstrap documentation. Since we upgraded two major versions, you might need to look at both v4 and v5 documentation for what has changed since 3.x:
+
+- [migrating to v4](https://getbootstrap.com/docs/4.6/migration/)
+- [migrating to v5](https://getbootstrap.com/docs/5.3/migration/)
+
+If you customized the JupyterHub CSS by recompiling from LESS files, bootstrap migrated to SCSS.
+You can start by autoconverting your LESS to SCSS (it's not that different) with [less2sass](https://github.com/ekryski/less2sass):
+
+```bash
+npm install --global less2scss
+# converts less/foo.less to scss/foo.scss
+less2scss --src ./less --dst ./scss
+```
+
+Bootstrap also allows configuring things with [CSS variables](https://getbootstrap.com/docs/5.3/customize/css-variables/), so depending on what you have customized, you may be able to get away with just adding a CSS file defining variables without rebuilding the whole SCSS.
+
+## groups required with Authenticator.manage_groups
+
+Setting `Authenticator.manage_groups = True` allows the Authenticator to manage group membership by returning `groups` from the authentication model.
+However, this option is available even on Authenticators that do not support it, which led to confusion.
+Starting with JupyterHub 5, if `manage_groups` is True `authenticate` _must_ return a groups field, otherwise an error is raised.
+This prevents confusion when users enable managed groups that is not implemented.
+
+If an Authenticator _does_ support managing groups but was not providing a `groups` field in order to leave membership unmodified, it must specify `"groups": None` to make this explicit instead of implicit (this is backward-compatible).

docs/source/howto/upgrading.md

@@ -14,6 +14,14 @@ JupyterHub is painless, quick and with minimal user interruption.
 
 The steps are discussed in detail, so if you get stuck at any step you can always refer to this guide.
 
+For specific version migrations:
+
+```{toctree}
+:maxdepth: 1
+
+./upgrading-v5
+```
+
 ## Read the Changelog
 
 The [changelog](changelog) contains information on what has

docs/source/rbac/generate-scope-table.py

@@ -13,6 +13,7 @@ The files are:
        This file is JupyterHub's REST API schema. Both a version and the RBAC
        scopes descriptions are updated in it.
 """
+
 import os
 from collections import defaultdict
 from pathlib import Path

docs/source/rbac/scopes.md

@@ -178,6 +178,57 @@ Note that only the {ref}`horizontal filtering <horizontal-filtering-target>` can
 Metascopes `self` and `all`, `<resource>`, `<resource>:<subresource>`, `read:<resource>`, `admin:<resource>`, and `access:<resource>` scopes are predefined and cannot be changed otherwise.
 ```
 
+(access-scopes)=
+
+### Access scopes
+
+An **access scope** is used to govern _access_ to a JupyterHub service or a user's single-user server.
+This means making API requests, or visiting via a browser using OAuth.
+Without the appropriate access scope, a user or token should not be permitted to make requests of the service.
+
+When you attempt to access a service or server authenticated with JupyterHub, it will begin the [oauth flow](jupyterhub-oauth) for issuing a token that can be used to access the service.
+If the user does not have the access scope for the relevant service or server, JupyterHub will not permit the oauth process to complete.
+If oauth completes, the token will have at least the access scope for the service.
+For minimal permissions, this is the _only_ scope granted to tokens issued during oauth by default,
+but can be expanded via {attr}`.Spawner.oauth_client_allowed_scopes` or a service's [`oauth_client_allowed_scopes`](service-credentials) configuration.
+
+:::{seealso}
+[Further explanation of OAuth in JupyterHub](jupyterhub-oauth)
+:::
+
+If a given service or single-user server can be governed by a single boolean "yes, you can use this service" or "no, you can't," or limiting via other existing scopes, access scopes are enough to manage access to the service.
+But you can also further control granular access to servers or services with [custom scopes](custom-scopes), to limit access to particular APIs within the service, e.g. read-only access.
+
+#### Example access scopes
+
+Some example access scopes for services:
+
+access:services
+: access to all services
+
+access:services!service=somename
+: access to the service named `somename`
+
+and for user servers:
+
+access:servers
+: access to all user servers
+
+access:servers!user
+: access to all of a user's _own_ servers (never in _resolved_ scopes, but may be used in configuration)
+
+access:servers!user=name
+: access to all of `name`'s servers
+
+access:servers!group=groupname
+: access to all servers owned by a user in the group `groupname`
+
+access:servers!server
+: access to only the issuing server (only relevant when applied to oauth tokens associated with a particular server, e.g. via the {attr}`Spawner.oauth_client_allowed_scopes` configuration.
+
+access:servers!server=username/
+: access to only `username`'s _default_ server.
+
 (custom-scopes)=
 
 ### Custom scopes
@@ -298,8 +349,24 @@ class MyHandler(HubOAuthenticated, BaseHandler):
 Existing scope filters (`!user=`, etc.) may be applied to custom scopes.
 Custom scope _filters_ are NOT supported.
 
+:::{warning}
+JupyterHub allows you to define custom scopes,
+but it does not enforce that your services apply them.
+
+For example, if you enable read-only access to servers via custom JupyterHub
+(as seen in the `read-only` example),
+it is the administrator's responsibility to enforce that they are applied.
+If you allow users to launch servers without that custom Authorizer,
+read-only permissions will not be enforced, and the default behavior of unrestricted access via the `access:servers` scope will be applied.
+:::
+
 ### Scopes and APIs
 
-The scopes are also listed in the [](jupyterhub-rest-API) documentation. Each API endpoint has a list of scopes which can be used to access the API; if no scopes are listed, the API is not authenticated and can be accessed without any permissions (i.e., no scopes).
+The scopes are also listed in the [](jupyterhub-rest-API) documentation.
+Each API endpoint has a list of scopes which can be used to access the API;
+if no scopes are listed, the API is not authenticated and can be accessed without any permissions (i.e., no scopes).
 
-Listed scopes by each API endpoint reflect the "lowest" permissions required to gain any access to the corresponding API. For example, posting user's activity (_POST /users/:name/activity_) needs `users:activity` scope. If scope `users` is passed during the request, the access will be granted as the required scope is a subscope of the `users` scope. If, on the other hand, `read:users:activity` scope is passed, the access will be denied.
+Listed scopes by each API endpoint reflect the "lowest" permissions required to gain any access to the corresponding API.
+For example, posting user's activity (_POST /users/:name/activity_) needs `users:activity` scope.
+If scope `users` is held by the request, the access will be granted as the required scope is a subscope of the `users` scope.
+If, on the other hand, `read:users:activity` scope is the only scope held, the request will be denied.

docs/source/reference/authenticators.md

@@ -30,7 +30,6 @@ popular services:
 - Globus
 - Google
 - MediaWiki
-- Okpy
 - OpenShift
 
 A [generic implementation](https://github.com/jupyterhub/oauthenticator/blob/master/oauthenticator/generic.py), which you can use for OAuth authentication with any provider, is also available.
@@ -38,14 +37,19 @@ A [generic implementation](https://github.com/jupyterhub/oauthenticator/blob/mas
 ## The Dummy Authenticator
 
 When testing, it may be helpful to use the
-{class}`jupyterhub.auth.DummyAuthenticator`. This allows for any username and
-password unless if a global password has been set. Once set, any username will
+{class}`~.jupyterhub.auth.DummyAuthenticator`. This allows for any username and
+password unless a global password has been set. Once set, any username will
 still be accepted but the correct password will need to be provided.
 
+:::{versionadded} 5.0
+The DummyAuthenticator's default `allow_all` is True,
+unlike most other Authenticators.
+:::
+
 ## Additional Authenticators
 
-A partial list of other authenticators is available on the
-[JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+Additional authenticators can be found on GitHub
+by searching for [topic:jupyterhub topic:authenticator](https://github.com/search?q=topic%3Ajupyterhub%20topic%3Aauthenticator&type=repositories).
 
 ## Technical Overview of Authentication
 
@@ -55,9 +59,9 @@ The base authenticator uses simple username and password authentication.
 
 The base Authenticator has one central method:
 
-#### Authenticator.authenticate method
+#### Authenticator.authenticate
 
-    Authenticator.authenticate(handler, data)
+{meth}`.Authenticator.authenticate`
 
 This method is passed the Tornado `RequestHandler` and the `POST data`
 from JupyterHub's login form. Unless the login form has been customized,
@@ -66,17 +70,24 @@ from JupyterHub's login form. Unless the login form has been customized,
 - `username`
 - `password`
 
-The `authenticate` method's job is simple:
+If authentication is successful the `authenticate` method must return either:
 
-- return the username (non-empty str) of the authenticated user if
-  authentication is successful
-- return `None` otherwise
+- the username (non-empty str) of the authenticated user
+- or a dictionary with fields:
+  - `name`: the username
+  - `admin`: optional, a boolean indicating whether the user is an admin.
+    In most cases it is better to use fine grained [RBAC permissions](rbac) instead of giving users full admin privileges.
+  - `auth_state`: optional, a dictionary of [auth state that will be persisted](authenticator-auth-state)
+  - `groups`: optional, a list of JupyterHub [group memberships](authenticator-groups)
+
+Otherwise, it must return `None`.
 
 Writing an Authenticator that looks up passwords in a dictionary
 requires only overriding this one method:
 
 ```python
-from IPython.utils.traitlets import Dict
+from secrets import compare_digest
+from traitlets import Dict
 from jupyterhub.auth import Authenticator
 
 class DictionaryAuthenticator(Authenticator):
@@ -86,8 +97,14 @@ class DictionaryAuthenticator(Authenticator):
     )
 
     async def authenticate(self, handler, data):
-        if self.passwords.get(data['username']) == data['password']:
-            return data['username']
+        username = data["username"]
+        password = data["password"]
+        check_password = self.passwords.get(username, "")
+        # always call compare_digest, for timing attacks
+        if compare_digest(check_password, password) and username in self.passwords:
+            return username
+        else:
+            return None
 ```
 
 #### Normalize usernames
@@ -131,7 +148,7 @@ To only allow usernames that start with 'w':
 c.Authenticator.username_pattern = r'w.*'
 ```
 
-### How to write a custom authenticator
+## How to write a custom authenticator
 
 You can use custom Authenticator subclasses to enable authentication
 via other mechanisms. One such example is using [GitHub OAuth][].
@@ -143,11 +160,6 @@ and {meth}`.Authenticator.post_spawn_stop`, are hooks that can be used to do
 auth-related startup (e.g. opening PAM sessions) and cleanup
 (e.g. closing PAM sessions).
 
-See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
-
-If you are interested in writing a custom authenticator, you can read
-[this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
-
 ### Registering custom Authenticators via entry points
 
 As of JupyterHub 1.0, custom authenticators can register themselves via
@@ -183,6 +195,168 @@ Additionally, configurable attributes for your authenticator will
 appear in jupyterhub help output and auto-generated configuration files
 via `jupyterhub --generate-config`.
 
+(authenticator-allow)=
+
+### Allowing access
+
+When dealing with logging in, there are generally two _separate_ steps:
+
+authentication
+: identifying who is trying to log in, and
+
+authorization
+: deciding whether an authenticated user is allowed to access your JupyterHub
+
+{meth}`Authenticator.authenticate` is responsible for authenticating users.
+It is perfectly fine in the simplest cases for `Authenticator.authenticate` to be responsible for authentication _and_ authorization,
+in which case `authenticate` may return `None` if the user is not authorized.
+
+However, Authenticators also have two methods, {meth}`~.Authenticator.check_allowed` and {meth}`~.Authenticator.check_blocked_users`, which are called after successful authentication to further check if the user is allowed.
+
+If `check_blocked_users()` returns False, authorization stops and the user is not allowed.
+
+If `Authenticator.allow_all` is True OR `check_allowed()` returns True, authorization proceeds.
+
+:::{versionadded} 5.0
+{attr}`.Authenticator.allow_all` and {attr}`.Authenticator.allow_existing_users` are new in JupyterHub 5.0.
+
+By default, `allow_all` is False,
+which is a change from pre-5.0, where `allow_all` was implicitly True if `allowed_users` was empty.
+:::
+
+### Overriding `check_allowed`
+
+:::{versionchanged} 5.0
+`check_allowed()` is **not called** if `allow_all` is True.
+:::
+
+:::{versionchanged} 5.0
+Starting with 5.0, `check_allowed()` should **NOT** return True if no allow config
+is specified (`allow_all` should be used instead).
+
+:::
+
+The base implementation of {meth}`~.Authenticator.check_allowed` checks:
+
+- if username is in the `allowed_users` set, return True
+- else return False
+
+:::{versionchanged} 5.0
+Prior to 5.0, this would also return True if `allowed_users` was empty.
+
+For clarity, this is no longer the case. A new `allow_all` property (default False) has been added which is checked _before_ calling `check_allowed`.
+If `allow_all` is True, this takes priority over `check_allowed`, which will be ignored.
+
+If your Authenticator subclass similarly returns True when no allow config is defined,
+this is fully backward compatible for your users, but means `allow_all = False` has no real effect.
+
+You can make your Authenticator forward-compatible with JupyterHub 5 by defining `allow_all` as a boolean config trait on your class:
+
+```python
+class MyAuthenticator(Authenticator):
+
+    # backport allow_all from JupyterHub 5
+    allow_all = Bool(False, config=True)
+
+    def check_allowed(self, username, authentication):
+        if self.allow_all:
+            # replaces previous "if no auth config"
+            return True
+        ...
+```
+
+:::
+
+If an Authenticator defines additional sources of `allow` configuration,
+such as membership in a group or other information,
+it should override `check_allowed` to account for this.
+
+:::{note}
+`allow_` configuration should generally be _additive_,
+i.e. if access is granted by _any_ allow configuration,
+a user should be authorized.
+
+JupyterHub recommends that Authenticators applying _restrictive_ configuration should use names like `block_` or `require_`,
+and check this during `check_blocked_users` or `authenticate`, not `check_allowed`.
+:::
+
+In general, an Authenticator's skeleton should look like:
+
+```python
+class MyAuthenticator(Authenticator):
+    # backport allow_all for compatibility with JupyterHub < 5
+    allow_all = Bool(False, config=True)
+    require_something = List(config=True)
+    allowed_something = Set()
+
+    def authenticate(self, data, handler):
+        ...
+        if success:
+            return {"username": username, "auth_state": {...}}
+        else:
+            return None
+
+    def check_blocked_users(self, username, authentication=None):
+        """Apply _restrictive_ configuration"""
+
+        if self.require_something and not has_something(username, self.request_):
+            return False
+        # repeat for each restriction
+        if restriction_defined and restriction_not_met:
+            return False
+        return super().check_blocked_users(self, username, authentication)
+
+    def check_allowed(self, username, authentication=None):
+        """Apply _permissive_ configuration
+
+        Only called if check_blocked_users returns True
+        AND allow_all is False
+        """
+        if self.allow_all:
+            # check here to backport allow_all behavior
+            # from JupyterHub 5
+            # this branch will never be taken with jupyterhub >=5
+            return True
+        if self.allowed_something and user_has_something(username):
+            return True
+        # repeat for each allow
+        if allow_config and allow_met:
+            return True
+        # should always have this at the end
+        if self.allowed_users and username in self.allowed_users:
+            return True
+        # do not call super!
+        # super().check_allowed is not safe with JupyterHub < 5.0,
+        # as it will return True if allowed_users is empty
+        return False
+```
+
+Key points:
+
+- `allow_all` is backported from JupyterHub 5, for consistent behavior in all versions of JupyterHub (optional)
+- restrictive configuration is checked in `check_blocked_users`
+- if any restriction is not met, `check_blocked_users` returns False
+- permissive configuration is checked in `check_allowed`
+- if any `allow` condition is met, `check_allowed` returns True
+
+So the logical expression for a user being authorized should look like:
+
+> if ALL restrictions are met AND ANY admissions are met: user is authorized
+
+#### Custom error messages
+
+Any of these authentication and authorization methods may raise a `web.HTTPError` Exception
+
+```python
+from tornado import web
+
+raise web.HTTPError(403, "informative message")
+```
+
+if you want to show a more informative login failure message rather than the generic one.
+
+(authenticator-auth-state)=
+
 ### Authentication state
 
 JupyterHub 0.8 adds the ability to persist state related to authentication,
@@ -284,7 +458,7 @@ c.Authenticator.manage_groups = True
 to enable this behavior.
 The default is False for Authenticators that ship with JupyterHub,
 but may be True for custom Authenticators.
-Check your Authenticator's documentation for manage_groups support.
+Check your Authenticator's documentation for `manage_groups` support.
 
 If True, {meth}`.Authenticator.authenticate` and {meth}`.Authenticator.refresh_user` may include a field `groups`
 which is a list of group names the user should be a member of:
@@ -295,7 +469,51 @@ which is a list of group names the user should be a member of:
 - If `None` is returned, no changes are made to the user's group membership
 
 If authenticator-managed groups are enabled,
-all group-management via the API is disabled.
+all group-management via the API is disabled,
+and roles cannot be specified with `load_groups` traitlet.
+
+(authenticator-roles)=
+
+## Authenticator-managed roles
+
+:::{versionadded} 5.0
+:::
+
+Some identity providers may have their own concept of role membership that you would like to preserve in JupyterHub.
+This is now possible with {attr}`.Authenticator.manage_roles`.
+
+You can set the config:
+
+```python
+c.Authenticator.manage_roles = True
+```
+
+to enable this behavior.
+The default is False for Authenticators that ship with JupyterHub,
+but may be True for custom Authenticators.
+Check your Authenticator's documentation for `manage_roles` support.
+
+If True, {meth}`.Authenticator.authenticate` and {meth}`.Authenticator.refresh_user` may include a field `roles`
+which is a list of roles that user should be assigned to:
+
+- User will be assigned each role in the list
+- User will be revoked roles not in the list (but they may still retain the role privileges if they inherit the role from their group)
+- Any roles not already present in the database will be created
+- Attributes of the roles (`description`, `scopes`, `groups`, `users`, and `services`) will be updated if given
+- If `None` is returned, no changes are made to the user's roles
+
+If authenticator-managed roles are enabled,
+all role-management via the API is disabled,
+and roles cannot be assigned to groups nor users via `load_roles` traitlet
+(roles can still be created via `load_roles` or assigned to services).
+
+When an authenticator manages roles, the initial roles and role assignments
+can be loaded from role specifications returned by the {meth}`.Authenticator.load_managed_roles()` method.
+
+The authenticator-manged roles and role assignment will be deleted after restart if:
+
+- {attr}`.Authenticator.reset_managed_roles_on_startup` is set to `True`, and
+- the roles and role assignments are not included in the initial set of roles returned by the {meth}`.Authenticator.load_managed_roles()` method.
 
 ## pre_spawn_start and post_spawn_stop hooks
 

docs/source/reference/gallery-jhub-deployments.md

@@ -16,8 +16,6 @@ Please submit pull requests to update information or to add new institutions or
 
 - [BIDS - Berkeley Institute for Data Science](https://bids.berkeley.edu/)
 
-  - [Teaching with Jupyter notebooks and JupyterHub](https://bids.berkeley.edu/resources/videos/teaching-ipythonjupyter-notebooks-and-jupyterhub)
-
 - [Data 8](http://data8.org/)
 
   - [GitHub organization](https://github.com/data-8)
@@ -93,6 +91,14 @@ Within CERN, there are two noteworthy JupyterHub deployments in operation:
     - log troubleshooting
     - Profiles in IPython Clusters tab
 
+### ETH Zurich
+
+[ETH Zurich](https://ethz.ch/en.html), (Federal Institute of Technology Zurich), is a public research university in Zürich, Switzerland, with focus on science, technology, engineering, and mathematics, although its 16 departments span a variety of disciplines and subjects.
+
+The [Educational Development and Technology](https://ethz.ch/en/the-eth-zurich/organisation/departments/educational-development-and-technology.html) unit provides JupyterHub exclusively for teaching and learning, integrated in the learning management system [Moodle](https://ethz.ch/staffnet/en/teaching/academic-support/it-services-teaching/teaching-applications/moodle-service.html). Each course gets its individually configured JupyterHub environment deployed on a on-premise Kubernetes cluster.
+
+- [ETH JupyterHub](https://ethz.ch/staffnet/en/teaching/academic-support/it-services-teaching/teaching-applications/jupyterhub.html) for teaching and learning
+
 ### George Washington University
 
 - [JupyterHub](https://go.gwu.edu/jupyter) with university single-sign-on. Deployed early 2017.
@@ -188,6 +194,12 @@ Within CERN, there are two noteworthy JupyterHub deployments in operation:
 
 - [Deploying JupyterHub on Hadoop](https://jupyterhub-on-hadoop.readthedocs.io)
 
+### Sirepo
+
+- Sirepo is an online Computer-Aided Engineering gateway that contains a JupyterHub instance. Sirepo is provided at no cost for community use, but users must request login access.
+- [Sirepo.com](https://www.sirepo.com)
+- [Sirepo Jupyter](https://www.sirepo.com/jupyter)
+
 ## Miscellaneous
 
 - https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1

docs/source/reference/index.md

@@ -21,7 +21,9 @@ services
 urls
 event-logging
 monitoring
+sharing
 gallery-jhub-deployments
 changelog
+rest-api
 api/index.md
 ```

docs/source/reference/monitoring.md

@@ -18,3 +18,17 @@ tool like [Grafana](https://grafana.com).
 
 /reference/metrics
 ```
+
+## Customizing the metrics prefix
+
+JupyterHub metrics all have a `jupyterhub_` prefix.
+As of JupyterHub 5.0, this can be overridden with `$JUPYTERHUB_METRICS_PREFIX` environment variable
+in the Hub's environment.
+
+For example,
+
+```bash
+export JUPYTERHUB_METRICS_PREFIX=jupyterhub_prod
+```
+
+would result in the metric `jupyterhub_prod_active_users`, etc.

docs/source/reference/rest-api.md

@@ -1,33 +1,25 @@
-<!---
-This doc is part of the API references section of the References documentation.
---->
+---
+page_template: redoc.html
+# see: https://redocly.com/docs/redoc/config/ for options
+redoc_options:
+  hideHostname: true
+  hideLoading: true
+---
 
 (jupyterhub-rest-API)=
 
 # JupyterHub REST API
 
-Below is an interactive view of JupyterHub's OpenAPI specification.
+NOTE: The contents of this markdown file are not used,
+this page is entirely generated from `_templates/redoc.html` and `_static/rest-api.yml`
 
-<!-- client-rendered openapi UI copied from FastAPI -->
+REST API methods can be linked by their operationId in rest-api.yml,
+prefixed with `rest-api-`, e.g.
 
-<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
-<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.1/swagger-ui-bundle.js"></script>
-<!-- `SwaggerUIBundle` is now available on the page -->
+```markdown
+you cat [GET /api/users](rest-api-get-users)
+```
 
-<!-- render the ui here -->
-<div id="openapi-ui"></div>
+```{jupyterhub-rest-api-links}
 
-<script>
-const ui = SwaggerUIBundle({
-  url: '../_static/rest-api.yml',
-  dom_id: '#openapi-ui',
-  presets: [
-    SwaggerUIBundle.presets.apis,
-    SwaggerUIBundle.SwaggerUIStandalonePreset
-  ],
-  layout: "BaseLayout",
-  deepLinking: true,
-  showExtensions: true,
-  showCommonExtensions: true,
-});
-</script>
+```

docs/source/reference/services.md

@@ -4,20 +4,19 @@
 
 ## Definition of a Service
 
-When working with JupyterHub, a **Service** is defined as a process that interacts
-with the Hub's REST API. A Service may perform a specific
-action or task. For example, the following tasks can each be a unique Service:
+When working with JupyterHub, a **Service** is defined as something (usually a process) that can interact with the Hub's REST API.
+A Service may perform a specific action or task.
+For example, the following tasks can each be a unique Service:
 
-- shutting down individuals' single user notebook servers that have been idle
-  for some time
-- registering additional web servers which should use the Hub's authentication
-  and be served behind the Hub's proxy.
+- shutting down individuals' single user notebook servers that have been idle for some time
+- an additional web application which uses the Hub as an OAuth provider to authenticate and authorize user access
+- a script run once in a while, which performs any API action
+- automating requests to running user servers, such as activity data collection
 
-Two key features help define a Service:
+Two key features help differentiate Services:
 
 - Is the Service **managed** by JupyterHub?
-- Does the Service have a web server that should be added to the proxy's
-  table?
+- Does the Service have a web server that should be added to the proxy's table?
 
 Currently, these characteristics distinguish two types of Services:
 
@@ -30,24 +29,32 @@ Currently, these characteristics distinguish two types of Services:
 A Service may have the following properties:
 
 - `name: str` - the name of the service
-- `admin: bool (default - false)` - whether the service should have
-  administrative privileges
-- `url: str (default - None)` - The URL where the service is/should be. If a
-  url is specified for where the Service runs its own web server,
-  the service will be added to the proxy at `/services/:name`
-- `api_token: str (default - None)` - For Externally-Managed Services you need to specify
-  an API token to perform API requests to the Hub
+- `url: str (default - None)` - The URL where the service should be running (from the proxy's perspective).
+  Typically a localhost URL for Hub-managed services.
+  If a url is specified,
+  the service will be added to the proxy at `/services/:name`.
+- `api_token: str (default - None)` - For Externally-Managed Services,
+  you need to specify an API token to perform API requests to the Hub.
+  For Hub-managed services, this token is generated at startup,
+  and available via `$JUPYTERHUB_API_TOKEN`.
+  For OAuth services, this is the client secret.
 - `display: bool (default - True)` - When set to true, display a link to the
-  service's URL under the 'Services' dropdown in user's hub home page.
-
+  service's URL under the 'Services' dropdown in users' hub home page.
+  Only has an effect if `url` is also specified.
 - `oauth_no_confirm: bool (default - False)` - When set to true,
   skip the OAuth confirmation page when users access this service.
-
   By default, when users authenticate with a service using JupyterHub,
   they are prompted to confirm that they want to grant that service
   access to their credentials.
   Skipping the confirmation page is useful for admin-managed services that are considered part of the Hub
   and shouldn't need extra prompts for login.
+- `oauth_client_id: str (default - 'service-$name')` -
+  This never needs to be set, but you can specify a service's OAuth client id.
+  It must start with `service-`.
+- `oauth_redirect_uri: str (default: '/services/:name/oauth_redirect')` -
+  Set the OAuth redirect URI.
+  Required if the redirect URI differs from the default or the service is not to be added to the proxy at `/services/:name`
+  (i.e. `url` is not set, but there is still a public web service using OAuth).
 
 If a service is also to be managed by the Hub, it has a few extra options:
 
@@ -55,19 +62,19 @@ If a service is also to be managed by the Hub, it has a few extra options:
   externally. - If a command is specified for launching the Service, the Service will
   be started and managed by the Hub.
 - `environment: dict` - additional environment variables for the Service.
-- `user: str` - the name of a system user to manage the Service. If
-  unspecified, run as the same user as the Hub.
+- `user: str` - the name of a system user to manage the Service.
+  If unspecified, run as the same user as the Hub.
 
 ## Hub-Managed Services
 
 A **Hub-Managed Service** is started by the Hub, and the Hub is responsible
-for the Service's actions. A Hub-Managed Service can only be a local
+for the Service's operation. A Hub-Managed Service can only be a local
 subprocess of the Hub. The Hub will take care of starting the process and
 restart the service if the service stops.
 
-While Hub-Managed Services share some similarities with notebook Spawners,
+While Hub-Managed Services share some similarities with single-user server Spawners,
 there are no plans for Hub-Managed Services to support the same spawning
-abstractions as a notebook Spawner.
+abstractions as a Spawner.
 
 If you wish to run a Service in a Docker container or other deployment
 environments, the Service can be registered as an
@@ -80,7 +87,7 @@ the Service. For example, a 'cull idle' notebook server task configured as a
 Hub-Managed Service would include:
 
 - the Service name,
-- admin permissions, and
+- permissions to see when users are active, and to stop servers
 - the `command` to launch the Service which will cull idle servers after a
   timeout interval
 
@@ -131,6 +138,14 @@ JUPYTERHUB_OAUTH_SCOPES:   JSON-serialized list of scopes to use for allowing ac
                            (deprecated in 3.0, use JUPYTERHUB_OAUTH_ACCESS_SCOPES).
 JUPYTERHUB_OAUTH_ACCESS_SCOPES: JSON-serialized list of scopes to use for allowing access to the service (new in 3.0).
 JUPYTERHUB_OAUTH_CLIENT_ALLOWED_SCOPES: JSON-serialized list of scopes that can be requested by the oauth client on behalf of users (new in 3.0).
+JUPYTERHUB_PUBLIC_URL: the public URL of the service,
+  e.g. `https://jupyterhub.example.org/services/name/`.
+  Empty if no public URL is specified (default).
+  Will be available if subdomains are configured.
+JUPYTERHUB_PUBLIC_HUB_URL: the public URL of JupyterHub as a whole,
+  e.g. `https://jupyterhub.example.org/`.
+  Empty if no public URL is specified (default).
+  Will be available if subdomains are configured.
 ```
 
 For the previous 'cull idle' Service example, these environment variables
@@ -156,8 +171,8 @@ to perform its API requests. Each Externally-Managed Service will need a
 unique API token, because the Hub authenticates each API request and the API
 token is used to identify the originating Service or user.
 
-A configuration example of an Externally-Managed Service with admin access and
-running its own web server is:
+A configuration example of an Externally-Managed Service running its own web
+server is:
 
 ```python
 c.JupyterHub.services = [
@@ -174,6 +189,149 @@ c.JupyterHub.services = [
 In this case, the `url` field will be passed along to the Service as
 `JUPYTERHUB_SERVICE_URL`.
 
+(service-credentials)=
+
+## Service credentials
+
+A service has direct access to the Hub API via its `api_token`.
+Exactly what actions the service can take are governed by the service's [role assignments](define-role-target):
+
+```python
+c.JupyterHub.services = [
+    {
+        "name": "user-lister",
+        "command": ["python3", "/path/to/user-lister"],
+    }
+]
+
+c.JupyterHub.load_roles = [
+    {
+        "name": "list-users",
+        "scopes": ["list:users", "read:users"],
+        "services": ["user-lister"]
+    }
+]
+```
+
+When a service has a configured URL or explicit `oauth_client_id` or `oauth_redirect_uri`, it can operate as an [OAuth client](jupyterhub-oauth).
+When a user visits an oauth-authenticated service,
+completion of authentication results in issuing an oauth token.
+
+This token is:
+
+- owned by the authenticated user
+- associated with the oauth client of the service
+- governed by the service's `oauth_client_allowed_scopes` configuration
+
+This token enables the service to act _on behalf of_ the user.
+
+When an oauthenticated service makes a request to the Hub (or other Hub-authenticated service), it has two credentials available to authenticate the request:
+
+- the service's own `api_token`, which acts _as_ the service,
+  and is governed by the service's own role assignments.
+- the user's oauth token issued to the service during the oauth flow,
+  which acts _as_ the user.
+
+Choosing which one to use depends on "who" should be considered taking the action represented by the request.
+
+A service's own permissions governs how it can act without any involvement of a user.
+The service's `oauth_client_allowed_scopes` configuration allows individual users to _delegate_ permission for the service to act on their behalf.
+This allows services to have little to no permissions of their own,
+but allow users to take actions _via_ the service,
+using their own credentials.
+
+An example of such a service would be a web application for instructors,
+presenting a dashboard of actions which can be taken for students in their courses.
+The service would need no permission to do anything with the JupyterHub API on its own,
+but it could employ the user's oauth credentials to list users,
+manage student servers, etc.
+
+This service might look like:
+
+```python
+c.JupyterHub.services = [
+    {
+        "name": "grader-dashboard",
+        "command": ["python3", "/path/to/grader-dashboard"],
+        "url": "http://127.0.0.1:12345",
+        "oauth_client_allowed_scopes": [
+            "list:users",
+            "read:users",
+        ]
+    }
+]
+
+c.JupyterHub.load_roles = [
+    {
+        "name": "grader",
+        "scopes": [
+            "list:users!group=class-a",
+            "read:users!group=class-a",
+            "servers!group=class-a",
+            "access:servers!group=class-a",
+            "access:services",
+        ],
+        "groups": ["graders"]
+    }
+]
+```
+
+In this example, the `grader-dashboard` service does not have permission to take any actions with the Hub API on its own because it has not been assigned any role.
+But when a grader accesses the service,
+the dashboard will have a token with permission to list and read information about any users that the grader can access.
+The dashboard will _not_ have permission to do additional things as the grader.
+
+The dashboard will be able to:
+
+- list users in class A (`list:users!group=class-a`)
+- read information about users in class A (`read:users!group=class-a`)
+
+The dashboard will _not_ be able to:
+
+- start, stop, or access user servers (`servers`, `access:servers`), even though the grader has this permission (it's not in `oauth_client_allowed_scopes`)
+- take any action without the grader granting permission via oauth
+
+## Adding or removing services at runtime
+
+Only externally-managed services can be added at runtime by using JupyterHub’s REST API.
+
+### Add a new service
+
+To add a new service, send a POST request to this endpoint
+
+```
+POST /hub/api/services/:servicename
+```
+
+**Required scope: `admin:services`**
+
+**Payload**: The payload should contain the definition of the service to be created. The endpoint supports the same properties as externally-managed services defined in the config file.
+
+**Possible responses**
+
+- `201 Created`: The service and related objects are created (and started in case of a Hub-managed one) successfully.
+- `400 Bad Request`: The payload is invalid or JupyterHub can not create the service.
+- `409 Conflict`: The service with the same name already exists.
+
+### Remove an existing service
+
+To remove an existing service, send a DELETE request to this endpoint
+
+```
+DELETE /hub/api/services/:servicename
+```
+
+**Required scope: `admin:services`**
+
+**Payload**: `None`
+
+**Possible responses**
+
+- `200 OK`: The service and related objects are removed (and stopped in case of a Hub-managed one) successfully.
+- `400 Bad Request`: JupyterHub can not remove the service.
+- `404 Not Found`: The requested service does not exist.
+- `405 Not Allowed`: The requested service is created from the config file, it can not be removed at runtime.
+
 ## Writing your own Services
 
 When writing your own services, you have a few decisions to make (in addition
@@ -237,16 +395,14 @@ There are two levels of authentication with the Hub:
   This should be used for any service that serves pages that should be visited with a browser.
 
 To use HubAuth, you must set the `.api_token` instance variable. This can be
-done either programmatically when constructing the class, or via the
+done via the HubAuth constructor, direct assignment to a HubAuth object, or via the
 `JUPYTERHUB_API_TOKEN` environment variable. A number of the examples in the
 root of the jupyterhub git repository set the `JUPYTERHUB_API_TOKEN` variable
-so consider having a look at those for futher reading
+so consider having a look at those for further reading
 ([cull-idle](https://github.com/jupyterhub/jupyterhub/tree/master/examples/cull-idle),
 [external-oauth](https://github.com/jupyterhub/jupyterhub/tree/master/examples/external-oauth),
 [service-notebook](https://github.com/jupyterhub/jupyterhub/tree/master/examples/service-notebook)
-and [service-whoiami](https://github.com/jupyterhub/jupyterhub/tree/master/examples/service-whoami))
-
-(TODO: Where is this API TOKen set?)
+and [service-whoami](https://github.com/jupyterhub/jupyterhub/tree/master/examples/service-whoami))
 
 Most of the logic for authentication implementation is found in the
 {meth}`.HubAuth.user_for_token` methods,
@@ -299,7 +455,7 @@ for more details.
 ### Authenticating tornado services with JupyterHub
 
 Since most Jupyter services are written with tornado,
-we include a mixin class, [`HubOAuthenticated`][huboauthenticated],
+we include a mixin class, {class}`.HubOAuthenticated`,
 for quickly authenticating your own tornado services with JupyterHub.
 
 Tornado's {py:func}`~.tornado.web.authenticated` decorator calls a Handler's {py:meth}`~.tornado.web.RequestHandler.get_current_user`

docs/source/reference/sharing.md

@@ -0,0 +1,402 @@
+(sharing-reference)=
+
+# Sharing access to user servers
+
+In order to make use of features like JupyterLab's real-time collaboration (RTC), multiple users must have access to a single server.
+There are a few ways to do this, but ultimately both users must have the appropriate `access:servers` scope.
+Prior to JupyterHub 5.0, this could only be granted via static role assignments in JupyterHub configuration.
+JupyterHub 5.0 adds the concept of a 'share', allowing _users_ to grant each other limited access to their servers.
+
+:::{seealso}
+Documentation on [roles and scopes](rbac) for more details on how permissions work in JupyterHub, and in particular [access scopes](access-scopes).
+:::
+
+In JupyterHub, shares:
+
+1. are 'granted' to a user or group
+2. grant only limited permissions (e.g. only 'access' or access and start/stop)
+3. may be revoked by anyone with the `shares` permissions
+4. may always be revoked by the shared-with user or group
+
+Additionally a "share code" is a random string, which has all the same properties as a Share aside from the user or group.
+The code can be exchanged for actual sharing permission, to enable the pattern of sharing permissions without needing to know the username(s) of who you'd like to share with (e.g. email a link).
+
+There is not yet _UI_ to create shares, but they can be managed via JupyterHub's [REST API](jupyterhub-rest-api).
+
+In general, with shares you can:
+
+1. access other users' servers
+2. grant access to your servers
+3. see servers shared with you
+4. review and revoke permissions for servers you manage
+
+## Enable sharing
+
+For safety, users do not have permission to share access to their servers by default.
+To grant this permission, a user must have the `shares` scope for their servers.
+To grant all users permission to share access to their servers:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        "scopes": ["self", "shares!user"],
+    },
+]
+```
+
+With this, only the sharing via invitation code described below will be available.
+
+Additionally, to share access with a **specific user or group** (more below),
+a user must have permission to read that user or group's name.
+To enable the _full_ sharing API for all users:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        "scopes": ["self", "shares!user", "read:users:name", "read:groups:name"],
+    },
+]
+```
+
+Note that this exposes the ability for all users to _discover_ existing user and group names,
+which is part of why we have the share-by-code pattern,
+so users don't need this ability to share with each other.
+
+## Share or revoke access to a server
+
+To modify who has access to a server, you need the permission `shares` with the appropriate _server_ filter,
+and access to read the name of the target user or group (`read:users:name` or `read:groups:name`).
+You can only modify access to one server at a time.
+
+### Granting access to a server
+
+To grant access to a particular user, in addition to `shares`, the granter must have at least `read:user:name` permission for the target user (or `read:group:name` if it's a group).
+
+Send a POST request to `/api/shares/:username/:servername` to grant permissions.
+
+```{parsed-literal}
+[POST /api/shares/:username/:servername](rest-api-post-shares-server)
+```
+
+The JSON body should specify what permissions to grant and whom to grant them to:
+
+```python
+{
+    "scopes": [],
+    "user": "username", # or:
+    "group": "groupname",
+}
+```
+
+It should have exactly one of "user" or "group" defined (not both).
+The specified user or group will be _granted_ access to the target server.
+
+If `scopes` is specified, all requested scopes _must_ have the `!server=:username/:servername` filter applied.
+The default value for `scopes` is `["access:servers!server=:username/:servername"]` (i.e. the 'access scope' for the server).
+
+### Revoke access
+
+To revoke permissions, you need the permission `shares` with the appropriate _server_ filter,
+and `read:users:name` (or `read:groups:name`) for the user or group to modify.
+You can only modify access to one server at a time.
+
+Send a PATCH request to `/api/shares/:username/:servername` to revoke permissions.
+
+```{parsed-literal}
+[PATCH /api/shares/:username/:servername](rest-api-patch-shares-server)
+```
+
+The JSON body should specify the scopes to revoke
+
+```
+POST /api/shares/:username/:servername
+{
+    "scopes": [],
+    "user": "username", # or:
+    "group": "groupname",
+}
+```
+
+If `scopes` is empty or unspecified, _all_ scopes are revoked from the target user or group.
+
+#### Revoke _all_ permissions
+
+A DELETE request will revoke all shared access permissions for the given server.
+
+```{parsed-literal}
+[DELETE /api/shares/:username/:servername](rest-api-delete-shares-server)
+```
+
+### View shares for a server
+
+To view shares for a given server, you need the permission `read:shares` with the appropriate _server_ filter.
+
+```{parsed-literal}
+[GET /api/shares/:username/:servername](rest-api-get-shares-server)
+```
+
+This is a paginated endpoint, so responses has `items` as a list of Share models, and `_pagination` for information about retrieving all shares if there are many:
+
+```python
+{
+  "items": [
+    {
+      "server": {...},
+      "scopes": ["access:servers!server=sharer/"],
+      "user": {
+        "name": "shared-with",
+      },
+      "group": None, # or {"name": "groupname"},
+      ...
+    },
+    ...
+  ],
+  "_pagination": {
+    "total": 5,
+    "limit": 50,
+    "offset": 0,
+    "next": None,
+  },
+}
+```
+
+see the [rest-api](rest-api-get-shares-server) for full details of the response models.
+
+### View servers shared with user or group
+
+To review servers shared with a given user or group, you need the permission `read:users:shares` or `read:groups:shares` with the appropriate _user_ or _group_ filter.
+
+```{parsed-literal}
+[GET /api/users/:username/shared](rest-api-get-user-shared)
+```
+
+or
+
+```{parsed-literal}
+[GET /api/groups/:groupname/shared](rest-api-get-group-shared)
+```
+
+These are paginated endpoints.
+
+### Access permission for a single user on a single server
+
+```{parsed-literal}
+[GET /api/users/:username/shared/:ownername/:servername](rest-api-get-user-shared-server)
+```
+
+or
+
+```{parsed-literal}
+[GET /api/groups/:groupname/shared/:ownername/:servername](rest-api-get-group-shared-server)
+```
+
+will return the _single_ Share info for the given user or group for the server specified by `ownername/servername`,
+or 404 if no access is granted.
+
+### Revoking one's own permissions for a server
+
+To revoke sharing permissions from the perspective of the user or group being shared with,
+you need the permissions `users:shares` or `groups:shares` with the appropriate _user_ or _group_ filter.
+This allows users to 'leave' shared servers, without needing permission to manage the server's sharing permissions.
+
+```
+[DELETE /api/users/:username/shared/:ownername/:servername](rest-api-delete-user-shared-server)
+```
+
+or
+
+```
+[DELETE /api/groups/:groupname/shared/:ownername/:servername](rest-api-delete-group-shared-server)
+```
+
+will revoke all permissions granted to the user or group for the specified server.
+
+### The Share model
+
+<!-- refresh from examples/user-sharing/rest-api.ipynb -->
+
+A Share returned in the REST API has the following structure:
+
+```python
+{
+    "server": {
+        "name": "servername",
+        "user": {
+          "name": "ownername"
+        },
+        "url": "/users/ownername/servername/",
+        "ready": True,
+
+    },
+    "scopes": ["access:servers!server=username/servername"],
+    "user": { # or None
+        "name": "username",
+    },
+    "group": None, # or {"name": "groupname"},
+    "created_at": "2023-10-02T13:27Z",
+}
+```
+
+where exactly one of `user` and `group` is not null and the other is null.
+
+See the [rest-api](rest-api-get-shares-server) for full details of the response models.
+
+## Share via invitation code
+
+Sometimes you would like to share access to a server with one or more users,
+but you don't want to deal with collecting everyone's username.
+For this, you can create shares via _share code_.
+This is identical to sharing with a user,
+only it adds the step where the sharer creates the _code_ and distributes the code to one or more users,
+then the users themselves exchange the code for actual sharing permissions.
+
+Share codes are much like shares, except:
+
+1. they don't associate with specific users
+2. they can be used multiple times, by more than one user (i.e. send one invite email to several recipients)
+3. they expire (default: 1 day)
+4. they can only be accepted by individual users, not groups
+
+### Creating share codes
+
+To create a share code:
+
+```{parsed-literal}
+[POST /api/share-code/:username/:servername](rest-api-post-share-code)
+```
+
+where the body should include the scopes to be granted and expiration.
+Share codes _must_ expire.
+
+```python
+{
+  "scopes": ["access:servers!server=:user/:server"],
+  "expires_in": 86400, # seconds, default: 1 day
+}
+```
+
+If no scopes are specified, the access scope for the specified server will be used.
+If no expiration is specified, the code will expire in one day (86400 seconds).
+
+The response contains the code itself:
+
+```python
+{
+  "code": "abc1234....",
+  "accept_url": "/hub/accept-share?code=abc1234",
+  "id": "sc_1234",
+  "scopes": [...],
+  ...
+}
+```
+
+See the [rest-api](rest-api-post-share-code) for full details of the response models.
+
+### Accepting sharing invitations
+
+Sharing invitations can be accepted by visiting:
+
+```
+/hub/accept-share/?code=:share-code
+```
+
+where you will be able to confirm the permissions you would like to accept.
+After accepting permissions, you will be redirected to the running server.
+
+If the server is not running and you have not also been granted permission to start it,
+you will need to contact the owner of the server to start it.
+
+### Listing existing invitations
+
+You can see existing invitations for
+
+```{parsed-literal}
+[GET /hub/api/share-codes/:username/:servername](rest-api-get-share-codes-server)
+```
+
+which produces a paginated list of share codes (_excluding_ the codes themselves, which are not stored by jupyterhub):
+
+```python
+{
+  "items": [
+    {
+      "id": "sc_1234",
+      "exchange_count": 0,
+      "last_exchanged_at": None,
+      "scopes": ["access:servers!server=username/servername"],
+      "server": {
+        "name": "",
+        "user": {
+          "name": "username",
+        },
+      },
+      ...
+    }
+  ],
+  "_pagination": {
+    "total": 5,
+    "limit": 50,
+    "offset": 0,
+    "next": None,
+  }
+}
+```
+
+see the [rest-api](rest-api) for full details of the response models.
+
+### Share code model
+
+<!-- refresh from examples/user-sharing/rest-api.ipynb -->
+
+A Share Code returned in the REST API has most of the same fields as a Share, but lacks the association with a user or group, and adds information about exchanges of the share code,
+and the `id` that can be used for revocation:
+
+```python
+{
+
+  # common share fields
+  "server": {
+    "user": {
+      "name": "sharer"
+    },
+    "name": "",
+    "url": "/user/sharer/",
+    "ready": True,
+  },
+  "scopes": [
+    "access:servers!server=sharer/"
+  ],
+  # share-code-specific fields
+  "id": "sc_1",
+  "created_at": "2024-01-23T11:46:32.154416Z",
+  "expires_at": "2024-01-24T11:46:32.153582Z",
+  "exchange_count": 1,
+  "last_exchanged_at": "2024-01-23T11:46:43.589701Z"
+}
+```
+
+see the [rest-api](rest-api-get-share-codes-server) for full details of the response models.
+
+### Revoking invitations
+
+If you've finished inviting users to a server, you can revoke all invitations with:
+
+```{parsed-literal}
+[DELETE /hub/api/share-codes/:username/:servername](rest-api-delete-share-code)
+```
+
+or revoke a single invitation code:
+
+```
+DELETE /hub/api/share-codes/:username/:servername?code=:thecode
+```
+
+You can also revoke a code by _id_, if you non longer have the code:
+
+```
+DELETE /hub/api/share-codes/:username/:servername?id=sc_123
+```
+
+where the `id` is retrieved from the share-code model, e.g. when listing current share codes.

docs/source/reference/spawners.md

@@ -12,7 +12,7 @@ and a custom Spawner needs to be able to take three actions:
 
 ## Examples
 
-Custom Spawners for JupyterHub can be found on the [JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Spawners).
+Additional Spawners can be installed from separate packages.
 Some examples include:
 
 - [DockerSpawner](https://github.com/jupyterhub/dockerspawner) for spawning user servers in Docker containers
@@ -31,6 +31,7 @@ Some examples include:
 - [SSHSpawner](https://github.com/NERSC/sshspawner) to spawn notebooks
   on a remote server using SSH
 - [KubeSpawner](https://github.com/jupyterhub/kubespawner) to spawn notebook servers on kubernetes cluster.
+- [NomadSpawner](https://github.com/mxab/jupyterhub-nomad-spawner) to spawn a notebook server as a Nomad job inside HashiCorp's Nomad cluster
 
 ## Spawner control methods
 
@@ -314,6 +315,14 @@ The process environment is returned by `Spawner.get_env`, which specifies the fo
 - `JUPYTERHUB_OAUTH_ACCESS_SCOPES` - the scopes required to access the server (called `JUPYTERHUB_OAUTH_SCOPES` prior to 3.0)
 - `JUPYTERHUB_OAUTH_CLIENT_ALLOWED_SCOPES` - the scopes the service is allowed to request.
   If no scopes are requested explicitly, these scopes will be requested.
+- `JUPYTERHUB_PUBLIC_URL` - the public URL of the server,
+  e.g. `https://jupyterhub.example.org/user/name/`.
+  Empty if no public URL is specified (default).
+  Will be available if subdomains are configured.
+- `JUPYTERHUB_PUBLIC_HUB_URL` - the public URL of JupyterHub as a whole,
+  e.g. `https://jupyterhub.example.org/`.
+  Empty if no public URL is specified (default).
+  Will be available if subdomains are configured.
 
 Optional environment variables, depending on configuration:
 

docs/source/tutorial/collaboration-users.md

@@ -6,6 +6,10 @@
 It is recommended to use at least JupyterLab 3.6 with JupyterHub >= 3.1.1 for this.
 :::
 
+:::{note}
+Starting with JupyterLab >=4.0, installing the [jupyter-collaboration](https://github.com/jupyterlab/jupyter-collaboration) package in your single-user environment enables collaborative mode, instead of passing the `--collaborative` flag at runtime.
+:::
+
 JupyterLab has support for real-time collaboration (RTC), where multiple users are working with the same Jupyter server and see each other's edits.
 Beyond other collaborative-editing environments, Jupyter includes _execution_.
 So granting someone access to your server also means granting them access to **run code as you**.

docs/source/tutorial/getting-started/authenticators-users-basics.md

@@ -6,20 +6,72 @@ The default Authenticator uses [PAM][] (Pluggable Authentication Module) to auth
 their usernames and passwords. With the default Authenticator, any user
 with an account and password on the system will be allowed to login.
 
-## Create a set of allowed users (`allowed_users`)
+## Deciding who is allowed
+
+In the base Authenticator, there are 3 configuration options for granting users access to your Hub:
+
+1. `allow_all` grants any user who can successfully authenticate access to the Hub
+2. `allowed_users` defines a set of users who can access the Hub
+3. `allow_existing_users` enables managing users via the JupyterHub API or admin page
+
+These options should apply to all Authenticators.
+Your chosen Authenticator may add additional configuration options to admit users, such as team membership, course enrollment, etc.
+
+:::{important}
+You should always specify at least one allow configuration if you want people to be able to access your Hub!
+In most cases, this looks like:
+
+```python
+c.Authenticator.allow_all = True
+# or
+c.Authenticator.allowed_users = {"name", ...}
+```
+
+:::
+
+:::{versionchanged} 5.0
+If no allow config is specified, then by default **nobody will have access to your Hub**.
+Prior to 5.0, the opposite was true; effectively `allow_all = True` if no other allow config was specified.
+:::
 
 You can restrict which users are allowed to login with a set,
 `Authenticator.allowed_users`:
 
 ```python
 c.Authenticator.allowed_users = {'mal', 'zoe', 'inara', 'kaylee'}
+# c.Authenticator.allow_all = False
+c.Authenticator.allow_existing_users = False
 ```
 
-Users in the `allowed_users` set are added to the Hub database when the Hub is
-started.
+Users in the `allowed_users` set are added to the Hub database when the Hub is started.
 
-```{warning}
-If this configuration value is not set, then **all authenticated users will be allowed into your hub**.
+:::{versionchanged} 5.0
+{attr}`.Authenticator.allow_all` and {attr}`.Authenticator.allow_existing_users` are new in JupyterHub 5.0
+to enable explicit configuration of previously implicit behavior.
+
+Prior to 5.0, `allow_all` was implicitly True if `allowed_users` was empty.
+Starting with 5.0, to allow all authenticated users by default,
+`allow_all` must be explicitly set to True.
+
+By default, `allow_existing_users` is True when `allowed_users` is not empty,
+to ensure backward-compatibility.
+To make the `allowed_users` set _restrictive_,
+set `allow_existing_users = False`.
+:::
+
+## One Time Passwords ( request_otp )
+
+By setting `request_otp` to true, the login screen will show and additional password input field
+to accept an OTP:
+
+```python
+c.Authenticator.request_otp = True
+```
+
+By default, the prompt label is `OTP:`, but this can be changed by setting `otp_prompt`:
+
+```python
+c.Authenticator.otp_prompt = 'Google Authenticator:'
 ```
 
 ## Configure admins (`admin_users`)
@@ -27,7 +79,7 @@ If this configuration value is not set, then **all authenticated users will be a
 ```{note}
 As of JupyterHub 2.0, the full permissions of `admin_users`
 should not be required.
-Instead, you can assign [roles](define-role-target) to users or groups
+Instead, it is best to assign [roles](define-role-target) to users or groups
 with only the scopes they require.
 ```
 
@@ -53,26 +105,55 @@ group. For example, we can let any user in the `wheel` group be an admin:
 c.PAMAuthenticator.admin_groups = {'wheel'}
 ```
 
-## Give admin access to other users' notebook servers (`admin_access`)
+## Give some users access to other users' notebook servers
 
-Since the default `JupyterHub.admin_access` setting is `False`, the admins
-do not have permission to log in to the single user notebook servers
-owned by _other users_. If `JupyterHub.admin_access` is set to `True`,
-then admins have permission to log in _as other users_ on their
-respective machines for debugging. **As a courtesy, you should make
-sure your users know if admin_access is enabled.**
+The `access:servers` scope can be granted to users to give them permission to visit other users' servers.
+For example, to give members of the `teachers` group access to the servers of members of the `students` group:
+
+```python
+c.JupyterHub.load_roles = [
+  {
+    "name": "teachers",
+    "scopes": [
+      "admin-ui",
+      "list:users",
+      "access:servers!group=students",
+    ],
+    "groups": ["teachers"],
+  }
+]
+```
+
+By default, only the deprecated `admin` role has global `access` permissions.
+**As a courtesy, you should make sure your users know if admin access is enabled.**
 
 ## Add or remove users from the Hub
 
+:::{versionadded} 5.0
+`c.Authenticator.allow_existing_users` is added in 5.0 and True by default _if_ any `allowed_users` are specified.
+
+Prior to 5.0, this behavior was not optional.
+:::
+
 Users can be added to and removed from the Hub via the admin
-panel or the REST API. When a user is **added**, the user will be
-automatically added to the `allowed_users` set and database. Restarting the Hub
-will not require manually updating the `allowed_users` set in your config file,
+panel or the REST API.
+
+To enable this behavior, set:
+
+```python
+c.Authenticator.allow_existing_users = True
+```
+
+When a user is **added**, the user will be
+automatically added to the `allowed_users` set and database.
+If `allow_existing_users` is True, restarting the Hub will not require manually updating the `allowed_users` set in your config file,
 as the users will be loaded from the database.
+If `allow_existing_users` is False, users not granted access by configuration such as `allowed_users` will not be permitted to login,
+even if they are present in the database.
 
 After starting the Hub once, it is not sufficient to **remove** a user
 from the allowed users set in your config file. You must also remove the user
-from the Hub's database, either by deleting the user from JupyterHub's
+from the Hub's database, either by deleting the user via JupyterHub's
 admin page, or you can clear the `jupyterhub.sqlite` database and start
 fresh.
 
@@ -112,7 +193,6 @@ popular services:
 - [Globus](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.globus.html)
 - [Google](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.google.html)
 - [MediaWiki](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.mediawiki.html)
-- [Okpy](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.okpy.html)
 - [OpenShift](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.openshift.html)
 
 A [generic implementation](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.generic.html), which you can use for OAuth authentication

docs/source/tutorial/index.md

@@ -51,5 +51,6 @@ Further tutorials of configuring JupyterHub for specific tasks
 ```{toctree}
 :maxdepth: 1
 
+sharing
 collaboration-users
 ```

docs/source/tutorial/quickstart-docker.md

@@ -1,9 +1,9 @@
 # Install JupyterHub with Docker
 
-The JupyterHub [docker image](https://hub.docker.com/r/jupyterhub/jupyterhub/) is the fastest way to set up Jupyterhub in your local development environment.
+The JupyterHub [docker image](https://quay.io/repository/jupyterhub/jupyterhub) is the fastest way to set up Jupyterhub in your local development environment.
 
 :::{note}
-This `jupyterhub/jupyterhub` docker image is only an image for running
+This `quay.io/jupyterhub/jupyterhub` docker image is only an image for running
 the Hub service itself. It does not provide the other Jupyter components,
 such as Notebook installation, which are needed by the single-user servers.
 To run the single-user servers, which may be on the same system as the Hub or
@@ -24,7 +24,7 @@ You should have [Docker] installed on a Linux/Unix based system.
 To pull the latest JupyterHub image and start the `jupyterhub` container, run this command in your terminal.
 
 ```
-docker run -d -p 8000:8000 --name jupyterhub jupyterhub/jupyterhub jupyterhub
+docker run -d -p 8000:8000 --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub
 ```
 
 This command exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console.

docs/source/tutorial/quickstart.md

@@ -5,11 +5,11 @@
 Before installing JupyterHub, you will need:
 
 - a Linux/Unix-based system
-- [Python](https://www.python.org/downloads/) 3.6 or greater. An understanding
+- [Python {{python_min}}](https://www.python.org/downloads/) or greater. An understanding
   of using [`pip`](https://pip.pypa.io) or
   [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) for
   installing Python packages is helpful.
-- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
+- [Node.js {{node_min}}](https://www.npmjs.com/) or greater, along with npm. [Install Node.js/npm](https://docs.npmjs.com/getting-started/installing-node),
   using your operating system's package manager.
 
   - If you are using **`conda`**, the nodejs and npm dependencies will be installed for
@@ -24,7 +24,7 @@ Before installing JupyterHub, you will need:
     ```
 
     [nodesource][] is a great resource to get more recent versions of the nodejs runtime,
-    if your system package manager only has an old version of Node.js (e.g. 10 or older).
+    if your system package manager only has an old version of Node.js.
 
 - A [pluggable authentication module (PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module)
   to use the [default Authenticator](authenticators).

docs/source/tutorial/sharing.md

@@ -0,0 +1,287 @@
+(sharing-tutorial)=
+
+# Sharing access to your server
+
+In JupyterHub 5.0, users can grant each other limited access to their servers without intervention by Hub administrators.
+There is not (yet!) any UI for granting shared access, so this tutorial goes through the steps of using the JupyterHub API to grant access to servers.
+
+For more background on how sharing works in JupyterHub, see the [sharing reference documentation](sharing-reference).
+
+## Setup: enable sharing (admin)
+
+First, sharing must be _enabled_ on the JupyterHub deployment.
+That is, grant (some) users permission to share their servers with others.
+Users cannot share their servers by default.
+This is the only step that requires an admin action.
+To grant users permission to share access to their servers,
+add the `shares!user` scope to the default `user` role:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        "scopes": ["self", "shares!user"],
+    },
+]
+```
+
+With this, only the sharing via invitation code (described below) will be available.
+
+Additionally, if you want users to be able to share access with a **specific user or group** (more below),
+a user must have permission to read that user or group's name.
+To enable the _full_ sharing API for all users:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        "scopes": ["self", "shares!user", "read:users:name", "read:groups:name"],
+    },
+]
+```
+
+Note that this exposes the ability for all users to _discover_ existing user and group names,
+which is part of why we have the share-by-code pattern,
+so users don't need this ability to share with each other.
+Adding filters lets you limit who can be shared with by name.
+
+:::{note}
+Removing a user's permission to grant shares only prevents _future_ shares.
+Any shared permissions previously granted by a user will remain and must be revoked separately,
+if desired.
+:::
+
+### Grant servers permission to share themselves (optional, admin)
+
+The most natural place to want to grant access to a server is when viewing that server.
+By default, the tokens used when talking to a server have extremely limited permissions.
+You can grant sharing permissions to servers themselves in one of two ways.
+
+The first is to grant sharing permission to the tokens used by browser requests.
+This is what you would do if you had a JupyterLab extension that presented UI for managing shares
+(this should exist! We haven't made it yet).
+To grant these tokens sharing permissions:
+
+```python
+c.Spawner.oauth_client_allowed_scopes = ["access:servers!server", "shares!server"]
+```
+
+JupyterHub's `user-sharing` example does it this way.
+The nice thing about this approach is that only users who already have those permissions will get a token which can take these actions.
+The downside (in terms of convenience) is that the browser token is only accessible to the javascript (e.g. JupyterLab) and/or jupyter-server request handlers,
+but not notebooks or terminals.
+
+The second way, which is less secure, but perhaps more convenient for demonstration purposes,
+is to grant the _server itself_ permission to grant access to itself.
+
+```python
+c.Spawner.server_token_scopes = [
+  "users:activity!user",
+  "shares!server",
+]
+```
+
+The security downside of this approach is that anyone who can access the server generally can assume the permissions of the server token.
+Effectively, this means anyone who the server is shared _with_ will gain permission to further share the server with others.
+This is not the case for the first approach, but this token is accessible to terminals and notebook kernels, making it easier to illustrate.
+
+## Get a token
+
+Now, assuming the _user_ has permission to share their server (step 0), we need a token to make the API requests in this tutorial.
+You can do this at the token page, or inherit it from the single-user server environment if one of the above configurations has been selected by admins.
+
+To request a token with only the permissions required (`shares!user`) on the token page:
+
+![JupyterHub Token page requesting a token with scopes "shares!user"](../images/sharing-token.png)
+
+This token will be in the `Authorization` header.
+To create a {py:class}`requests.Session` that will send this header on every request:
+
+```python
+import requests
+from getpass import getpass
+
+token = getpass.getpass("JupyterHub API token: ")
+
+session = requests.Session()
+session.headers = {"Authorization": f"Bearer {token}"}
+```
+
+We will make subsequent requests in this tutorial with this session object, so the header is present.
+
+## Issue a sharing code
+
+We are going to make a POST request to `/hub/api/share-codes/username/` to issue a _sharing code_.
+This is a _code_, which can be _exchanged_ by one or more users for access to the shared service.
+
+A sharing code:
+
+- always expires (default: after one day)
+- can be _exchanged_ multiple times for shared access to the server
+
+When the sharing code expires, any permissions granted by the code will remain
+(think of it like an invitation to collaborate on a repository or to a chat group - the invitation can expire, but once accepted, access persists).
+
+To request a share code:
+
+```
+POST /hub/api/share-codes/:username/:servername
+```
+
+Assuming your username is `barb` and you want to share access to your default server, this would be:
+
+```
+POST /hub/api/share-codes/barb/
+```
+
+```python
+# sample values, replace with your actual hub
+hub_url = "http://127.0.0.1:8000"
+username = "barb"
+
+r = session.post(f"{hub_url}/hub/api/share-codes/{username}/")
+```
+
+which will have a JSON response:
+
+```python
+{
+  'server': {'user': {'name': 'barb'},
+    'name': '',
+    'url': '/user/barb/',
+    'ready': True,
+  },
+  'scopes': ['access:servers!server=barb/'],
+  'id': 'sc_2',
+  'created_at': '2024-01-10T13:01:32.972409Z',
+  'expires_at': '2024-01-11T13:01:32.970126Z',
+  'exchange_count': 0,
+  'last_exchanged_at': None,
+  'code': 'U-eYLFT1lGstEqfMHpAIvTZ1MRjZ1Y1a-loGQ0K86to',
+  'accept_url': '/hub/accept-share?code=U-eYLFT1lGstEqfMHpAIvTZ1MRjZ1Y1a-loGQ0K86to',
+}
+```
+
+The most relevant fields here are `code`, which contains the code itself, and `accept_url`, which is the URL path for the page another user.
+Note: it does not contain the _hostname_ of the hub, which JupyterHub often does not know.
+
+Share codes are guaranteed to be url-safe, so no encoding is required.
+
+### Expanding or limiting the share code
+
+You can specify scopes (must be limited to this specific server) and expiration of the sharing code.
+
+:::{note}
+The granted permissions do not expire, only the code itself.
+That means that after expiration, users may not exchange the code anymore,
+but any user who has exchanged it will still have those permissions.
+:::
+
+The _default_ scopes are only `access:servers!server=:user/:server`, and the default expiration is one day (86400).
+These can be overridden in the JSON body of the POST request that issued the token:
+
+```python
+import json
+
+options = {
+  "scopes": [
+    f"access:servers!server={username}/", # access the server (default)
+    f"servers!server={username}/", # start/stop the server
+    f"shares!server={username}/", # further share the server with others
+  ],
+  "expires_in": 3600, # code expires in one hour
+}
+
+session.post(f"{hub_url}/hub/api/share-codes/{username}/", data=json.dumps(options))
+```
+
+### Distribute the sharing code
+
+Now that you have a code and/or a URL, anyone you share the code with will be able to visit `$JUPYTERHUB/hub/accept-share?code=code`.
+
+### Sharing a link to a specific page
+
+The `accept-share` page also accepts a `next` URL parameter, which can be a redirect to a specific page, rather than the default page of the server.
+For example:
+
+```
+/hub/accept-code?code=abc123&next=/users/barb/lab/tree/mynotebook.ipynb
+```
+
+would be a link that can be shared with any JupyterHub user that will take them directly to the file `mynotebook.ipynb` in JupyterLab on barb's server after granting them access to the server.
+
+## Reviewing shared access
+
+When you have shared access to your server, it's a good idea to check out who has access.
+You can see who has access with:
+
+```python
+session.get()
+```
+
+which produces a paginated list of who has shared access:
+
+```python
+{'items': [{'server': {'user': {'name': 'barb'},
+    'name': '',
+    'url': '/user/barb/',
+    'ready': True},
+   'scopes': ['access:servers!server=barb/',
+    'servers!server=barb/',
+    'shares!server=barb/'],
+   'user': {'name': 'shared-with'},
+   'group': None,
+   'kind': 'user',
+   'created_at': '2024-01-10T13:16:56.432599Z'}],
+ '_pagination': {'offset': 0, 'limit': 200, 'total': 1, 'next': None}}
+```
+
+## Revoking shared access
+
+There are two ways to revoke access to a shared server:
+
+1. `PATCH` requests can revoke individual permissions from individual users or groups
+2. `DELETE` requests revokes all shared permissions from anyone (unsharing the server in one step)
+
+To revoke one or more scopes from a user:
+
+```python
+options = {
+    "user": "shared-with",
+    "scopes": ["shares!server=barb/"],
+}
+
+session.patch(f"{hub_url}/hub/api/shares/{username}/", data=json.dumps(options))
+```
+
+The Share model with remaining permissions, if any, will be returned:
+
+```python
+{'server': {'user': {'name': 'barb'},
+  'name': '',
+  'url': '/user/barb/',
+  'ready': True},
+ 'scopes': ['access:servers!server=barb/', 'servers!server=barb/'],
+ 'user': {'name': 'shared-with'},
+ 'group': None,
+ 'kind': 'user',
+ 'created_at': '2024-01-10T13:16:56.432599Z'}
+```
+
+If no permissions remain, the response will be an empty dict (`{}`).
+
+To revoke all permissions for a single user, leave `scopes` unspecified:
+
+```python
+options = {
+    "user": "shared-with",
+}
+
+session.patch(f"{hub_url}/hub/api/shares/{username}/", data=json.dumps(options))
+```
+
+Or revoke all shared permissions from all users for the server:
+
+```python
+session.delete(f"{hub_url}/hub/api/shares/{username}/")
+```

examples/bootstrap-script/jupyterhub_config.py

@@ -2,6 +2,7 @@
 Example for a Spawner.pre_spawn_hook
 create a directory for the user before the spawner starts
 """
+
 # pylint: disable=import-error
 import os
 import shutil
@@ -27,8 +28,9 @@ def clean_dir_hook(spawner):
         shutil.rmtree(temp_path)
 
 
+c = get_config()  # noqa
+
 # attach the hook functions to the spawner
-# pylint: disable=undefined-variable
 c.Spawner.pre_spawn_hook = create_dir_hook
 c.Spawner.post_stop_hook = clean_dir_hook
 

examples/external-oauth/README.md

@@ -60,8 +60,9 @@ The essential pieces for using JupyterHub as an OAuth provider are:
            "name": "my-service",
            # the oauth client id of your service
            # must be unique but isn't private
-           # can be randomly generated or hand-written
-           "oauth_client_id": "abc123",
+           # can be randomly generated or hand-written, but must
+           # begin with service-
+           "oauth_client_id": "service-abc123",
            # the API token and client secret of the service
            # should be generated securely,
            # e.g. via `openssl rand -hex 32`
@@ -77,7 +78,7 @@ The essential pieces for using JupyterHub as an OAuth provider are:
 
 The relevant OAuth URLs and keys for using JupyterHub as an OAuth provider are:
 
-1. the client_id, used in oauth requests
+1. the client_id, used in oauth requests. This must begin with the characters `service-`
 2. the api token registered with jupyterhub is the client_secret for oauth requests
 3. oauth url of the Hub, which is "/hub/api/oauth2/authorize", e.g. `https://myhub.horse/hub/api/oauth2/authorize`
 4. a redirect handler to receive the authenticated response

examples/external-oauth/jupyterhub_config.py

@@ -8,8 +8,8 @@ if not api_token:
         "Make sure to `export JUPYTERHUB_API_TOKEN=$(openssl rand -hex 32)`"
     )
 
+c = get_config()  # noqa
 # tell JupyterHub to register the service as an external oauth client
-
 c.JupyterHub.services = [
     {
         'name': 'external-oauth',
@@ -18,3 +18,26 @@ c.JupyterHub.services = [
         'oauth_redirect_uri': 'http://127.0.0.1:5555/oauth_callback',
     }
 ]
+
+# Grant all JupyterHub users ability to access services
+c.JupyterHub.load_roles = [
+    {
+        'name': 'user',
+        'description': 'Allow all users to access all services',
+        'scopes': ['access:services', 'self'],
+    }
+]
+
+# Boilerplate to make sure the example runs - this is not relevant
+# to external oauth services.
+
+# Allow authentication with any username and any password
+from jupyterhub.auth import DummyAuthenticator
+
+c.JupyterHub.authenticator_class = DummyAuthenticator
+
+# Optionally set a global password that all users must use
+# c.DummyAuthenticator.password = "your_password"
+
+# only listen on localhost for testing.
+c.JupyterHub.bind_url = 'http://127.0.0.1:8000'

examples/external-oauth/whoami-oauth-basic.py

@@ -3,6 +3,7 @@
 Implements OAuth handshake manually
 so all URLs and requests necessary for OAuth with JupyterHub should be in one place
 """
+
 import json
 import os
 from urllib.parse import urlencode, urlparse

examples/postgres/hub/jupyterhub_config.py

@@ -25,6 +25,4 @@ import os
 
 pg_pass = os.getenv('POSTGRES_ENV_JPY_PSQL_PASSWORD')
 pg_host = os.getenv('POSTGRES_PORT_5432_TCP_ADDR')
-c.JupyterHub.db_url = 'postgresql://jupyterhub:{}@{}:5432/jupyterhub'.format(
-    pg_pass, pg_host
-)
+c.JupyterHub.db_url = f'postgresql://jupyterhub:{pg_pass}@{pg_host}:5432/jupyterhub'

examples/read-only/README.md

@@ -23,3 +23,8 @@ To test this, you'll want two browser sessions:
 
 Percy can use their server as normal, but vex will only be able to read files.
 Vex won't be able to run any code, connect to kernels, or save edits to files.
+
+Note that defining custom scopes does not enforce that they are used.
+Defining scopes for read-only access and then running user servers without the custom Authorizer
+will result in users who are supposed to have read-only access actually having unrestricted access,
+because only the default `access:servers` scope is checked.

examples/server-api/start-stop-server.py

@@ -9,6 +9,7 @@ Example of starting/stopping a server via the JupyterHub API
 5. stop server via API
 6. wait for server to finish stopping
 """
+
 import json
 import logging
 import pathlib

examples/service-announcement/jupyterhub_config.py

@@ -1,6 +1,6 @@
 import sys
 
-c = get_config()
+c = get_config()  # noqa
 
 # To run the announcement service managed by the hub, add this.
 

examples/service-announcement/templates/page.html

@@ -1,9 +1,12 @@
-{% extends "templates/page.html" %} {% block announcement %}
+{% extends "templates/page.html" %}
+{% block announcement %}
   <div class="container text-center announcement"></div>
-{% endblock %} {% block script %} {{ super() }}
+{% endblock announcement %}
+{% block script %}
+  {{ super() }}
   <script>
     $.get("/services/announcement/", function(data) {
       $(".announcement").html(data["announcement"]);
     });
   </script>
-{% endblock %}
+{% endblock script %}

examples/service-fastapi/Dockerfile

@@ -1,4 +1,4 @@
-FROM jupyterhub/jupyterhub
+FROM quay.io/jupyterhub/jupyterhub
 
 # Create test user (PAM auth) and install single-user Jupyter
 RUN useradd testuser --create-home --shell /bin/bash

examples/service-fastapi/jupyterhub_config.py

@@ -19,6 +19,8 @@ else:
 service_name = "fastapi"
 oauth_redirect_uri = f"{public_host}/services/{service_name}/oauth_callback"
 
+
+c = get_config()  # noqa
 c.JupyterHub.services = [
     {
         "name": service_name,

examples/service-notebook/external/jupyterhub_config.py

@@ -1,3 +1,5 @@
+c = get_config()  # noqa
+
 # our user list
 c.Authenticator.allowed_users = ['minrk', 'ellisonbg', 'willingc']
 

examples/service-notebook/managed/jupyterhub_config.py

@@ -1,3 +1,5 @@
+c = get_config()  # noqa
+
 # our user list
 c.Authenticator.allowed_users = ['minrk', 'ellisonbg', 'willingc']
 

examples/service-whoami-flask/README.md

@@ -15,14 +15,19 @@ After logging in with your local-system credentials, you should see a JSON dump
 ```json
 {
   "admin": false,
-  "last_activity": "2016-05-27T14:05:18.016372",
+  "groups": [],
+  "kind": "user",
   "name": "queequeg",
-  "pending": null,
-  "server": "/user/queequeg"
+  "scopes": [
+    "access:services!service=whoami",
+    "read:users:groups!user=queequeg",
+    "read:users:name!user=queequeg"
+  ],
+  "session_id": "a32e59cdd7b445759c58c48e47394a38"
 }
 ```
 
-This relies on the Hub starting the whoami service, via config (see [jupyterhub_config.py](./jupyterhub_config.py)).
+This relies on the Hub starting the whoami service, via config (see [jupyterhub_config.py](./jupyterhub_config.py)). For ordinary users to access this service, they need to be given the appropriate scope (again, see [jupyterhub_config.py](./jupyterhub_config.py)).
 
 A similar service could be run externally, by setting the JupyterHub service environment variables:
 

examples/service-whoami-flask/jupyterhub_config.py

@@ -1,3 +1,5 @@
+c = get_config()  # noqa
+
 c.JupyterHub.services = [
     {
         'name': 'whoami',
@@ -6,6 +8,15 @@ c.JupyterHub.services = [
         'environment': {'FLASK_APP': 'whoami-flask.py'},
     },
 ]
+c.JupyterHub.load_roles = [
+    {
+        'name': 'user',
+        'scopes': [
+            'access:services!service=whoami',  # access this service
+            'self',  # and all of the standard things for a user
+        ],
+    }
+]
 
 # dummy auth and simple spawner for testing
 # any username and password will work

examples/service-whoami-flask/whoami-flask.py

@@ -2,6 +2,7 @@
 """
 whoami service authentication with the Hub
 """
+
 import json
 import os
 import secrets
@@ -56,14 +57,14 @@ def whoami(user):
 def oauth_callback():
     code = request.args.get('code', None)
     if code is None:
-        return 403
+        return "Forbidden", 403
 
     # validate state field
     arg_state = request.args.get('state', None)
     cookie_state = request.cookies.get(auth.state_cookie_name)
     if arg_state is None or arg_state != cookie_state:
         # state doesn't match
-        return 403
+        return "Forbidden", 403
 
     token = auth.token_for_code(code)
     # store token in session cookie

examples/service-whoami/jupyterhub_config.py

@@ -1,5 +1,7 @@
 import sys
 
+c = get_config()  # noqa
+
 c.JupyterHub.services = [
     {
         'name': 'whoami-api',

examples/service-whoami/whoami-oauth.py

@@ -4,6 +4,7 @@ This example service serves `/services/whoami-oauth/`,
 authenticated with the Hub,
 showing the user their own info.
 """
+
 import json
 import os
 from urllib.parse import urlparse

examples/service-whoami/whoami.py

@@ -4,6 +4,7 @@ This serves `/services/whoami-api/`, authenticated with the Hub, showing the use
 
 HubAuthenticated only supports token-based access.
 """
+
 import json
 import os
 from urllib.parse import urlparse

examples/spawn-form/jupyterhub_config.py

@@ -1,15 +1,18 @@
 """
 Example JupyterHub config allowing users to specify environment variables and notebook-server args
 """
+
 import shlex
 
 from jupyterhub.spawner import LocalProcessSpawner
 
+c = get_config()  # noqa
+
 
 class DemoFormSpawner(LocalProcessSpawner):
     def _options_form_default(self):
         default_env = "YOURNAME=%s\n" % self.user.name
-        return """
+        return f"""
         <div class="form-group">
             <label for="args">Extra notebook CLI arguments</label>
             <input name="args" class="form-control"
@@ -17,11 +20,9 @@ class DemoFormSpawner(LocalProcessSpawner):
         </div>
         <div class="form-group">
             <label for="env">Environment variables (one per line)</label>
-            <textarea class="form-control" name="env">{env}</textarea>
+            <textarea class="form-control" name="env">{default_env}</textarea>
         </div>
-        """.format(
-            env=default_env
-        )
+        """
 
     def options_from_form(self, formdata):
         options = {}

examples/user-sharing/README.md

@@ -0,0 +1,77 @@
+# User-initiated sharing
+
+This example contains a jupyterhub configuration and sample notebooks demonstrating user-initiated sharing from within a JupyterLab session.
+
+What _admins_ need to do is enable sharing:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        "scopes": ["self", "shares!user"],
+    }
+]
+```
+
+## Getting a token with sharing permission
+
+Users can always issue themselves tokens with the desired permissions.
+But for a deployment, it's likely that you want to grant sharing permission to something,
+be it a service or some part of the single-user application.
+
+There are two ways to do this in a single-user session,
+and for convenience, this example includes both.
+In most real deployments, it will only make sense to do one or the other.
+
+### Sharing via JupyterLab extension
+
+If you have a JupyterLab javascript sharing extension or server extension,
+sharing permissions should be granted to the oauth tokens used to visit the single-user server.
+These permissions can be specified:
+
+```python
+# OAuth token should have sharing permissions,
+# so JupyterLab javascript can manage shares
+c.Spawner.oauth_client_allowed_scopes = ["access:servers!server", "shares!server"]
+```
+
+The notebook `share-jupyterlab.ipynb` contains a few javascript snippets which will use the JupyterLab configuration to make API requests to JupyterHub from javascript in order to grant access.
+
+This workflow _should_ be handled by a proper JupyterLab extension,
+but this notebook of javascript snippets serves as a proof of concept for what is required to build such an extension.
+
+## Sharing via API token
+
+These same permissions can also be granted to the server token itself,
+which is available as $JUPYTERHUB_API_TOKEN in the server,
+as well as terminals and notebooks.
+
+```python
+# grant $JUPYTERHUB_API_TOKEN sharing permissions
+# so that _python_ code can manage shares
+c.Spawner.server_token_scopes = [
+    "shares!server",  # manage shares
+    "servers!server",  # start/stop itself
+    "users:activity!server",  # report activity (default permission)
+]
+```
+
+This method is not preferable, because it means anyone with _access_ to the server also has access to the token to grant further sharing permissions,
+which is not the case when using the oauth permissions above,
+where each visiting user has their own permissions.
+
+But it is more convenient for demonstration purposes, because we can write a Python notebook to use it, share-api.ipynb.
+
+## Run the example
+
+First, launch jupyterhub: `jupyterhub`.
+
+Then login as the user `sharer`.
+
+Run the first couple of cells of the notebook, until you get a `/hub/accept-share` URL.
+
+Open a new private browser window, and paste this URL. When prompted, login with the username `shared-with`.
+
+In the end, you should arrive at `sharer`'s server as the user `shared-with`.
+
+After visiting as `shared-with`, you can proceed in the notebook as `sharer` and view who has permissions, revoke share codes, permissions, etc.

examples/user-sharing/jupyterhub_config.py

@@ -0,0 +1,37 @@
+c = get_config()  # noqa
+
+
+c.JupyterHub.authenticator_class = 'dummy'
+c.JupyterHub.spawner_class = 'simple'
+
+c.Authenticator.allowed_users = {"sharer", "shared-with"}
+
+# put the current directory on sys.path for shareextension.py
+from pathlib import Path
+
+here = Path(__file__).parent.absolute()
+c.Spawner.notebook_dir = str(here)
+
+# users need sharing permissions for their own servers
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        "scopes": ["self", "shares!user"],
+    },
+]
+
+# below are two ways to grant sharing permission to a single-user server.
+# there's no reason to use both
+
+
+# OAuth token should have sharing permissions,
+# so JupyterLab javascript can manage shares
+c.Spawner.oauth_client_allowed_scopes = ["access:servers!server", "shares!server"]
+
+# grant $JUPYTERHUB_API_TOKEN sharing permissions
+# so that _python_ code can manage shares
+c.Spawner.server_token_scopes = [
+    "shares!server",  # manage shares
+    "servers!server",  # start/stop itself
+    "users:activity!server",  # report activity
+]

examples/user-sharing/share-api.ipynb

@@ -0,0 +1,688 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "8c5bd1ca-3329-4062-8851-9bd33009d805",
+   "metadata": {},
+   "source": [
+    "# Using the sharing API from Python \n",
+    "\n",
+    "In this example, we use $JUPYTERHUB_API_TOKEN to communicate with the sharing API via Python.\n",
+    "\n",
+    "The permissions used here are granted via the `c.Spawner.server_token_scopes` config in jupyterhub_config.py\n",
+    "\n",
+    "By using this token, any user who has access to this server has access to sharing permissions.\n",
+    "\n",
+    "First, get some useful configuration from the server environment:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "95fa629b-ac65-46da-86a6-9798f3d0a2ba",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'http://127.0.0.1:8081/hub/api'"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import os\n",
+    "\n",
+    "hub_api = os.environ[\"JUPYTERHUB_API_URL\"]\n",
+    "token = os.environ[\"JUPYTERHUB_API_TOKEN\"]\n",
+    "username = os.environ[\"JUPYTERHUB_USER\"]\n",
+    "user_server = f\"{username}/{os.environ['JUPYTERHUB_SERVER_NAME']}\"\n",
+    "hub_host = os.environ[\"JUPYTERHUB_HOST\"]\n",
+    "server_base_url = os.environ[\"JUPYTERHUB_SERVICE_PREFIX\"]\n",
+    "\n",
+    "hub_api"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "456697ab-e7ce-4f75-bc8f-3ce424830e0d",
+   "metadata": {},
+   "source": [
+    "Create a requests.Session to make jupyterhub API requests with our token"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "f3335eeb-64e5-4caa-acb5-1032aaf727bb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import requests\n",
+    "\n",
+    "session = requests.Session()\n",
+    "session.headers = {\"Authorization\": f\"Bearer {token}\"}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3cf5605b-2022-4d2a-b0cc-de6f80e8f2fe",
+   "metadata": {},
+   "source": [
+    "We can check the permissions our token has with a request to /hub/api/user:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "17529af3-5ec8-4495-9183-bd5d423a1d76",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'kind': 'user',\n",
+       " 'last_activity': '2024-01-23T11:43:50.800864Z',\n",
+       " 'groups': [],\n",
+       " 'admin': False,\n",
+       " 'name': 'sharer',\n",
+       " 'servers': {'': {'name': '',\n",
+       "   'full_name': 'sharer/',\n",
+       "   'last_activity': '2024-01-23T11:43:50.800864Z',\n",
+       "   'started': '2024-01-23T11:28:44.948553Z',\n",
+       "   'pending': None,\n",
+       "   'ready': True,\n",
+       "   'stopped': False,\n",
+       "   'url': '/user/sharer/',\n",
+       "   'user_options': {},\n",
+       "   'progress_url': '/hub/api/users/sharer/server/progress'}},\n",
+       " 'session_id': None,\n",
+       " 'scopes': ['access:servers!server=sharer/',\n",
+       "  'delete:servers!server=sharer/',\n",
+       "  'groups:shares!server=sharer/',\n",
+       "  'read:groups:shares!server=sharer/',\n",
+       "  'read:servers!server=sharer/',\n",
+       "  'read:shares!server=sharer/',\n",
+       "  'read:users:activity!user=sharer',\n",
+       "  'read:users:groups!user=sharer',\n",
+       "  'read:users:name!user=sharer',\n",
+       "  'servers!server=sharer/',\n",
+       "  'shares!server=sharer/',\n",
+       "  'users:activity!server=sharer/',\n",
+       "  'users:activity!user=sharer',\n",
+       "  'users:shares!server=sharer/']}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "r = session.get(f\"{hub_api}/user\")\n",
+    "r.json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a14578b8-577e-4b0a-b74c-40d7a04a1a1a",
+   "metadata": {},
+   "source": [
+    "We can see who has access to this server:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "63520e3c-3621-4ebf-9775-52e6150ccca5",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'items': [],\n",
+       " '_pagination': {'offset': 0, 'limit': 200, 'total': 0, 'next': None}}"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "shares_url = f\"{hub_api}/shares/{user_server}\"\n",
+    "share_codes_url = f\"{hub_api}/share-codes/{user_server}\"\n",
+    "r = session.get(shares_url)\n",
+    "r.json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c8870d0-5b7e-4065-b227-fd463289cfdf",
+   "metadata": {},
+   "source": [
+    "and if there are any outstanding codes:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "6fad5334-6034-48f8-b008-1fd3d6e4d139",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'items': [],\n",
+       " '_pagination': {'offset': 0, 'limit': 200, 'total': 0, 'next': None}}"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "r = session.get(share_codes_url)\n",
+    "r.json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e6d598b3-5eab-4d56-b2ea-9aec345a3948",
+   "metadata": {},
+   "source": [
+    "Next, we can create a code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "facb1872-44a5-4e4e-84d4-1fd829b1a27b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'server': {'user': {'name': 'sharer'},\n",
+       "  'name': '',\n",
+       "  'url': '/user/sharer/',\n",
+       "  'ready': True},\n",
+       " 'scopes': ['access:servers!server=sharer/'],\n",
+       " 'id': 'sc_1',\n",
+       " 'created_at': '2024-01-23T11:46:32.154416Z',\n",
+       " 'expires_at': '2024-01-24T11:46:32.153582Z',\n",
+       " 'exchange_count': 0,\n",
+       " 'last_exchanged_at': None,\n",
+       " 'code': 'gTs7DmIhFu6UG5VQkOzRMk2MN-cdDiQ_RONCnkaq5Cg',\n",
+       " 'accept_url': '/hub/accept-share?code=gTs7DmIhFu6UG5VQkOzRMk2MN-cdDiQ_RONCnkaq5Cg'}"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "r = session.post(share_codes_url)\n",
+    "code_info = r.json()\n",
+    "code_info"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "83e23f83-18cb-4e54-9683-68c2ab0fcfc2",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "    <a href='/hub/accept-share?code=gTs7DmIhFu6UG5VQkOzRMk2MN-cdDiQ_RONCnkaq5Cg'>share this link to grant access</a>\n",
+       "    "
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from IPython.display import HTML, display\n",
+    "\n",
+    "full_accept_url = f\"{hub_host}{code_info['accept_url']}\"\n",
+    "\n",
+    "display(\n",
+    "    HTML(f\"\"\"\n",
+    "    <a href='{full_accept_url}'>share this link to grant access</a>\n",
+    "    \"\"\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0ce4f6f8-a0f3-4556-ab25-1f86ef49a6db",
+   "metadata": {},
+   "source": [
+    "(in jupyterlab, shift-right-click to copy link)\n",
+    "\n",
+    "We can now give this to the shared-with user (i.e. us in another private browsing tab).\n",
+    "\n",
+    "After accepting the link, we can see who we've shared with again:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "e056a9f0-7cec-414b-a3ce-03c8abfbc087",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'items': [{'server': {'user': {'name': 'sharer'},\n",
+       "    'name': '',\n",
+       "    'url': '/user/sharer/',\n",
+       "    'ready': True},\n",
+       "   'scopes': ['access:servers!server=sharer/'],\n",
+       "   'user': {'name': 'shared-with'},\n",
+       "   'group': None,\n",
+       "   'kind': 'user',\n",
+       "   'created_at': '2024-01-23T11:46:43.585455Z'}],\n",
+       " '_pagination': {'offset': 0, 'limit': 200, 'total': 1, 'next': None}}"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "session.get(shares_url).json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9933ef79-3f59-45fc-92a9-13e7bc1f3b82",
+   "metadata": {},
+   "source": [
+    "The share code can also include a `?next=` url parameter, to enable a link to take users to a specific file or view after accepting the code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "9c313d99-4dc9-45af-9643-f2b0e08b2bb4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "/hub/accept-share?code=gTs7DmIhFu6UG5VQkOzRMk2MN-cdDiQ_RONCnkaq5Cg&next=%2Fuser%2Fsharer%2Flab%2Ftree%2Fshare-api.ipynb\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "    share <a href='/hub/accept-share?code=gTs7DmIhFu6UG5VQkOzRMk2MN-cdDiQ_RONCnkaq5Cg&next=%2Fuser%2Fsharer%2Flab%2Ftree%2Fshare-api.ipynb'>this link</a>\n",
+       "    to grant access and direct users to this notebook\n",
+       "    "
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from urllib.parse import urlencode\n",
+    "\n",
+    "this_notebook_url = server_base_url + \"lab/tree/share-api.ipynb\"\n",
+    "this_notebook_accept_url = (\n",
+    "    full_accept_url + \"&\" + urlencode({\"next\": this_notebook_url})\n",
+    ")\n",
+    "print(this_notebook_accept_url)\n",
+    "\n",
+    "display(\n",
+    "    HTML(f\"\"\"\n",
+    "    share <a href='{this_notebook_accept_url}'>this link</a>\n",
+    "    to grant access and direct users to this notebook\n",
+    "    \"\"\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2455ba21-f558-4391-b8fc-6501feb3bbfb",
+   "metadata": {},
+   "source": [
+    "## Reviewing and managing access\n",
+    "\n",
+    "Listing share codes doesn't reveal the code - if you need to get a code, issue a new sharing code.\n",
+    "\n",
+    "But we can see in `exchange_count` whether and how often the code has been used"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "313116ed-2aa5-4a0a-bc91-f15a9428ae0c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'items': [{'server': {'user': {'name': 'sharer'},\n",
+       "    'name': '',\n",
+       "    'url': '/user/sharer/',\n",
+       "    'ready': True},\n",
+       "   'scopes': ['access:servers!server=sharer/'],\n",
+       "   'id': 'sc_1',\n",
+       "   'created_at': '2024-01-23T11:46:32.154416Z',\n",
+       "   'expires_at': '2024-01-24T11:46:32.153582Z',\n",
+       "   'exchange_count': 1,\n",
+       "   'last_exchanged_at': '2024-01-23T11:46:43.589701Z'}],\n",
+       " '_pagination': {'offset': 0, 'limit': 200, 'total': 1, 'next': None}}"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "session.get(share_codes_url).json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5f0d4d8e-fabb-4423-b9bd-d96643a9b9f7",
+   "metadata": {},
+   "source": [
+    "we can also revoke the code. Codes can be deleted by code or id"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "666ac28c-70f5-4a75-9bfa-6d26c5ea610f",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Response [204]>"
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "session.delete(share_codes_url + f\"?id={code_info['id']}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ce2fdb7f-a2de-4c95-996b-527ce0536794",
+   "metadata": {},
+   "source": [
+    "or if you're done sharing via code, you can delete all sharing codes for a server without looking it up their ids:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "4633b0af-ad75-4e72-9702-9cb16182aecb",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Response [204]>"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "session.delete(share_codes_url)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c322e058-bbf5-4058-8e20-415c7da0aa8a",
+   "metadata": {},
+   "source": [
+    "scopes and expiration can be customized in the request when creating the share code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "462bcec7-a899-4e3e-8e77-7d08adedb7a4",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Response [200]>"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import json\n",
+    "\n",
+    "options = {\n",
+    "    \"scopes\": [\n",
+    "        f\"access:servers!server={user_server}\",  # access the server (default)\n",
+    "        f\"servers!server={user_server}\",  # start/stop the server\n",
+    "        f\"shares!server={user_server}\",  # further share the server with others\n",
+    "    ],\n",
+    "    \"expires_in\": 3600,  # code expires in one hour\n",
+    "}\n",
+    "\n",
+    "\n",
+    "session.post(share_codes_url, data=json.dumps(options))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "c8babe6c-6339-4990-9241-d3db54205108",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'items': [{'server': {'user': {'name': 'sharer'},\n",
+       "    'name': '',\n",
+       "    'url': '/user/sharer/',\n",
+       "    'ready': True},\n",
+       "   'scopes': ['access:servers!server=sharer/'],\n",
+       "   'user': {'name': 'shared-with'},\n",
+       "   'group': None,\n",
+       "   'kind': 'user',\n",
+       "   'created_at': '2024-01-23T11:46:43.585455Z'}],\n",
+       " '_pagination': {'offset': 0, 'limit': 200, 'total': 1, 'next': None}}"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "r = session.get(shares_url)\n",
+    "r.json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "616d8f46-940d-4527-98a7-27894a23974f",
+   "metadata": {},
+   "source": [
+    "## Revoking permissions\n",
+    "\n",
+    "We can revoke specific permssions via a PATCH request\n",
+    "by specifying the user (or group) and one or more scopes:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "id": "13d54943-e95a-4222-a67d-8f3832b70e3c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Response [200]>"
+      ]
+     },
+     "execution_count": 15,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "options = {\n",
+    "    \"user\": \"shared-with\",\n",
+    "    \"scopes\": ['shares!server=sharer/'],\n",
+    "}\n",
+    "\n",
+    "session.patch(shares_url, data=json.dumps(options))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0b2b2619-3bb4-41a7-852b-de019f49185e",
+   "metadata": {},
+   "source": [
+    "If scopes are unspecified, all permissions are revoked:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "1d8997fa-7093-44dd-abdf-405fe8cc7fcd",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Response [200]>"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "options = {\n",
+    "    \"user\": \"shared-with\",\n",
+    "}\n",
+    "\n",
+    "session.patch(shares_url, data=json.dumps(options))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bb4e37a4-d206-420b-ad21-93a15c65bbd9",
+   "metadata": {},
+   "source": [
+    "_All_ shared access can be revoked via a DELETE request to the shares URL:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "id": "203ec184-df77-493b-bd8f-e6bb461abe7e",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Response [204]>"
+      ]
+     },
+     "execution_count": 17,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "session.delete(shares_url)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "129d98a3-df16-4607-8a9d-784843a7eeaf",
+   "metadata": {},
+   "source": [
+    "and we can see that nobody has shared access anymore"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "id": "d40f97b8-171f-4958-9cbf-bcc08a5f0db7",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'items': [],\n",
+       " '_pagination': {'offset': 0, 'limit': 200, 'total': 0, 'next': None}}"
+      ]
+     },
+     "execution_count": 18,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "session.get(shares_url).json()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/user-sharing/share-jupyterlab.ipynb

@@ -0,0 +1,403 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7609a68a-c01b-43a8-90aa-3d004af614dd",
+   "metadata": {},
+   "source": [
+    "# Sharing access to a server\n",
+    "\n",
+    "This notebook executes some javascript in the browser, using the user's OAuth token.\n",
+    "\n",
+    "This code would normally reside in a jupyterlab extension.\n",
+    "The notebook serves only for demonstration purposes.\n",
+    "\n",
+    "First, collect some configuration from the page, so we can talk to the JupyterHub API:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "b3cf16bd-ff9b-4140-a394-5a7ca5d96d88",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/javascript": [
+       "// define some globals to share\n",
+       "\n",
+       "var configElement = document.getElementById(\"jupyter-config-data\");\n",
+       "var jupyterConfig = JSON.parse(configElement.innerHTML);\n",
+       "\n",
+       "window.token = jupyterConfig.token;\n",
+       "window.hubOrigin = `${document.location.protocol}//${jupyterConfig.hubHost || window.location.host}`\n",
+       "window.hubUrl = `${hubOrigin}${jupyterConfig.hubPrefix}`;\n",
+       "window.shareCodesUrl = `${hubUrl}api/share-codes/${jupyterConfig.hubServerUser}/${jupyterConfig.hubServerName}`\n",
+       "window.sharesUrl = `${hubUrl}api/shares/${jupyterConfig.hubServerUser}/${jupyterConfig.hubServerName}`\n",
+       "console.log(shareCodesUrl);\n",
+       "\n",
+       "// utility function to make API requests and parse errors\n",
+       "window.apiRequest = async function (url, options) {\n",
+       "  var element = options.element;\n",
+       "  var okStatus = options.ok || 200;\n",
+       "  var resp = await fetch(url, {headers: {Authorization: `Bearer ${token}`}, method: options.method || 'GET'});\n",
+       "  var replyText = await resp.text();\n",
+       "  var replyJSON = {};\n",
+       "  if (replyText.length) {\n",
+       "     replyJSON = JSON.parse(replyText);\n",
+       "  }\n",
+       "  \n",
+       "  if (resp.status != okStatus) {\n",
+       "    var p = document.createElement('p');\n",
+       "    p.innerText = `Error ${resp.status}: ${replyJSON.message}`;\n",
+       "    element.appendChild(p);\n",
+       "    return;\n",
+       "  }\n",
+       "  return replyJSON;\n",
+       "}\n",
+       "\n",
+       "// `element` is a special variable for the current cell's output area\n",
+       "element.innerText = `API URL for sharing codes is: ${shareCodesUrl}`;\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Javascript object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%javascript\n",
+    "// define some globals to share\n",
+    "\n",
+    "var configElement = document.getElementById(\"jupyter-config-data\");\n",
+    "var jupyterConfig = JSON.parse(configElement.innerHTML);\n",
+    "\n",
+    "window.token = jupyterConfig.token;\n",
+    "window.hubOrigin = `${document.location.protocol}//${jupyterConfig.hubHost || window.location.host}`\n",
+    "window.hubUrl = `${hubOrigin}${jupyterConfig.hubPrefix}`;\n",
+    "window.shareCodesUrl = `${hubUrl}api/share-codes/${jupyterConfig.hubServerUser}/${jupyterConfig.hubServerName}`\n",
+    "window.sharesUrl = `${hubUrl}api/shares/${jupyterConfig.hubServerUser}/${jupyterConfig.hubServerName}`\n",
+    "console.log(shareCodesUrl);\n",
+    "\n",
+    "// utility function to make API requests and parse errors\n",
+    "window.apiRequest = async function (url, options) {\n",
+    "  var element = options.element;\n",
+    "  var okStatus = options.ok || 200;\n",
+    "  var resp = await fetch(url, {headers: {Authorization: `Bearer ${token}`}, method: options.method || 'GET'});\n",
+    "  var replyText = await resp.text();\n",
+    "  var replyJSON = {};\n",
+    "  if (replyText.length) {\n",
+    "     replyJSON = JSON.parse(replyText);\n",
+    "  }\n",
+    "  \n",
+    "  if (resp.status != okStatus) {\n",
+    "    var p = document.createElement('p');\n",
+    "    p.innerText = `Error ${resp.status}: ${replyJSON.message}`;\n",
+    "    element.appendChild(p);\n",
+    "    return;\n",
+    "  }\n",
+    "  return replyJSON;\n",
+    "}\n",
+    "\n",
+    "// `element` is a special variable for the current cell's output area\n",
+    "element.innerText = `API URL for sharing codes is: ${shareCodesUrl}`;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b2049fa1-bb60-4073-9167-2e116b198f0e",
+   "metadata": {},
+   "source": [
+    "Next, we can request a share code with\n",
+    "\n",
+    "```\n",
+    "POST $hub/api/share-codes/$user/$server\n",
+    "```\n",
+    "\n",
+    "The URL for _accepting_ a sharing invitation code is `/hub/accept-share?code=abc123...`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "ee9430f3-4866-41f7-942d-423bd48dc6b8",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/javascript": [
+       "\n",
+       "(async function f() {\n",
+       "  var shareCode = await apiRequest(shareCodesUrl, {method: 'POST', element: element});\n",
+       "\n",
+       "  // laziest way to display\n",
+       "  var shareCodeUrl = `${hubOrigin}${shareCode.accept_url}`\n",
+       "  var a = document.createElement('a');\n",
+       "  a.href = shareCodeUrl;\n",
+       "  a.innerText = shareCodeUrl;\n",
+       "  var p = document.createElement(p);\n",
+       "  p.append(\"Share this URL to grant access to this server: \");\n",
+       "  p.appendChild(a);\n",
+       "  element.appendChild(p);\n",
+       "})();\n",
+       "\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Javascript object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%javascript\n",
+    "\n",
+    "(async function f() {\n",
+    "  var shareCode = await apiRequest(shareCodesUrl, {method: 'POST', element: element});\n",
+    "\n",
+    "  // laziest way to display\n",
+    "  var shareCodeUrl = `${hubOrigin}${shareCode.accept_url}`\n",
+    "  var a = document.createElement('a');\n",
+    "  a.href = shareCodeUrl;\n",
+    "  a.innerText = shareCodeUrl;\n",
+    "  var p = document.createElement(p);\n",
+    "  p.append(\"Share this URL to grant access to this server: \");\n",
+    "  p.appendChild(a);\n",
+    "  element.appendChild(p);\n",
+    "})();\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "418152a0-2e0f-4ca6-8b53-9295d15c4345",
+   "metadata": {},
+   "source": [
+    "Share this URL to grant access to your server (e.g. visit the URL in a private window and login as the user `shared-with`).\n",
+    "\n",
+    "After our code has been used, we can see who has access to this server:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "5c9c6e1b-ccab-4c85-8afb-db141651236a",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/javascript": [
+       "\n",
+       "(async function f() {\n",
+       "\n",
+       "  var shares = await apiRequest(sharesUrl, {element: element});\n",
+       "\n",
+       "  var list = document.createElement('ul');\n",
+       "  for (var share of shares.items) {\n",
+       "    var p = document.createElement('li');\n",
+       "    p.append(`${share.kind} ${share[share.kind].name} has access: `)\n",
+       "    var scopes = document.createElement('tt');\n",
+       "    scopes.innerText = share.scopes.join(',');\n",
+       "    p.appendChild(scopes);\n",
+       "    list.append(p);\n",
+       "  }\n",
+       "  var p = document.createElement('p');\n",
+       "  p.innerText = `Shared with ${shares.items.length} users:`;\n",
+       "  element.appendChild(p);\n",
+       "  element.appendChild(list);\n",
+       "  return;\n",
+       "})();\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Javascript object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%javascript\n",
+    "\n",
+    "(async function f() {\n",
+    "\n",
+    "  var shares = await apiRequest(sharesUrl, {element: element});\n",
+    "\n",
+    "  var list = document.createElement('ul');\n",
+    "  for (var share of shares.items) {\n",
+    "    var p = document.createElement('li');\n",
+    "    p.append(`${share.kind} ${share[share.kind].name} has access: `)\n",
+    "    var scopes = document.createElement('tt');\n",
+    "    scopes.innerText = share.scopes.join(',');\n",
+    "    p.appendChild(scopes);\n",
+    "    list.append(p);\n",
+    "  }\n",
+    "  var p = document.createElement('p');\n",
+    "  p.innerText = `Shared with ${shares.items.length} users:`;\n",
+    "  element.appendChild(p);\n",
+    "  element.appendChild(list);\n",
+    "  return;\n",
+    "})();\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18165205-67f3-44d4-ad6b-40ab27ec469c",
+   "metadata": {},
+   "source": [
+    "We could also use this info to revoke permissions, or share with individuals by name.\n",
+    "\n",
+    "We can also review outstanding sharing _codes_:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "40cd1e2d-fc21-4238-8cbc-9ae45be248c9",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/javascript": [
+       "\n",
+       "(async function f() {\n",
+       "  var shareCodes = await apiRequest(shareCodesUrl, {element: element});\n",
+       "  var p = document.createElement('pre');\n",
+       "  p.innerText = JSON.stringify(shareCodes.items, null, ' ');\n",
+       "  element.appendChild(p);\n",
+       "})();\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Javascript object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%javascript\n",
+    "\n",
+    "(async function f() {\n",
+    "  var shareCodes = await apiRequest(shareCodesUrl, {element: element});\n",
+    "  var p = document.createElement('pre');\n",
+    "  p.innerText = JSON.stringify(shareCodes.items, null, ' ');\n",
+    "  element.appendChild(p);\n",
+    "})();\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0effee22-c132-4b44-a677-c4375594c462",
+   "metadata": {},
+   "source": [
+    "And finally, when we're done, we can revoke the codes, at which point nobody _new_ can use the code to gain access to this server,\n",
+    "but anyone who has accepted the code will still have access:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "51a795f5-9a74-49b1-9ef3-e7978da0cc44",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/javascript": [
+       "\n",
+       "(async function f() {\n",
+       "  await apiRequest(shareCodesUrl, {method: 'DELETE', element: element, ok: 204});\n",
+       "  var p = document.createElement('p');\n",
+       "  p.innerText = `Deleted all share codes`;\n",
+       "  element.appendChild(p);  \n",
+       "})();\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Javascript object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%javascript\n",
+    "\n",
+    "(async function f() {\n",
+    "  await apiRequest(shareCodesUrl, {method: 'DELETE', element: element, ok: 204});\n",
+    "  var p = document.createElement('p');\n",
+    "  p.innerText = `Deleted all share codes`;\n",
+    "  element.appendChild(p);  \n",
+    "})();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2ad12718-1f68-4d2f-9934-dd6bd4555a1d",
+   "metadata": {},
+   "source": [
+    "Or even revoke all shared access, so anyone who may have used the code no longer has any access:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "efa5ae15-ac99-4bf4-b7b4-3d93747dba8c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/javascript": [
+       "\n",
+       "(async function f() {\n",
+       "  var resp = await apiRequest(sharesUrl, {method: 'DELETE', element: element, ok: 204});\n",
+       "  var p = document.createElement('p');\n",
+       "  p.innerText = `Deleted all shared access`;\n",
+       "  element.appendChild(p);  \n",
+       "})();\n"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Javascript object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%javascript\n",
+    "\n",
+    "(async function f() {\n",
+    "  var resp = await apiRequest(sharesUrl, {method: 'DELETE', element: element, ok: 204});\n",
+    "  var p = document.createElement('p');\n",
+    "  p.innerText = `Deleted all shared access`;\n",
+    "  element.appendChild(p);  \n",
+    "})();"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

jsx/.gitignore

@@ -1,2 +1,3 @@
 node_modules
 build/admin-react.js
+.yarn

jsx/README.md

@@ -7,11 +7,11 @@ admin dashboard codebase.
 
 ### Build Commands
 
-- `yarn build`: Installs all dependencies and bundles the application
-- `yarn hot`: Bundles the application and runs a mock (serverless) version on port 8000
-- `yarn lint`: Lints JSX with ESLint
-- `yarn lint --fix`: Lints and fixes errors JSX with ESLint / formats with Prettier
-- `yarn place`: Copies the transpiled React bundle to /share/jupyterhub/static/js/admin-react.js for use.
+- `npm run build`: Installs all dependencies and bundles the application
+- `npm run hot`: Bundles the application and runs a mock (serverless) version on port 8000
+- `npm run lint`: Lints JSX with ESLint
+- `npm run lint --fix`: Lints and fixes errors JSX with ESLint / formats with Prettier
+- `npm run place`: Copies the transpiled React bundle to share/jupyterhub/static/js/admin-react.js for use.
 
 ### Good To Know
 

jsx/package.json

@@ -6,9 +6,9 @@
   "author": "nabarber",
   "license": "BSD-3-Clause",
   "scripts": {
-    "build": "yarn && webpack",
+    "build": "webpack",
+    "build:watch": "webpack watch",
     "hot": "webpack && webpack-dev-server",
-    "place": "cp build/admin-react.js* ../share/jupyterhub/static/js/",
     "test": "jest --verbose",
     "snap": "jest --updateSnapshot",
     "lint": "eslint --ext .jsx --ext .js src/",
@@ -34,12 +34,12 @@
     "lodash": "^4.17.21",
     "prop-types": "^15.8.1",
     "react": "^17.0.2",
-    "react-bootstrap": "^2.7.4",
+    "react-bootstrap": "^2.10.1",
     "react-dom": "^17.0.2",
     "react-icons": "^4.8.0",
     "react-multi-select-component": "^4.3.4",
     "react-redux": "^7.2.8",
-    "react-router-dom": "^5.3.4",
+    "react-router-dom": "^6.22.2",
     "recompose": "npm:react-recompose@^0.33.0",
     "redux": "^4.2.1",
     "regenerator-runtime": "^0.13.11"
@@ -64,7 +64,6 @@
     "jest": "^29.5.0",
     "jest-environment-jsdom": "^29.5.0",
     "prettier": "^2.8.7",
-    "sinon": "^15.0.3",
     "style-loader": "^3.3.2",
     "webpack": "^5.79.0",
     "webpack-cli": "^5.0.1",

jsx/src/App.jsx

@@ -5,7 +5,7 @@ import { createStore } from "redux";
 import { compose } from "recompose";
 import { initialState, reducers } from "./Store";
 import withAPI from "./util/withAPI";
-import { HashRouter, Switch, Route } from "react-router-dom";
+import { HashRouter, Routes, Route } from "react-router-dom";
 
 import ServerDashboard from "./components/ServerDashboard/ServerDashboard";
 import Groups from "./components/Groups/Groups";
@@ -23,34 +23,17 @@ const App = () => {
     <div className="resets">
       <Provider store={store}>
         <HashRouter>
-          <Switch>
+          <Routes>
+            <Route path="/" element={compose(withAPI)(ServerDashboard)()} />
+            <Route path="/groups" element={compose(withAPI)(Groups)()} />
+            <Route path="/group-edit" element={compose(withAPI)(GroupEdit)()} />
             <Route
-              exact
-              path="/"
-              component={compose(withAPI)(ServerDashboard)}
-            />
-            <Route exact path="/groups" component={compose(withAPI)(Groups)} />
-            <Route
-              exact
-              path="/group-edit"
-              component={compose(withAPI)(GroupEdit)}
-            />
-            <Route
-              exact
               path="/create-group"
-              component={compose(withAPI)(CreateGroup)}
+              element={compose(withAPI)(CreateGroup)()}
             />
-            <Route
-              exact
-              path="/add-users"
-              component={compose(withAPI)(AddUser)}
-            />
-            <Route
-              exact
-              path="/edit-user"
-              component={compose(withAPI)(EditUser)}
-            />
-          </Switch>
+            <Route path="/add-users" element={compose(withAPI)(AddUser)()} />
+            <Route path="/edit-user" element={compose(withAPI)(EditUser)()} />
+          </Routes>
         </HashRouter>
       </Provider>
     </div>

jsx/src/Store.js

@@ -1,48 +1,20 @@
 export const initialState = {
   user_data: undefined,
-  user_page: { offset: 0, limit: window.api_page_limit || 100 },
-  name_filter: "",
+  user_page: undefined,
   groups_data: undefined,
-  groups_page: { offset: 0, limit: window.api_page_limit || 100 },
+  groups_page: undefined,
   limit: window.api_page_limit || 100,
 };
 
 export const reducers = (state = initialState, action) => {
   switch (action.type) {
     // Updates the client user model data and stores the page
-    case "USER_OFFSET":
-      return Object.assign({}, state, {
-        user_page: Object.assign({}, state.user_page, {
-          offset: action.value.offset,
-        }),
-      });
-
-    case "USER_NAME_FILTER":
-      // set offset to 0 if name filter changed,
-      // otherwise leave it alone
-      const newOffset =
-        action.value.name_filter !== state.name_filter ? 0 : state.name_filter;
-      return Object.assign({}, state, {
-        user_page: Object.assign({}, state.user_page, {
-          offset: newOffset,
-        }),
-        name_filter: action.value.name_filter,
-      });
-
     case "USER_PAGE":
       return Object.assign({}, state, {
         user_page: action.value.page,
         user_data: action.value.data,
       });
 
-    // Updates the client group user model data and stores the page
-    case "GROUPS_OFFSET":
-      return Object.assign({}, state, {
-        groups_page: Object.assign({}, state.groups_page, {
-          offset: action.value.offset,
-        }),
-      });
-
     case "GROUPS_PAGE":
       return Object.assign({}, state, {
         groups_page: action.value.page,

jsx/src/components/AddUser/AddUser.jsx

@@ -1,15 +1,18 @@
 import React, { useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
-import { Link } from "react-router-dom";
+import { Link, useNavigate } from "react-router-dom";
+import { Button, Col } from "react-bootstrap";
 import PropTypes from "prop-types";
+import ErrorAlert from "../../util/error";
 
 const AddUser = (props) => {
-  var [users, setUsers] = useState([]),
+  const [users, setUsers] = useState([]),
     [admin, setAdmin] = useState(false),
     [errorAlert, setErrorAlert] = useState(null),
     limit = useSelector((state) => state.limit);
 
-  var dispatch = useDispatch();
+  const dispatch = useDispatch();
+  const navigate = useNavigate();
 
   var dispatchPageChange = (data, page) => {
     dispatch({
@@ -21,36 +24,19 @@ const AddUser = (props) => {
     });
   };
 
-  var { addUsers, updateUsers, history } = props;
+  var { addUsers, updateUsers } = props;
 
   return (
     <>
       <div className="container" data-testid="container">
-        {errorAlert != null ? (
+        <ErrorAlert errorAlert={errorAlert} setErrorAlert={setErrorAlert} />
         <div className="row">
-            <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-              <div className="alert alert-danger">
-                {errorAlert}
-                <button
-                  type="button"
-                  className="close"
-                  onClick={() => setErrorAlert(null)}
-                >
-                  <span>&times;</span>
-                </button>
-              </div>
-            </div>
-          </div>
-        ) : (
-          <></>
-        )}
-        <div className="row">
-          <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-            <div className="panel panel-default">
-              <div className="panel-heading">
+          <Col md={{ span: 10, offset: 1 }} lg={{ span: 8, offset: 2 }}>
+            <div className="card">
+              <div className="card-header">
                 <h4>Add Users</h4>
               </div>
-              <div className="panel-body">
+              <div className="card-body">
                 <form>
                   <div className="form-group">
                     <textarea
@@ -81,22 +67,24 @@ const AddUser = (props) => {
                   </div>
                 </form>
               </div>
-              <div className="panel-footer">
-                <button id="return" className="btn btn-light">
-                  <Link to="/">Back</Link>
-                </button>
+              <div className="card-footer">
+                <Link to="/">
+                  <Button variant="light" id="return">
+                    Back
+                  </Button>
+                </Link>
                 <span> </span>
-                <button
+                <Button
                   id="submit"
                   data-testid="submit"
-                  className="btn btn-primary"
+                  variant="primary"
                   onClick={() => {
                     addUsers(users, admin)
                       .then((data) =>
                         data.status < 300
                           ? updateUsers(0, limit)
                               .then((data) => dispatchPageChange(data, 0))
-                              .then(() => history.push("/"))
+                              .then(() => navigate("/"))
                               .catch(() =>
                                 setErrorAlert(`Failed to update users.`),
                               )
@@ -110,10 +98,10 @@ const AddUser = (props) => {
                   }}
                 >
                   Add Users
-                </button>
-              </div>
+                </Button>
               </div>
             </div>
+          </Col>
         </div>
       </div>
     </>
@@ -123,9 +111,6 @@ const AddUser = (props) => {
 AddUser.propTypes = {
   addUsers: PropTypes.func,
   updateUsers: PropTypes.func,
-  history: PropTypes.shape({
-    push: PropTypes.func,
-  }),
 };
 
 export default AddUser;

jsx/src/components/AddUser/AddUser.test.js

@@ -26,11 +26,7 @@ var mockAsyncRejection = () =>
 var addUserJsx = (spy, spy2, spy3) => (
   <Provider store={createStore(() => {}, {})}>
     <HashRouter>
-      <AddUser
-        addUsers={spy}
-        updateUsers={spy3 || spy2 || spy}
-        history={{ push: () => {} }}
-      />
+      <AddUser addUsers={spy} updateUsers={spy3 || spy2 || spy} />
     </HashRouter>
   </Provider>
 );

jsx/src/components/CreateGroup/CreateGroup.jsx

@@ -1,16 +1,19 @@
 import React, { useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
-import { Link } from "react-router-dom";
+import { Link, useNavigate } from "react-router-dom";
+import { Button, Card } from "react-bootstrap";
 import PropTypes from "prop-types";
+import { MainContainer } from "../../util/layout";
 
 const CreateGroup = (props) => {
-  var [groupName, setGroupName] = useState(""),
+  const [groupName, setGroupName] = useState(""),
     [errorAlert, setErrorAlert] = useState(null),
     limit = useSelector((state) => state.limit);
 
-  var dispatch = useDispatch();
+  const dispatch = useDispatch();
+  const navigate = useNavigate();
 
-  var dispatchPageUpdate = (data, page) => {
+  const dispatchPageUpdate = (data, page) => {
     dispatch({
       type: "GROUPS_PAGE",
       value: {
@@ -20,36 +23,15 @@ const CreateGroup = (props) => {
     });
   };
 
-  var { createGroup, updateGroups, history } = props;
+  const { createGroup, updateGroups } = props;
 
   return (
-    <>
-      <div className="container" data-testid="container">
-        {errorAlert != null ? (
-          <div className="row">
-            <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-              <div className="alert alert-danger">
-                {errorAlert}
-                <button
-                  type="button"
-                  className="close"
-                  onClick={() => setErrorAlert(null)}
-                >
-                  <span>&times;</span>
-                </button>
-              </div>
-            </div>
-          </div>
-        ) : (
-          <></>
-        )}
-        <div className="row">
-          <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-            <div className="panel panel-default">
-              <div className="panel-heading">
+    <MainContainer errorAlert={errorAlert} setErrorAlert={setErrorAlert}>
+      <Card>
+        <Card.Header>
           <h4>Create Group</h4>
-              </div>
-              <div className="panel-body">
+        </Card.Header>
+        <Card.Body>
           <div className="input-group">
             <input
               className="group-name-input"
@@ -63,31 +45,31 @@ const CreateGroup = (props) => {
               }}
             ></input>
           </div>
-              </div>
-              <div className="panel-footer">
-                <button id="return" className="btn btn-light">
-                  <Link to="/">Back</Link>
-                </button>
+        </Card.Body>
+        <Card.Footer>
+          <Link to="/groups">
+            <Button variant="light" id="return">
+              Back
+            </Button>
+          </Link>
           <span> </span>
-                <button
+          <Button
             id="submit"
             data-testid="submit"
-                  className="btn btn-primary"
+            variant="primary"
             onClick={() => {
               createGroup(groupName)
                 .then((data) => {
                   return data.status < 300
                     ? updateGroups(0, limit)
                         .then((data) => dispatchPageUpdate(data, 0))
-                              .then(() => history.push("/groups"))
+                        .then(() => navigate("/groups"))
                         .catch(() =>
                           setErrorAlert(`Could not update groups list.`),
                         )
                     : setErrorAlert(
                         `Failed to create group. ${
-                                data.status == 409
-                                  ? "Group already exists."
-                                  : ""
+                          data.status == 409 ? "Group already exists." : ""
                         }`,
                       );
                 })
@@ -95,22 +77,16 @@ const CreateGroup = (props) => {
             }}
           >
             Create
-                </button>
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </>
+          </Button>
+        </Card.Footer>
+      </Card>
+    </MainContainer>
   );
 };
 
 CreateGroup.propTypes = {
   createGroup: PropTypes.func,
   updateGroups: PropTypes.func,
-  history: PropTypes.shape({
-    push: PropTypes.func,
-  }),
 };
 
 export default CreateGroup;

jsx/src/components/CreateGroup/CreateGroup.test.js

@@ -25,11 +25,7 @@ var mockAsyncRejection = () =>
 var createGroupJsx = (callbackSpy) => (
   <Provider store={createStore(() => {}, {})}>
     <HashRouter>
-      <CreateGroup
-        createGroup={callbackSpy}
-        updateGroups={callbackSpy}
-        history={{ push: () => {} }}
-      />
+      <CreateGroup createGroup={callbackSpy} updateGroups={callbackSpy} />
     </HashRouter>
   </Provider>
 );

jsx/src/components/DynamicTable/DynamicTable.jsx

@@ -1,6 +1,7 @@
-import React, { useState, useEffect } from "react";
+import React, { useState } from "react";
 import "./table-select.css";
 import PropTypes from "prop-types";
+import { Button } from "react-bootstrap";
 
 const DynamicTable = (props) => {
   var [message, setMessage] = useState(""),
@@ -32,7 +33,7 @@ const DynamicTable = (props) => {
     setMessage2("");
   };
 
-  const handleClick = () => {
+  const handleAddItem = () => {
     if (message != "") {
       if (message2 != "") {
         propkeys.push(message);
@@ -52,14 +53,12 @@ const DynamicTable = (props) => {
     setOwnValues(propvalues);
     setMessage("");
     setMessage2("");
-    console.log(propkeys);
-    console.log(propvalues);
-    console.log(propobject);
   };
 
-  const renderKeyRows = () => {
-    if (propkeys) {
-      return propkeys.map(function (o, i) {
+  const KeyValueRow = (i) => {
+    // one table row for a key-value pair
+    const key = propkeys[i];
+    const value = propvalues[i];
     return (
       <tr key={"item-" + i}>
         <td>
@@ -67,7 +66,7 @@ const DynamicTable = (props) => {
             className="form-control"
             type="text"
             value={propkeys[i]}
-                id={o}
+            id={key}
             onChange={(e) => {
               if (e.target.value != "") {
                 propkeys[i] = e.target.value;
@@ -82,23 +81,11 @@ const DynamicTable = (props) => {
             }}
           />
         </td>
-          </tr>
-        );
-      });
-    }
-  };
-  const renderValueRows = () => {
-    if (propvalues) {
-      return propvalues.map(function (o, i) {
-        //console.log("ValRows" +i)
-        //console.log("ValRows" +o)
-        return (
-          <tr key={"item-" + i}>
         <td>
           <input
             className="form-control"
             type="text"
-                value={o}
+            value={value}
             onChange={(e) => {
               propvalues[i] = e.target.value;
               props.setPropValues(propvalues);
@@ -107,26 +94,14 @@ const DynamicTable = (props) => {
             }}
           />
         </td>
-          </tr>
-        );
-      });
-    }
-  };
-  const renderDelete = () => {
-    if (propvalues) {
-      return propvalues.map(function (o, i) {
-        return (
-          <tr key={"item-" + i}>
         <td>
-              <button
-                className="btn btn-default"
+          <Button
+            variant="danger"
             onClick={() => {
               propvalues.splice(i, 1);
               propkeys.splice(i, 1);
               var propobject = {};
-                  propkeys.forEach(
-                    (key, i) => (propobject[key] = propvalues[i]),
-                  );
+              propkeys.forEach((key, i) => (propobject[key] = propvalues[i]));
               props.setProp(propobject);
               props.setPropKeys(propkeys);
               props.setPropValues(propvalues);
@@ -136,17 +111,20 @@ const DynamicTable = (props) => {
             }}
           >
             Delete
-              </button>
+          </Button>
         </td>
       </tr>
     );
-      });
-    }
+  };
+
+  const renderKeyValueRows = () => {
+    if (!propkeys) return null;
+    return propkeys.map((key, i) => KeyValueRow(i));
   };
 
   return (
     <div>
-      <table className="">
+      <table className="properties-table">
         <thead>
           <tr>
             <th>Key</th>
@@ -154,14 +132,7 @@ const DynamicTable = (props) => {
           </tr>
         </thead>
         <tbody>
-          <tr>
-            <td>{renderKeyRows()}</td>
-            <td>{renderValueRows()}</td>
-            <td>{renderDelete()}</td>
-          </tr>
-        </tbody>
-      </table>
-      <form>
+          {renderKeyValueRows()}
           <tr>
             <td>
               <input
@@ -180,18 +151,18 @@ const DynamicTable = (props) => {
               />
             </td>
             <td>
-            <button
+              <Button
                 id="add-item"
                 data-testid="add-item"
-              className="btn btn-default"
-              type="button"
-              onClick={() => handleClick()}
+                className="text-nowrap"
+                onClick={() => handleAddItem()}
               >
                 Add Item
-            </button>
+              </Button>
             </td>
           </tr>
-      </form>
+        </tbody>
+      </table>
       <hr />
     </div>
   );
@@ -199,8 +170,9 @@ const DynamicTable = (props) => {
 DynamicTable.propTypes = {
   current_keys: PropTypes.array,
   current_values: PropTypes.array,
-  setPropKeys: PropTypes.array,
-  setPropValues: PropTypes.array,
+  current_propobject: PropTypes.object,
+  setPropKeys: PropTypes.func,
+  setPropValues: PropTypes.func,
   setProp: PropTypes.func,
 };
 export default DynamicTable;

jsx/src/components/DynamicTable/table-select.css

@@ -1,14 +1,12 @@
 @import url(../../style/root.css);
 
 .properties-table {
-  width: 95%;
   position: relative;
   padding: 5px;
   overflow-x: scroll;
 }
 
 .properties-table-keyvalues {
-  width: 95%;
   position: relative;
   padding: 5px;
   overflow-x: scroll;

jsx/src/components/EditUser/EditUser.jsx

@@ -1,13 +1,17 @@
-import React, { useState } from "react";
+import React, { useEffect, useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
 import PropTypes from "prop-types";
-import { Link } from "react-router-dom";
+import { Link, useLocation, useNavigate } from "react-router-dom";
+import { Button, Card } from "react-bootstrap";
+import { MainContainer } from "../../util/layout";
 
 const EditUser = (props) => {
-  var limit = useSelector((state) => state.limit),
+  const limit = useSelector((state) => state.limit),
     [errorAlert, setErrorAlert] = useState(null);
 
-  var dispatch = useDispatch();
+  const dispatch = useDispatch();
+  const location = useLocation();
+  const navigate = useNavigate();
 
   var dispatchPageChange = (data, page) => {
     dispatch({
@@ -19,46 +23,30 @@ const EditUser = (props) => {
     });
   };
 
-  var { editUser, deleteUser, noChangeEvent, updateUsers, history } = props;
+  var { editUser, deleteUser, noChangeEvent, updateUsers } = props;
 
-  if (props.location.state == undefined) {
-    props.history.push("/");
-    return <></>;
+  useEffect(() => {
+    if (!location.state) {
+      navigate("/");
+    }
+  }, [location]);
+
+  if (!location.state) {
+    return null;
   }
 
-  var { username, has_admin } = props.location.state;
+  var { username, has_admin } = location.state;
 
   var [updatedUsername, setUpdatedUsername] = useState(""),
     [admin, setAdmin] = useState(has_admin);
 
   return (
-    <>
-      <div className="container" data-testid="container">
-        {errorAlert != null ? (
-          <div className="row">
-            <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-              <div className="alert alert-danger">
-                {errorAlert}
-                <button
-                  type="button"
-                  className="close"
-                  onClick={() => setErrorAlert(null)}
-                >
-                  <span>&times;</span>
-                </button>
-              </div>
-            </div>
-          </div>
-        ) : (
-          <></>
-        )}
-        <div className="row">
-          <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-            <div className="panel panel-default">
-              <div className="panel-heading">
-                <h4>Editing user {username}</h4>
-              </div>
-              <div className="panel-body">
+    <MainContainer errorAlert={errorAlert} setErrorAlert={setErrorAlert}>
+      <Card>
+        <Card.Header>
+          <h1>Editing user {username}</h1>
+        </Card.Header>
+        <Card.Body>
           <form>
             <div className="form-group">
               <textarea
@@ -81,45 +69,18 @@ const EditUser = (props) => {
               />
               <span> </span>
               <label className="form-check-label">Admin</label>
-                    <br></br>
-                    <button
-                      id="delete-user"
-                      data-testid="delete-user"
-                      className="btn btn-danger btn-sm"
-                      onClick={(e) => {
-                        e.preventDefault();
-                        deleteUser(username)
-                          .then((data) => {
-                            data.status < 300
-                              ? updateUsers(0, limit)
-                                  .then((data) => dispatchPageChange(data, 0))
-                                  .then(() => history.push("/"))
-                                  .catch(() =>
-                                    setErrorAlert(
-                                      `Could not update users list.`,
-                                    ),
-                                  )
-                              : setErrorAlert(`Failed to edit user.`);
-                          })
-                          .catch(() => {
-                            setErrorAlert(`Failed to edit user.`);
-                          });
-                      }}
-                    >
-                      Delete user
-                    </button>
             </div>
           </form>
-              </div>
-              <div className="panel-footer">
-                <button className="btn btn-light">
-                  <Link to="/">Back</Link>
-                </button>
+        </Card.Body>
+        <Card.Footer>
+          <Link to="/">
+            <Button variant="light">Back</Button>
+          </Link>
           <span> </span>
-                <button
+          <Button
             id="submit"
             data-testid="submit"
-                  className="btn btn-primary"
+            variant="primary"
             onClick={(e) => {
               e.preventDefault();
               if (updatedUsername == "" && admin == has_admin) {
@@ -135,7 +96,7 @@ const EditUser = (props) => {
                     data.status < 300
                       ? updateUsers(0, limit)
                           .then((data) => dispatchPageChange(data, 0))
-                                .then(() => history.push("/"))
+                          .then(() => navigate("/"))
                           .catch(() =>
                             setErrorAlert(`Could not update users list.`),
                           )
@@ -148,26 +109,39 @@ const EditUser = (props) => {
             }}
           >
             Apply
-                </button>
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </>
+          </Button>
+          <Button
+            id="delete-user"
+            data-testid="delete-user"
+            variant="danger"
+            className="float-end"
+            onClick={(e) => {
+              e.preventDefault();
+              deleteUser(username)
+                .then((data) => {
+                  data.status < 300
+                    ? updateUsers(0, limit)
+                        .then((data) => dispatchPageChange(data, 0))
+                        .then(() => navigate("/"))
+                        .catch(() =>
+                          setErrorAlert(`Could not update users list.`),
+                        )
+                    : setErrorAlert(`Failed to edit user.`);
+                })
+                .catch(() => {
+                  setErrorAlert(`Failed to edit user.`);
+                });
+            }}
+          >
+            Delete user
+          </Button>
+        </Card.Footer>
+      </Card>
+    </MainContainer>
   );
 };
 
 EditUser.propTypes = {
-  location: PropTypes.shape({
-    state: PropTypes.shape({
-      username: PropTypes.string,
-      has_admin: PropTypes.bool,
-    }),
-  }),
-  history: PropTypes.shape({
-    push: PropTypes.func,
-  }),
   editUser: PropTypes.func,
   deleteUser: PropTypes.func,
   noChangeEvent: PropTypes.func,

jsx/src/components/EditUser/EditUser.test.js

@@ -16,6 +16,14 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
+jest.mock("react-router-dom", () => ({
+  ...jest.requireActual("react-router-dom"),
+  useLocation: jest.fn().mockImplementation(() => {
+    return { state: { username: "foo", has_admin: false } };
+  }),
+  useNavigate: jest.fn(),
+}));
+
 var mockAsync = (data) =>
   jest.fn().mockImplementation(() => Promise.resolve(data));
 
@@ -26,11 +34,9 @@ var editUserJsx = (callbackSpy, empty) => (
   <Provider store={createStore(() => {}, {})}>
     <HashRouter>
       <EditUser
-        location={empty ? {} : { state: { username: "foo", has_admin: false } }}
         deleteUser={callbackSpy}
         editUser={callbackSpy}
         updateUsers={callbackSpy}
-        history={{ push: () => {} }}
         noChangeEvent={callbackSpy}
       />
     </HashRouter>

jsx/src/components/GroupEdit/GroupEdit.jsx

@@ -1,17 +1,21 @@
-import React, { useState } from "react";
+import React, { useEffect, useState } from "react";
 import { useSelector, useDispatch } from "react-redux";
-import { Link } from "react-router-dom";
+import { Link, useNavigate, useLocation } from "react-router-dom";
 import PropTypes from "prop-types";
+import { Button, Card } from "react-bootstrap";
 import GroupSelect from "../GroupSelect/GroupSelect";
 import DynamicTable from "../DynamicTable/DynamicTable";
+import { MainContainer } from "../../util/layout";
 
 const GroupEdit = (props) => {
-  var [selected, setSelected] = useState([]),
+  const [selected, setSelected] = useState([]),
     [changed, setChanged] = useState(false),
     [errorAlert, setErrorAlert] = useState(null),
+    navigate = useNavigate(),
+    location = useLocation(),
     limit = useSelector((state) => state.limit);
 
-  var dispatch = useDispatch();
+  const dispatch = useDispatch();
   const hasDuplicates = (a) => a.filter((e, i) => a.indexOf(e) != i).length > 0;
   const dispatchPageUpdate = (data, page) => {
     dispatch({
@@ -23,56 +27,35 @@ const GroupEdit = (props) => {
     });
   };
 
-  var {
+  const {
     addToGroup,
     updateProp,
     removeFromGroup,
     deleteGroup,
     updateGroups,
     validateUser,
-    history,
-    location,
   } = props;
 
+  useEffect(() => {
     if (!location.state) {
-    history.push("/groups");
-    return <></>;
+      navigate("/groups");
     }
+  }, [location]);
 
-  var { group_data } = location.state;
-  var [propobject, setProp] = useState(group_data.properties);
-  var [propkeys, setPropKeys] = useState([]);
-  var [propvalues, setPropValues] = useState([]);
-
+  const { group_data } = location.state || {};
   if (!group_data) return <div></div>;
+  const [propobject, setProp] = useState(group_data.properties);
+  const [propkeys, setPropKeys] = useState([]);
+  const [propvalues, setPropValues] = useState([]);
 
   return (
-    <div className="container" data-testid="container">
-      {errorAlert != null ? (
-        <div className="row">
-          <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-            <div className="alert alert-danger">
-              {errorAlert}
-              <button
-                type="button"
-                className="close"
-                onClick={() => setErrorAlert(null)}
-              >
-                <span>&times;</span>
-              </button>
-            </div>
-          </div>
-        </div>
-      ) : (
-        <></>
-      )}
-      <div className="row">
-        <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-          <h3>Editing Group {group_data.name}</h3>
-          <br></br>
-          <div className="alert alert-info">Manage group members</div>
-        </div>
-      </div>
+    <MainContainer errorAlert={errorAlert} setErrorAlert={setErrorAlert}>
+      <h1>Editing Group {group_data.name}</h1>
+      <Card>
+        <Card.Header>
+          <h2>Manage group members</h2>
+        </Card.Header>
+        <Card.Body>
           <GroupSelect
             users={group_data.users}
             validateUser={validateUser}
@@ -81,13 +64,11 @@ const GroupEdit = (props) => {
               setChanged(true);
             }}
           />
-      <div className="row">
-        <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-          <div className="alert alert-info">Manage group properties</div>
-        </div>
-      </div>
-      <div className="row">
-        <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
+        </Card.Body>
+        <Card.Header>
+          <h2>Manage group properties</h2>
+        </Card.Header>
+        <Card.Body>
           <DynamicTable
             current_propobject={group_data.properties}
             setProp={setProp}
@@ -96,19 +77,21 @@ const GroupEdit = (props) => {
 
             //Add keys
           />
+          <div>
+            <span id="error"></span>
           </div>
-      </div>
-
-      <div className="row">
-        <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-          <button id="return" className="btn btn-light">
-            <Link to="/groups">Back</Link>
-          </button>
+        </Card.Body>
+        <Card.Footer>
+          <Link to="/groups">
+            <Button variant="light" id="return">
+              Back
+            </Button>
+          </Link>
           <span> </span>
-          <button
+          <Button
             id="submit"
             data-testid="submit"
-            className="btn btn-primary"
+            variant="primary"
             onClick={() => {
               // check for changes
               let new_users = selected.filter(
@@ -156,15 +139,12 @@ const GroupEdit = (props) => {
             }}
           >
             Apply
-          </button>
-          <div>
-            <span id="error"></span>
-          </div>
-          <button
+          </Button>
+          <Button
             id="delete-group"
             data-testid="delete-group"
-            className="btn btn-danger"
-            style={{ float: "right" }}
+            variant="danger"
+            className="float-end"
             onClick={() => {
               var groupName = group_data.name;
               deleteGroup(groupName)
@@ -173,32 +153,24 @@ const GroupEdit = (props) => {
                   data.status < 300
                     ? updateGroups(0, limit)
                         .then((data) => dispatchPageUpdate(data, 0))
-                        .then(() => history.push("/groups"))
+                        .then(() => navigate("/groups"))
                     : setErrorAlert(`Failed to delete group.`);
                 })
                 .catch(() => setErrorAlert(`Failed to delete group.`));
             }}
           >
             Delete Group
-          </button>
-          <br></br>
-          <br></br>
-        </div>
-      </div>
+          </Button>
+          <div>
+            <span id="error"></span>
           </div>
+        </Card.Footer>
+      </Card>
+    </MainContainer>
   );
 };
 
 GroupEdit.propTypes = {
-  location: PropTypes.shape({
-    state: PropTypes.shape({
-      group_data: PropTypes.object,
-      callback: PropTypes.func,
-    }),
-  }),
-  history: PropTypes.shape({
-    push: PropTypes.func,
-  }),
   addToGroup: PropTypes.func,
   removeFromGroup: PropTypes.func,
   deleteGroup: PropTypes.func,

jsx/src/components/GroupEdit/GroupEdit.test.jsx

@@ -16,6 +16,14 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
+jest.mock("react-router-dom", () => ({
+  ...jest.requireActual("react-router-dom"),
+  useLocation: jest.fn().mockImplementation(() => {
+    return { state: { group_data: { users: ["foo"], name: "group" } } };
+  }),
+  useNavigate: jest.fn(),
+}));
+
 var mockAsync = (data) =>
   jest.fn().mockImplementation(() => Promise.resolve(data));
 
@@ -28,16 +36,9 @@ var groupEditJsx = (callbackSpy) => (
   <Provider store={createStore(() => {}, {})}>
     <HashRouter>
       <GroupEdit
-        location={{
-          state: {
-            group_data: { users: ["foo"], name: "group" },
-            callback: () => {},
-          },
-        }}
         addToGroup={callbackSpy}
         removeFromGroup={callbackSpy}
         deleteGroup={callbackSpy}
-        history={{ push: () => callbackSpy }}
         updateGroups={callbackSpy}
         validateUser={jest.fn().mockImplementation(() => okPacket)}
       />

jsx/src/components/GroupSelect/GroupSelect.jsx

@@ -1,5 +1,6 @@
 import React, { useState } from "react";
 import PropTypes from "prop-types";
+import { Button } from "react-bootstrap";
 import "./group-select.css";
 
 const GroupSelect = (props) => {
@@ -12,15 +13,12 @@ const GroupSelect = (props) => {
   if (!users) return null;
 
   return (
-    <div className="row">
+    <>
       {error != null ? (
-        <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2 text-left">
         <div className="alert alert-danger">{error}</div>
-        </div>
       ) : (
         <></>
       )}
-      <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2 text-left">
       <div className="input-group">
         <input
           id="username-input"
@@ -33,12 +31,9 @@ const GroupSelect = (props) => {
             setUsername(e.target.value);
           }}
         />
-          <span className="input-group-btn">
-            <button
+        <Button
           id="validate-user"
           data-testid="validate-user"
-              className="btn btn-default"
-              type="button"
           onClick={() => {
             validateUser(username).then((exists) => {
               if (exists && !selected.includes(username)) {
@@ -54,11 +49,8 @@ const GroupSelect = (props) => {
           }}
         >
           Add user
-            </button>
-          </span>
+        </Button>
       </div>
-      </div>
-      <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2 text-left">
       <div className="users-container">
         <hr></hr>
         <div>
@@ -94,10 +86,7 @@ const GroupSelect = (props) => {
           )}
         </div>
       </div>
-        <br></br>
-        <br></br>
-      </div>
-    </div>
+    </>
   );
 };
 

jsx/src/components/Groups/Groups.jsx

@@ -2,30 +2,27 @@ import React, { useEffect } from "react";
 import { useSelector, useDispatch } from "react-redux";
 import PropTypes from "prop-types";
 
-import { Link } from "react-router-dom";
+import { Button, Card } from "react-bootstrap";
+import { Link, useNavigate } from "react-router-dom";
+import { usePaginationParams } from "../../util/paginationParams";
 import PaginationFooter from "../PaginationFooter/PaginationFooter";
+import { MainContainer } from "../../util/layout";
 
 const Groups = (props) => {
-  var groups_data = useSelector((state) => state.groups_data),
-    groups_page = useSelector((state) => state.groups_page),
-    dispatch = useDispatch();
+  const groups_data = useSelector((state) => state.groups_data);
+  const groups_page = useSelector((state) => state.groups_page);
+  const dispatch = useDispatch();
+  const navigate = useNavigate();
 
-  var offset = groups_page ? groups_page.offset : 0;
+  const { setOffset, offset, handleLimit, limit, setPagination } =
+    usePaginationParams();
 
-  const setOffset = (offset) => {
-    dispatch({
-      type: "GROUPS_OFFSET",
-      value: {
-        offset: offset,
-      },
-    });
-  };
-  var limit = groups_page ? groups_page.limit : window.api_page_limit;
-  var total = groups_page ? groups_page.total : undefined;
+  const total = groups_page ? groups_page.total : undefined;
 
-  var { updateGroups, history } = props;
+  const { updateGroups } = props;
 
   const dispatchPageUpdate = (data, page) => {
+    setPagination(page);
     dispatch({
       type: "GROUPS_PAGE",
       value: {
@@ -46,29 +43,20 @@ const Groups = (props) => {
   }
 
   return (
-    <div className="container" data-testid="container">
-      <div className="row">
-        <div className="col-md-12 col-lg-10 col-lg-offset-1">
-          <div className="panel panel-default">
-            <div className="panel-heading">
+    <MainContainer>
+      <Card>
+        <Card.Header>
           <h4>Groups</h4>
-            </div>
-            <div className="panel-body">
+        </Card.Header>
+        <Card.Body>
           <ul className="list-group">
             {groups_data.length > 0 ? (
               groups_data.map((e, i) => (
                 <li className="list-group-item" key={"group-item" + i}>
-                      <span className="badge badge-pill badge-success">
+                  <span className="badge rounded-pill bg-success mx-2">
                     {e.users.length + " users"}
                   </span>
-                      <Link
-                        to={{
-                          pathname: "/group-edit",
-                          state: {
-                            group_data: e,
-                          },
-                        }}
-                      >
+                  <Link to="/group-edit" state={{ group_data: e }}>
                     {e.name}
                   </Link>
                 </li>
@@ -85,38 +73,29 @@ const Groups = (props) => {
             visible={groups_data.length}
             total={total}
             next={() => setOffset(offset + limit)}
-                prev={() => setOffset(offset >= limit ? offset - limit : 0)}
+            prev={() => setOffset(offset - limit)}
+            handleLimit={handleLimit}
           />
-            </div>
-            <div className="panel-footer">
-              <button className="btn btn-light adjacent-span-spacing">
-                <Link to="/">Back</Link>
-              </button>
-              <button
-                className="btn btn-primary adjacent-span-spacing"
-                onClick={() => {
-                  history.push("/create-group");
-                }}
-              >
-                New Group
-              </button>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
+        </Card.Body>
+        <Card.Footer>
+          <Link to="/">
+            <Button variant="light" id="return">
+              Back
+            </Button>
+          </Link>
+          <span> </span>
+          <Link to="/create-group">
+            <Button variant="primary">New Group</Button>
+          </Link>
+        </Card.Footer>
+      </Card>
+    </MainContainer>
   );
 };
 
 Groups.propTypes = {
   updateUsers: PropTypes.func,
   updateGroups: PropTypes.func,
-  history: PropTypes.shape({
-    push: PropTypes.func,
-  }),
-  location: PropTypes.shape({
-    search: PropTypes.string,
-  }),
 };
 
 export default Groups;

jsx/src/components/Groups/Groups.test.js

@@ -2,9 +2,9 @@ import React from "react";
 import "@testing-library/jest-dom";
 import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
-import { Provider, useDispatch, useSelector } from "react-redux";
+import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter, useSearchParams } from "react-router-dom";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,13 +16,18 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
+jest.mock("react-router-dom", () => ({
+  ...jest.requireActual("react-router-dom"),
+  useSearchParams: jest.fn(),
+}));
+
 var mockAsync = () =>
   jest.fn().mockImplementation(() => Promise.resolve({ key: "value" }));
 
 var groupsJsx = (callbackSpy) => (
   <Provider store={createStore(mockReducers, mockAppState())}>
     <HashRouter>
-      <Groups location={{ search: "0" }} updateGroups={callbackSpy} />
+      <Groups updateGroups={callbackSpy} />
     </HashRouter>
   </Provider>
 );
@@ -50,11 +55,6 @@ var mockAppState = () =>
       offset: 0,
       limit: 2,
       total: 4,
-      next: {
-        offset: 2,
-        limit: 2,
-        url: "http://localhost:8000/hub/api/groups?offset=2&limit=2",
-      },
     },
   });
 
@@ -62,11 +62,15 @@ beforeEach(() => {
   useSelector.mockImplementation((callback) => {
     return callback(mockAppState());
   });
+  useSearchParams.mockImplementation(() => {
+    return [new URLSearchParams(), jest.fn()];
+  });
 });
 
 afterEach(() => {
   useSelector.mockClear();
   mockReducers.mockClear();
+  useSearchParams.mockClear();
 });
 
 test("Renders", async () => {
@@ -109,13 +113,23 @@ test("Renders nothing if required data is not available", async () => {
 });
 
 test("Interacting with PaginationFooter causes state update and refresh via useEffect call", async () => {
-  let callbackSpy = mockAsync();
-
+  let upgradeGroupsSpy = mockAsync();
+  let setSearchParamsSpy = mockAsync();
+  let searchParams = new URLSearchParams({ limit: "2" });
+  useSearchParams.mockImplementation(() => [
+    searchParams,
+    (callback) => {
+      searchParams = callback(searchParams);
+      setSearchParamsSpy(searchParams.toString());
+    },
+  ]);
+  let _, setSearchParams;
   await act(async () => {
-    render(groupsJsx(callbackSpy));
+    render(groupsJsx(upgradeGroupsSpy));
+    [_, setSearchParams] = useSearchParams();
   });
 
-  expect(callbackSpy).toBeCalledWith(0, 2);
+  expect(upgradeGroupsSpy).toBeCalledWith(0, 2);
 
   var lastState =
     mockReducers.mock.results[mockReducers.mock.results.length - 1].value;
@@ -123,12 +137,10 @@ test("Interacting with PaginationFooter causes state update and refresh via useE
   expect(lastState.groups_page.limit).toEqual(2);
 
   let next = screen.getByTestId("paginate-next");
+  await act(async () => {
     fireEvent.click(next);
-
-  lastState =
-    mockReducers.mock.results[mockReducers.mock.results.length - 1].value;
-  expect(lastState.groups_page.offset).toEqual(2);
-  expect(lastState.groups_page.limit).toEqual(2);
+  });
+  expect(setSearchParamsSpy).toBeCalledWith("limit=2&offset=2");
 
   // FIXME: mocked useSelector, state seem to prevent updateGroups from being called
   // making the test environment not representative

jsx/src/components/PaginationFooter/PaginationFooter.jsx

@@ -1,18 +1,19 @@
 import React from "react";
 import PropTypes from "prop-types";
+import { Button, FormControl } from "react-bootstrap";
 
 import "./pagination-footer.css";
 
 const PaginationFooter = (props) => {
-  let { offset, limit, visible, total, next, prev } = props;
+  const { offset, limit, visible, total, next, prev, handleLimit } = props;
   return (
     <div className="pagination-footer">
       <p>
-        Displaying {offset}-{offset + visible}
-        <br></br>
-        <br></br>
+        Displaying {visible ? offset + 1 : offset}-{offset + visible}{" "}
+        {total ? `of ${total}` : ""}
+        <br />
         {offset >= 1 ? (
-          <button className="btn btn-sm btn-light spaced">
+          <Button variant="light" size="sm">
             <span
               className="active-pagination"
               data-testid="paginate-prev"
@@ -20,14 +21,14 @@ const PaginationFooter = (props) => {
             >
               Previous
             </span>
-          </button>
+          </Button>
         ) : (
-          <button className="btn btn-sm btn-light spaced">
+          <Button variant="light" size="sm">
             <span className="inactive-pagination">Previous</span>
-          </button>
+          </Button>
         )}
         {offset + visible < total ? (
-          <button className="btn btn-sm btn-light spaced">
+          <Button variant="light" size="sm">
             <span
               className="active-pagination"
               data-testid="paginate-next"
@@ -35,12 +36,25 @@ const PaginationFooter = (props) => {
             >
               Next
             </span>
-          </button>
+          </Button>
         ) : (
-          <button className="btn btn-sm btn-light spaced">
+          <Button variant="light" size="sm">
             <span className="inactive-pagination">Next</span>
-          </button>
+          </Button>
         )}
+        <label>
+          Items per page:
+          <FormControl
+            type="number"
+            min="25"
+            step="25"
+            name="pagination-limit"
+            placeholder={limit}
+            aria-label="pagination-limit"
+            defaultValue={limit}
+            onChange={handleLimit}
+          />
+        </label>
       </p>
     </div>
   );
@@ -48,10 +62,13 @@ const PaginationFooter = (props) => {
 
 PaginationFooter.propTypes = {
   endpoint: PropTypes.string,
-  page: PropTypes.number,
+  offset: PropTypes.number,
   limit: PropTypes.number,
-  numOffset: PropTypes.number,
-  numElements: PropTypes.number,
+  visible: PropTypes.number,
+  total: PropTypes.number,
+  handleLimit: PropTypes.func,
+  next: PropTypes.func,
+  prev: PropTypes.func,
 };
 
 export default PaginationFooter;

jsx/src/components/ServerDashboard/ServerDashboard.jsx

@@ -2,11 +2,13 @@ import React, { useEffect, useState, Fragment } from "react";
 import { useSelector, useDispatch } from "react-redux";
 import { debounce } from "lodash";
 import PropTypes from "prop-types";
+import ErrorAlert from "../../util/error";
 
 import {
   Button,
   Col,
   Row,
+  Form,
   FormControl,
   Card,
   CardGroup,
@@ -14,21 +16,14 @@ import {
 } from "react-bootstrap";
 import ReactObjectTableViewer from "../ReactObjectTableViewer/ReactObjectTableViewer";
 
-import { Link } from "react-router-dom";
+import { Link, useSearchParams, useNavigate } from "react-router-dom";
 import { FaSort, FaSortUp, FaSortDown } from "react-icons/fa";
 
 import "./server-dashboard.css";
 import { timeSince } from "../../util/timeSince";
+import { usePaginationParams } from "../../util/paginationParams";
 import PaginationFooter from "../PaginationFooter/PaginationFooter";
 
-const AccessServerButton = ({ url }) => (
-  <a href={url || ""}>
-    <button className="btn btn-primary btn-xs" style={{ marginRight: 20 }}>
-      Access Server
-    </button>
-  </a>
-);
-
 const RowListItem = ({ text }) => (
   <span className="server-dashboard-row-list-item">{text}</span>
 );
@@ -37,37 +32,26 @@ RowListItem.propTypes = {
 };
 
 const ServerDashboard = (props) => {
-  let base_url = window.base_url || "/";
-  // sort methods
-  var usernameDesc = (e) => e.sort((a, b) => (a.name > b.name ? 1 : -1)),
-    usernameAsc = (e) => e.sort((a, b) => (a.name < b.name ? 1 : -1)),
-    adminDesc = (e) => e.sort((a) => (a.admin ? -1 : 1)),
-    adminAsc = (e) => e.sort((a) => (a.admin ? 1 : -1)),
-    dateDesc = (e) =>
-      e.sort((a, b) =>
-        new Date(a.last_activity) - new Date(b.last_activity) > 0 ? -1 : 1,
-      ),
-    dateAsc = (e) =>
-      e.sort((a, b) =>
-        new Date(a.last_activity) - new Date(b.last_activity) > 0 ? 1 : -1,
-      ),
-    runningAsc = (e) => e.sort((a) => (a.server == null ? -1 : 1)),
-    runningDesc = (e) => e.sort((a) => (a.server == null ? 1 : -1));
+  const base_url = window.base_url || "/";
+  const [searchParams, setSearchParams] = useSearchParams();
 
-  var [errorAlert, setErrorAlert] = useState(null);
-  var [sortMethod, setSortMethod] = useState(null);
-  var [disabledButtons, setDisabledButtons] = useState({});
-  var [collapseStates, setCollapseStates] = useState({});
+  const [errorAlert, setErrorAlert] = useState(null);
+  const [collapseStates, setCollapseStates] = useState({});
 
-  var user_data = useSelector((state) => state.user_data),
-    user_page = useSelector((state) => state.user_page),
-    name_filter = useSelector((state) => state.name_filter);
+  let user_data = useSelector((state) => state.user_data);
+  const user_page = useSelector((state) => state.user_page);
 
-  var offset = user_page ? user_page.offset : 0;
-  var limit = user_page ? user_page.limit : window.api_page_limit;
-  var total = user_page ? user_page.total : undefined;
+  const { setOffset, offset, setLimit, handleLimit, limit, setPagination } =
+    usePaginationParams();
+
+  const name_filter = searchParams.get("name_filter") || "";
+  const sort = searchParams.get("sort") || "id";
+  const state_filter = searchParams.get("state") || "";
+
+  const total = user_page ? user_page.total : undefined;
 
   const dispatch = useDispatch();
+  const navigate = useNavigate();
 
   var {
     updateUsers,
@@ -77,10 +61,16 @@ const ServerDashboard = (props) => {
     deleteServer,
     startAll,
     stopAll,
-    history,
   } = props;
 
   const dispatchPageUpdate = (data, page) => {
+    // trigger page update in state
+    // in response to fetching updated user list
+    // data is list of user records
+    // page is _pagination part of response
+    // persist page info in url query
+    setPagination(page);
+    // persist user data, triggers rerender
     dispatch({
       type: "USER_PAGE",
       value: {
@@ -90,177 +80,205 @@ const ServerDashboard = (props) => {
     });
   };
 
-  const setOffset = (newOffset) => {
-    dispatch({
-      type: "USER_OFFSET",
-      value: {
-        offset: newOffset,
-      },
+  const setNameFilter = (new_name_filter) => {
+    // persist ?name_filter parameter
+    // store in url param, clear when value is empty
+    setSearchParams((params) => {
+      // clear offset when name filter changes
+      if (new_name_filter !== name_filter) {
+        params.delete("offset");
+      }
+      if (new_name_filter) {
+        params.set("name_filter", new_name_filter);
+      } else {
+        params.delete("name_filter");
+      }
+      return params;
     });
   };
 
-  const setNameFilter = (name_filter) => {
-    dispatch({
-      type: "USER_NAME_FILTER",
-      value: {
-        name_filter: name_filter,
-      },
+  const setSort = (sort) => {
+    // persist ?sort parameter
+    // store in url param, clear when value is default ('id')
+    setSearchParams((params) => {
+      if (sort === "id") {
+        params.delete("id");
+      } else {
+        params.set("sort", sort);
+      }
+      return params;
     });
   };
 
+  const setStateFilter = (new_state_filter) => {
+    // persist ?state filter
+    // store in url param, clear when value is default ('')
+    setSearchParams((params) => {
+      // clear offset when filter changes
+      if (new_state_filter !== state_filter) {
+        params.delete("offset");
+      }
+      if (!new_state_filter) {
+        params.delete("state");
+      } else {
+        params.set("state", new_state_filter);
+      }
+      console.log("setting search params", params.toString());
+      return params;
+    });
+  };
+
+  // the callback to update the displayed user list
+  const updateUsersWithParams = () =>
+    updateUsers({
+      offset,
+      limit,
+      name_filter,
+      sort,
+      state: state_filter,
+    });
+
   useEffect(() => {
-    updateUsers(offset, limit, name_filter)
+    updateUsersWithParams()
       .then((data) => dispatchPageUpdate(data.items, data._pagination))
       .catch((err) => setErrorAlert("Failed to update user list."));
-  }, [offset, limit, name_filter]);
+  }, [offset, limit, name_filter, sort, state_filter]);
 
   if (!user_data || !user_page) {
     return <div data-testid="no-show"></div>;
   }
 
-  var slice = [offset, limit, name_filter];
-
   const handleSearch = debounce(async (event) => {
     setNameFilter(event.target.value);
   }, 300);
 
-  if (sortMethod != null) {
-    user_data = sortMethod(user_data);
-  }
-
-  const StopServerButton = ({ serverName, userName }) => {
+  const ServerButton = ({
+    server,
+    user,
+    action,
+    name,
+    variant,
+    extraClass,
+  }) => {
     var [isDisabled, setIsDisabled] = useState(false);
     return (
-      <button
-        className="btn btn-danger btn-xs stop-button"
-        disabled={isDisabled}
+      <Button
+        size="xs"
+        variant={variant}
+        className={extraClass}
+        disabled={isDisabled || server.pending}
         onClick={() => {
           setIsDisabled(true);
-          stopServer(userName, serverName)
+          action(user.name, server.name)
             .then((res) => {
               if (res.status < 300) {
-                updateUsers(...slice)
+                updateUsersWithParams()
                   .then((data) => {
-                    dispatchPageUpdate(
-                      data.items,
-                      data._pagination,
-                      name_filter,
-                    );
+                    dispatchPageUpdate(data.items, data._pagination);
                   })
                   .catch(() => {
                     setIsDisabled(false);
                     setErrorAlert(`Failed to update users list.`);
                   });
               } else {
-                setErrorAlert(`Failed to stop server.`);
+                setErrorAlert(`Failed to ${name.toLowerCase()}.`);
                 setIsDisabled(false);
               }
               return res;
             })
             .catch(() => {
-              setErrorAlert(`Failed to stop server.`);
+              setErrorAlert(`Failed to ${name.toLowerCase()}.`);
               setIsDisabled(false);
             });
         }}
       >
-        Stop Server
-      </button>
+        {name}
+      </Button>
     );
   };
 
-  const DeleteServerButton = ({ serverName, userName }) => {
-    if (serverName === "") {
+  const StopServerButton = ({ server, user }) => {
+    if (!server.ready) {
       return null;
     }
-    var [isDisabled, setIsDisabled] = useState(false);
-    return (
-      <button
-        className="btn btn-danger btn-xs stop-button"
+    return ServerButton({
+      server,
+      user,
+      action: stopServer,
+      name: "Stop Server",
+      variant: "danger",
+      extraClass: "stop-button",
+    });
+  };
+  const DeleteServerButton = ({ server, user }) => {
+    if (!server.name) {
       // It's not possible to delete unnamed servers
-        disabled={isDisabled}
-        onClick={() => {
-          setIsDisabled(true);
-          deleteServer(userName, serverName)
-            .then((res) => {
-              if (res.status < 300) {
-                updateUsers(...slice)
-                  .then((data) => {
-                    dispatchPageUpdate(
-                      data.items,
-                      data._pagination,
-                      name_filter,
-                    );
-                  })
-                  .catch(() => {
-                    setIsDisabled(false);
-                    setErrorAlert(`Failed to update users list.`);
-                  });
-              } else {
-                setErrorAlert(`Failed to delete server.`);
-                setIsDisabled(false);
+      return null;
     }
-              return res;
-            })
-            .catch(() => {
-              setErrorAlert(`Failed to delete server.`);
-              setIsDisabled(false);
+    if (server.ready || server.pending) {
+      return null;
+    }
+    return ServerButton({
+      server,
+      user,
+      action: deleteServer,
+      name: "Delete Server",
+      variant: "danger",
+      extraClass: "stop-button",
     });
-        }}
+  };
+
+  const StartServerButton = ({ server, user }) => {
+    if (server.ready) {
+      return null;
+    }
+    return ServerButton({
+      server,
+      user,
+      action: startServer,
+      name: server.pending ? "Server is pending" : "Start Server",
+      variant: "success",
+      extraClass: "start-button",
+    });
+  };
+
+  const SpawnPageButton = ({ server, user }) => {
+    if (server.ready) {
+      return null;
+    }
+    return (
+      <a
+        href={`${base_url}spawn/${user.name}${
+          server.name ? "/" + server.name : ""
+        }`}
       >
-        Delete Server
-      </button>
+        <Button variant="light" size="xs">
+          Spawn Page
+        </Button>
+      </a>
     );
   };
 
-  const StartServerButton = ({ serverName, userName }) => {
-    var [isDisabled, setIsDisabled] = useState(false);
-    return (
-      <button
-        className="btn btn-success btn-xs start-button"
-        disabled={isDisabled}
-        onClick={() => {
-          setIsDisabled(true);
-          startServer(userName, serverName)
-            .then((res) => {
-              if (res.status < 300) {
-                updateUsers(...slice)
-                  .then((data) => {
-                    dispatchPageUpdate(
-                      data.items,
-                      data._pagination,
-                      name_filter,
-                    );
-                  })
-                  .catch(() => {
-                    setErrorAlert(`Failed to update users list.`);
-                    setIsDisabled(false);
-                  });
-              } else {
-                setErrorAlert(`Failed to start server.`);
-                setIsDisabled(false);
+  const AccessServerButton = ({ server }) => {
+    if (!server.ready) {
+      return null;
     }
-              return res;
-            })
-            .catch(() => {
-              setErrorAlert(`Failed to start server.`);
-              setIsDisabled(false);
-            });
-        }}
-      >
-        Start Server
-      </button>
+    return (
+      <a href={server.url || ""}>
+        <Button variant="primary" size="xs">
+          Access Server
+        </Button>
+      </a>
     );
   };
 
-  const EditUserCell = ({ user }) => {
+  const EditUserButton = ({ user }) => {
     return (
-      <td>
-        <button
-          className="btn btn-primary btn-xs"
-          style={{ marginRight: 20 }}
+      <Button
+        size="xs"
+        variant="light"
         onClick={() =>
-            history.push({
-              pathname: "/edit-user",
+          navigate("/edit-user", {
             state: {
               username: user.name,
               has_admin: user.admin,
@@ -269,8 +287,7 @@ const ServerDashboard = (props) => {
         }
       >
         Edit User
-        </button>
-      </td>
+      </Button>
     );
   };
 
@@ -301,7 +318,7 @@ const ServerDashboard = (props) => {
       }, {});
     return (
       <ReactObjectTableViewer
-        className="table-striped table-bordered"
+        className="table table-striped table-bordered"
         style={{
           padding: "3px 6px",
           margin: "auto",
@@ -343,7 +360,7 @@ const ServerDashboard = (props) => {
               variant={open ? "secondary" : "primary"}
               size="sm"
             >
-              <span className="caret"></span>
+              <span className="fa fa-caret-down"></span>
             </Button>{" "}
           </span>
           <span data-testid={`user-name-div-${userServerName}`}>
@@ -358,43 +375,16 @@ const ServerDashboard = (props) => {
         <td data-testid="user-row-last-activity">
           {server.last_activity ? timeSince(server.last_activity) : "Never"}
         </td>
-        <td data-testid="user-row-server-activity">
-          {server.ready ? (
-            // Stop Single-user server
-            <>
-              <StopServerButton serverName={server.name} userName={user.name} />
-              <AccessServerButton url={server.url} />
-            </>
-          ) : (
-            // Start Single-user server
-            <>
-              <StartServerButton
-                serverName={server.name}
-                userName={user.name}
-                style={{ marginRight: 20 }}
-              />
-              <DeleteServerButton
-                serverName={server.name}
-                userName={user.name}
-              />
-              <a
-                href={`${base_url}spawn/${user.name}${
-                  server.name ? "/" + server.name : ""
-                }`}
-              >
-                <button
-                  className="btn btn-secondary btn-xs"
-                  style={{ marginRight: 20 }}
-                >
-                  Spawn Page
-                </button>
-              </a>
-            </>
-          )}
+        <td data-testid="user-row-server-activity" className="actions">
+          <StartServerButton server={server} user={user} />
+          <StopServerButton server={server} user={user} />
+          <DeleteServerButton server={server} user={user} />
+          <AccessServerButton server={server} />
+          <SpawnPageButton server={server} user={user} />
+          <EditUserButton user={user} />
         </td>
-        <EditUserCell user={user} />
       </tr>,
-      <tr>
+      <tr key={`${userServerName}-detail`}>
         <td
           colSpan={6}
           style={{ padding: 0 }}
@@ -430,26 +420,9 @@ const ServerDashboard = (props) => {
 
   return (
     <div className="container" data-testid="container">
-      {errorAlert != null ? (
-        <div className="row">
-          <div className="col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
-            <div className="alert alert-danger">
-              {errorAlert}
-              <button
-                type="button"
-                className="close"
-                onClick={() => setErrorAlert(null)}
-              >
-                <span>&times;</span>
-              </button>
-            </div>
-          </div>
-        </div>
-      ) : (
-        <></>
-      )}
+      <ErrorAlert errorAlert={errorAlert} setErrorAlert={setErrorAlert} />
       <div className="server-dashboard-container">
-        <Row>
+        <Row className="rows-cols-lg-auto g-3 mb-3 align-items-center">
           <Col md={4}>
             <FormControl
               type="text"
@@ -460,9 +433,32 @@ const ServerDashboard = (props) => {
               onChange={handleSearch}
             />
           </Col>
+          <Col md={4}>
+            <Form.Check
+              inline
+              title="check to only show running servers, otherwise show all"
+            >
+              <Form.Check.Input
+                type="checkbox"
+                name="active_servers"
+                id="active-servers-filter"
+                checked={state_filter == "active"}
+                onChange={(event) => {
+                  setStateFilter(event.target.checked ? "active" : null);
+                }}
+              />
+              <Form.Check.Label for="active-servers-filter">
+                {"only active servers"}
+              </Form.Check.Label>
+            </Form.Check>
+          </Col>
 
-          <Col md="auto" style={{ float: "right", margin: 15 }}>
-            <Link to="/groups">{"> Manage Groups"}</Link>
+          <Col md={{ span: 3, offset: 1 }}>
+            <Link to="/groups">
+              <Button variant="light" className="form-control">
+                {"Manage Groups"}
+              </Button>
+            </Link>
           </Col>
         </Row>
         <table className="table table-bordered table-hover">
@@ -471,61 +467,42 @@ const ServerDashboard = (props) => {
               <th id="user-header">
                 User{" "}
                 <SortHandler
-                  sorts={{ asc: usernameAsc, desc: usernameDesc }}
-                  callback={(method) => setSortMethod(() => method)}
+                  currentSort={sort}
+                  setSort={setSort}
+                  sortKey="name"
                   testid="user-sort"
                 />
               </th>
-              <th id="admin-header">
-                Admin{" "}
-                <SortHandler
-                  sorts={{ asc: adminAsc, desc: adminDesc }}
-                  callback={(method) => setSortMethod(() => method)}
-                  testid="admin-sort"
-                />
-              </th>
-              <th id="server-header">
-                Server{" "}
-                <SortHandler
-                  sorts={{ asc: usernameAsc, desc: usernameDesc }}
-                  callback={(method) => setSortMethod(() => method)}
-                  testid="server-sort"
-                />
-              </th>
+              <th id="admin-header">Admin</th>
+              <th id="server-header">Server</th>
               <th id="last-activity-header">
                 Last Activity{" "}
                 <SortHandler
-                  sorts={{ asc: dateAsc, desc: dateDesc }}
-                  callback={(method) => setSortMethod(() => method)}
+                  currentSort={sort}
+                  setSort={setSort}
+                  sortKey="last_activity"
                   testid="last-activity-sort"
                 />
               </th>
-              <th id="running-status-header">
-                Running{" "}
-                <SortHandler
-                  sorts={{ asc: runningAsc, desc: runningDesc }}
-                  callback={(method) => setSortMethod(() => method)}
-                  testid="running-status-sort"
-                />
-              </th>
               <th id="actions-header">Actions</th>
             </tr>
           </thead>
           <tbody>
             <tr className="noborder">
               <td>
+                <Link to="/add-users">
                   <Button variant="light" className="add-users-button">
-                  <Link to="/add-users">Add Users</Link>
+                    Add Users
                   </Button>
+                </Link>
               </td>
-              <td></td>
-              <td></td>
-              <td>
+              <td colSpan={4} className="admin-header-buttons">
                 {/* Start all servers */}
                 <Button
                   variant="primary"
                   className="start-all"
                   data-testid="start-all"
+                  title="start all servers on the current page"
                   onClick={() => {
                     Promise.all(startAll(user_data.map((e) => e.name)))
                       .then((res) => {
@@ -542,13 +519,9 @@ const ServerDashboard = (props) => {
                         return res;
                       })
                       .then((res) => {
-                        updateUsers(...slice)
+                        updateUsersWithParams()
                           .then((data) => {
-                            dispatchPageUpdate(
-                              data.items,
-                              data._pagination,
-                              name_filter,
-                            );
+                            dispatchPageUpdate(data.items, data._pagination);
                           })
                           .catch(() =>
                             setErrorAlert(`Failed to update users list.`),
@@ -566,6 +539,7 @@ const ServerDashboard = (props) => {
                   variant="danger"
                   className="stop-all"
                   data-testid="stop-all"
+                  title="stop all servers on the current page"
                   onClick={() => {
                     Promise.all(stopAll(user_data.map((e) => e.name)))
                       .then((res) => {
@@ -582,13 +556,9 @@ const ServerDashboard = (props) => {
                         return res;
                       })
                       .then((res) => {
-                        updateUsers(...slice)
+                        updateUsersWithParams()
                           .then((data) => {
-                            dispatchPageUpdate(
-                              data.items,
-                              data._pagination,
-                              name_filter,
-                            );
+                            dispatchPageUpdate(data.items, data._pagination);
                           })
                           .catch(() =>
                             setErrorAlert(`Failed to update users list.`),
@@ -600,8 +570,8 @@ const ServerDashboard = (props) => {
                 >
                   Stop All
                 </Button>
-              </td>
-              <td>
+                {/* spacing between start/stop and Shutdown */}
+                <span style={{ marginLeft: "30px" }}> </span>
                 {/* Shutdown Jupyterhub */}
                 <Button
                   variant="danger"
@@ -622,6 +592,7 @@ const ServerDashboard = (props) => {
           total={total}
           next={() => setOffset(offset + limit)}
           prev={() => setOffset(offset - limit)}
+          handleLimit={handleLimit}
         />
         <br></br>
       </div>
@@ -639,39 +610,30 @@ ServerDashboard.propTypes = {
   startAll: PropTypes.func,
   stopAll: PropTypes.func,
   dispatch: PropTypes.func,
-  history: PropTypes.shape({
-    push: PropTypes.func,
-  }),
-  location: PropTypes.shape({
-    search: PropTypes.string,
-  }),
 };
 
 const SortHandler = (props) => {
-  var { sorts, callback, testid } = props;
-
-  var [direction, setDirection] = useState(undefined);
+  const { currentSort, setSort, sortKey, testid } = props;
 
+  const currentlySorted = currentSort && currentSort.endsWith(sortKey);
+  const descending = currentSort && currentSort.startsWith("-");
   return (
     <div
       className="sort-icon"
       data-testid={testid}
       onClick={() => {
-        if (!direction) {
-          callback(sorts.desc);
-          setDirection("desc");
-        } else if (direction == "asc") {
-          callback(sorts.desc);
-          setDirection("desc");
+        if (!currentlySorted) {
+          setSort(sortKey);
+        } else if (descending) {
+          setSort(sortKey);
         } else {
-          callback(sorts.asc);
-          setDirection("asc");
+          setSort("-" + sortKey);
         }
       }}
     >
-      {!direction ? (
+      {!currentlySorted ? (
         <FaSort />
-      ) : direction == "asc" ? (
+      ) : descending ? (
         <FaSortDown />
       ) : (
         <FaSortUp />
@@ -681,8 +643,9 @@ const SortHandler = (props) => {
 };
 
 SortHandler.propTypes = {
-  sorts: PropTypes.object,
-  callback: PropTypes.func,
+  currentSort: PropTypes.string,
+  setSort: PropTypes.func,
+  sortKey: PropTypes.string,
   testid: PropTypes.string,
 };