Bump to 5.3.0

changelog for 5.3.0

.github/dependabot.yaml

@@ -14,3 +14,44 @@ updates:
       interval: monthly
       time: "05:00"
       timezone: Etc/UTC
+  - package-ecosystem: npm
+    directory: /
+    groups:
+      # one big pull request for minor bumps
+      npm-minor:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    schedule:
+      interval: monthly
+  - package-ecosystem: npm
+    directory: /jsx
+    groups:
+      # one big pull request for minor bumps
+      jsx-minor:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+      # group major bumps of react-related dependencies
+      jsx-react:
+        patterns:
+          - "react*"
+          - "redux*"
+          - "*react"
+          - "recompose"
+        update-types:
+          - major
+      # group major bumps of webpack-related dependencies
+      jsx-webpack:
+        patterns:
+          - "*webpack*"
+          - "@babel/*"
+          - "*-loader"
+        update-types:
+          - major
+    schedule:
+      interval: monthly

.github/workflows/registry-overviews.yml

@@ -1,54 +0,0 @@
-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

@@ -1,7 +1,7 @@
 # This is a GitHub workflow defining a set of jobs with a set of steps.
 # ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
 #
-# Test build release artifacts (PyPI package, Docker images) and publish them on
+# Test build release artifacts (PyPI package) and publish them on
 # pushed git tags.
 #
 name: Release
@@ -28,6 +28,9 @@ on:
       - "**"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   build-release:
     runs-on: ubuntu-22.04
@@ -36,6 +39,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          cache: pip
 
       - uses: actions/setup-node@v4
         with:
@@ -81,150 +85,3 @@ jobs:
         run: |
           pip install twine
           twine upload --skip-existing dist/*
-
-  publish-docker:
-    runs-on: ubuntu-22.04
-    timeout-minutes: 30
-
-    services:
-      # So that we can test this in PRs/branches
-      local-registry:
-        image: registry:2
-        ports:
-          - 5000:5000
-
-    steps:
-      - name: Should we push this image to a public registry?
-        run: |
-          if [ "${{ startsWith(github.ref, 'refs/tags/') || (github.ref == 'refs/heads/main') }}" = "true" ]; then
-              echo "REGISTRY=quay.io/" >> $GITHUB_ENV
-          else
-              echo "REGISTRY=localhost:5000/" >> $GITHUB_ENV
-          fi
-
-      - 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@v3
-
-      - name: Set up Docker Buildx (for multi-arch builds)
-        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 [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.QUAY_USERNAME }}" -p "${{ secrets.QUAY_PASSWORD }}" "${{ env.REGISTRY }}"
-          docker login -u "${{ secrets.DOCKERHUB_USERNAME }}" -p "${{ secrets.DOCKERHUB_TOKEN }}" docker.io
-
-      # image: jupyterhub/jupyterhub
-      #
-      # https://github.com/jupyterhub/action-major-minor-tag-calculator
-      # If this is a tagged build this will return additional parent tags.
-      # E.g. 1.2.3 is expanded to Docker tags
-      # [{prefix}:1.2.3, {prefix}:1.2, {prefix}:1, {prefix}:latest] unless
-      # this is a backported tag in which case the newer tags aren't updated.
-      # For branches this will return the branch name.
-      # 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@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          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@v5
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          # tags parameter must be a string input so convert `gettags` JSON
-          # array into a comma separated list of tags
-          tags: ${{ join(fromJson(steps.jupyterhubtags.outputs.tags)) }}
-
-      # image: jupyterhub/jupyterhub-onbuild
-      #
-      - name: Get list of jupyterhub-onbuild tags
-        id: onbuildtags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          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@v5
-        with:
-          build-args: |
-            BASE_IMAGE=${{ fromJson(steps.jupyterhubtags.outputs.tags)[0] }}
-          context: onbuild
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ join(fromJson(steps.onbuildtags.outputs.tags)) }}
-
-      # image: jupyterhub/jupyterhub-demo
-      #
-      - name: Get list of jupyterhub-demo tags
-        id: demotags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          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@v5
-        with:
-          build-args: |
-            BASE_IMAGE=${{ fromJson(steps.onbuildtags.outputs.tags)[0] }}
-          context: demo-image
-          # linux/arm64 currently fails:
-          # ERROR: Could not build wheels for argon2-cffi which use PEP 517 and cannot be installed directly
-          # ERROR: executor failed running [/bin/sh -c python3 -m pip install notebook]: exit code: 1
-          platforms: linux/amd64
-          push: true
-          tags: ${{ join(fromJson(steps.demotags.outputs.tags)) }}
-
-      # image: jupyterhub/singleuser
-      #
-      - name: Get list of jupyterhub/singleuser tags
-        id: singleusertags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          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@v5
-        with:
-          build-args: |
-            JUPYTERHUB_VERSION=${{ github.ref_type == 'tag' && github.ref_name || format('git:{0}', github.sha) }}
-          context: singleuser
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ join(fromJson(steps.singleusertags.outputs.tags)) }}

.github/workflows/test-docs.yml

@@ -29,6 +29,9 @@ on:
       - "**"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 env:
   # UTF-8 content may be interpreted as ascii and causes errors without this.
   LANG: C.UTF-8
@@ -61,6 +64,10 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            docs/requirements.txt
 
       - name: Install requirements
         run: |
@@ -77,10 +84,12 @@ jobs:
           cd docs
           make html
 
+      # Output broken and permanently redirected links in a readable format
       - name: check links
-        run: |
-          cd docs
-          make linkcheck
+        uses: manics/action-sphinx-linkcheck-summary@main
+        with:
+          docs-dir: docs
+          build-dir: docs/_build
 
       # make rediraffecheckdiff compares files for different changesets
       # these diff targets aren't always available

.github/workflows/test.yml

@@ -158,6 +158,11 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "${{ matrix.python }}"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements.txt
+            ci/oldest-dependencies/requirements.old
 
       - name: Install Python dependencies
         run: |
@@ -168,7 +173,7 @@ jobs:
             # 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]"
+            pip install --pre -e ".[test]"
           fi
 
           if [ "${{ matrix.main_dependencies }}" != "" ]; then
@@ -247,31 +252,10 @@ jobs:
 
       - name: Ensure browsers are installed for playwright
         if: matrix.browser
-        run: python -m playwright install --with-deps
+        run: python -m playwright install --with-deps firefox
 
       - name: Run pytest
         run: |
           pytest -k "${{ matrix.subset }}" --maxfail=2 --cov=jupyterhub jupyterhub/tests
 
-      - uses: codecov/codecov-action@v4
-
-  docker-build:
-    runs-on: ubuntu-22.04
-    timeout-minutes: 20
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: build images
-        run: |
-          DOCKER_BUILDKIT=1 docker build -t jupyterhub/jupyterhub .
-          docker build -t jupyterhub/jupyterhub-onbuild onbuild
-          docker build -t jupyterhub/singleuser singleuser
-
-      - name: smoke test jupyterhub
-        run: |
-          docker run --rm -t jupyterhub/jupyterhub jupyterhub --help
-
-      - name: verify static files
-        run: |
-          docker run --rm -t -v $PWD/dockerfiles:/io jupyterhub/jupyterhub python3 /io/test.py
+      - uses: codecov/codecov-action@v5

.gitignore

@@ -7,8 +7,6 @@ node_modules
 dist
 docs/_build
 docs/build
-docs/source/_static/rest-api
-docs/source/rbac/scope-table.md
 docs/source/reference/metrics.md
 
 .ipynb_checkpoints

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ ci:
 repos:
   # autoformat and lint Python code
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.3
+    rev: v0.11.4
     hooks:
       - id: ruff
         types_or:
@@ -33,11 +33,11 @@ repos:
     rev: v4.0.0-alpha.8
     hooks:
       - id: prettier
-        exclude: .*/templates/.*
+        exclude: .*/templates/.*|docs/source/_static/rest-api.yml|docs/source/rbac/scope-table.md
 
   # autoformat HTML templates
   - repo: https://github.com/djlint/djLint
-    rev: v1.34.1
+    rev: v1.36.4
     hooks:
       - id: djlint-reformat-jinja
         files: ".*templates/.*.html"
@@ -49,10 +49,38 @@ repos:
 
   # Autoformat and linting, misc. details
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.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
+
+  # source docs: rest-api.yml and scope-table.md are autogenerated
+  - repo: local
+    hooks:
+      - id: update-api-and-scope-docs
+        name: Update rest-api.yml and scope-table.md based on scopes.py
+        language: python
+        additional_dependencies: ["pytablewriter", "ruamel.yaml"]
+        entry: python docs/source/rbac/generate-scope-table.py
+        args:
+          - --update
+        files: jupyterhub/scopes.py
+        pass_filenames: false
+
+      # run eslint in the jsx directory
+      # need to pass through 'jsx:install-run' hook in
+      # top-level package.json to ensure dependencies are installed
+      # eslint pre-commit hook doesn't really work with eslint 9,
+      # so use `npm run lint:fix`
+      - id: jsx-eslint
+        name: eslint in jsx/
+        entry: npm run jsx:install-run lint:fix
+        pass_filenames: false
+        language: node
+        files: "jsx/.*"
+        # can't run on pre-commit; hangs, for some reason
+        stages:
+          - manual

.readthedocs.yaml

@@ -8,10 +8,9 @@ sphinx:
   configuration: docs/source/conf.py
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    nodejs: "20"
-    python: "3.11"
+    python: "3.13"
 
 python:
   install:

CONTRIBUTING.md

@@ -12,3 +12,29 @@ Please see our documentation on
 - [Testing JupyterHub and linting code](https://jupyterhub.readthedocs.io/en/latest/contributing/tests.html)
 
 If you need some help, feel free to ask on [Gitter](https://gitter.im/jupyterhub/jupyterhub) or [Discourse](https://discourse.jupyter.org/).
+
+## Our Copyright Policy
+
+Jupyter uses a shared copyright model. Each contributor maintains copyright
+over their contributions to Jupyter. But, it is important to note that these
+contributions are typically only changes to the repositories. Thus, the Jupyter
+source code, in its entirety is not the copyright of any single person or
+institution. Instead, it is the collective copyright of the entire Jupyter
+Development Team. If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate
+their copyright in the commit message of the change, when they commit the
+change to one of the Jupyter repositories.
+
+With this in mind, the following banner should be used in any source code file
+to indicate the copyright and license terms:
+
+    # Copyright (c) Jupyter Development Team.
+    # Distributed under the terms of the Modified BSD License.
+
+### About the Jupyter Development Team
+
+The Jupyter Development Team is the set of all contributors to the Jupyter project.
+This includes all of the Jupyter subprojects.
+
+The team that coordinates JupyterHub subproject can be found here:
+https://jupyterhub-team-compass.readthedocs.io/en/latest/governance.html

COPYING.md

@@ -1,59 +0,0 @@
-# The Jupyter multi-user notebook server licensing terms
-
-Jupyter multi-user notebook server is licensed under the terms of the Modified BSD License
-(also known as New or Revised or 3-Clause BSD), as follows:
-
-- Copyright (c) 2014-, Jupyter Development Team
-
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-Redistributions of source code must retain the above copyright notice, this
-list of conditions and the following disclaimer.
-
-Redistributions in binary form must reproduce the above copyright notice, this
-list of conditions and the following disclaimer in the documentation and/or
-other materials provided with the distribution.
-
-Neither the name of the Jupyter Development Team nor the names of its
-contributors may be used to endorse or promote products derived from this
-software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-## About the Jupyter Development Team
-
-The Jupyter Development Team is the set of all contributors to the Jupyter project.
-This includes all of the Jupyter subprojects.
-
-The core team that coordinates development on GitHub can be found here:
-https://github.com/jupyter/.
-
-## Our Copyright Policy
-
-Jupyter uses a shared copyright model. Each contributor maintains copyright
-over their contributions to Jupyter. But, it is important to note that these
-contributions are typically only changes to the repositories. Thus, the Jupyter
-source code, in its entirety is not the copyright of any single person or
-institution. Instead, it is the collective copyright of the entire Jupyter
-Development Team. If individual contributors want to maintain a record of what
-changes/contributions they have specific copyright on, they should indicate
-their copyright in the commit message of the change, when they commit the
-change to one of the Jupyter repositories.
-
-With this in mind, the following banner should be used in any source code file
-to indicate the copyright and license terms:
-
-    # Copyright (c) Jupyter Development Team.
-    # Distributed under the terms of the Modified BSD License.

Dockerfile

@@ -1,146 +0,0 @@
-# An incomplete base Docker image for running JupyterHub
-#
-# Add your configuration to create a complete derivative Docker image.
-#
-# Include your configuration settings by starting with one of two options:
-#
-# Option 1:
-#
-# FROM quay.io/jupyterhub/jupyterhub:latest
-#
-# And put your configuration file jupyterhub_config.py in /srv/jupyterhub/jupyterhub_config.py.
-#
-# Option 2:
-#
-# Or you can create your jupyterhub config and database on the host machine, and mount it with:
-#
-# docker run -v $PWD:/srv/jupyterhub -t quay.io/jupyterhub/jupyterhub
-#
-# NOTE
-# If you base on quay.io/jupyterhub/jupyterhub-onbuild
-# your jupyterhub_config.py will be added automatically
-# from your docker directory.
-
-######################################################################
-# This Dockerfile uses multi-stage builds with optimisations to build
-# the JupyterHub wheel on the native architecture only
-# https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/
-
-ARG BASE_IMAGE=ubuntu:22.04
-
-
-######################################################################
-# The JupyterHub wheel is pure Python so can be built for any platform
-# on the native architecture (avoiding QEMU emulation)
-FROM --platform=${BUILDPLATFORM:-linux/amd64} $BASE_IMAGE AS jupyterhub-builder
-
-ENV DEBIAN_FRONTEND=noninteractive
-
-# Don't clear apt cache, and don't combine RUN commands, so that cached layers can
-# be reused in other stages
-
-RUN apt-get update -qq \
- && apt-get install -yqq --no-install-recommends \
-    build-essential \
-    ca-certificates \
-    curl \
-    git \
-    gnupg \
-    locales \
-    python3-dev \
-    python3-pip \
-    python3-pycurl \
-    python3-venv \
- && 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)
-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
-
-WORKDIR /src/jupyterhub
-# copy everything except whats in .dockerignore, its a
-# compromise between needing to rebuild and maintaining
-# what needs to be part of the build
-COPY . .
-
-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
-FROM $BASE_IMAGE AS wheel-builder
-
-ENV DEBIAN_FRONTEND=noninteractive
-
-RUN apt-get update -qq \
- && apt-get install -yqq --no-install-recommends \
-    build-essential \
-    ca-certificates \
-    curl \
-    locales \
-    python3-dev \
-    python3-pip \
-    python3-pycurl \
-    python3-venv \
- && python3 -m pip install --no-cache-dir --upgrade setuptools pip build wheel
-
-WORKDIR /src/jupyterhub
-
-COPY --from=jupyterhub-builder /src/jupyterhub/dist/*.whl /src/jupyterhub/dist/
-ARG PIP_CACHE_DIR=/tmp/pip-cache
-RUN --mount=type=cache,target=${PIP_CACHE_DIR} \
-    python3 -m pip wheel --wheel-dir wheelhouse dist/*.whl
-
-
-######################################################################
-# The final JupyterHub image, platform specific
-FROM $BASE_IMAGE AS jupyterhub
-
-ENV DEBIAN_FRONTEND=noninteractive \
-    SHELL=/bin/bash \
-    LC_ALL=en_US.UTF-8 \
-    LANG=en_US.UTF-8 \
-    LANGUAGE=en_US.UTF-8 \
-    PYTHONDONTWRITEBYTECODE=1
-
-EXPOSE 8000
-
-LABEL maintainer="Jupyter Project <jupyter@googlegroups.com>"
-LABEL org.jupyter.service="jupyterhub"
-
-WORKDIR /srv/jupyterhub
-
-RUN apt-get update -qq \
- && apt-get install -yqq --no-install-recommends \
-    ca-certificates \
-    curl \
-    gnupg \
-    locales \
-    python-is-python3 \
-    python3-pip \
-    python3-pycurl \
-    nodejs \
-    npm \
- && locale-gen $LC_ALL \
- && npm install -g configurable-http-proxy@^4.2.0 \
- # clean cache and logs
- && rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* ~/.npm
-# install the wheels we built in the previous stage
-RUN --mount=type=cache,from=wheel-builder,source=/src/jupyterhub/wheelhouse,target=/tmp/wheelhouse \
-    # always make sure pip is up to date!
-    python3 -m pip install --no-compile --no-cache-dir --upgrade setuptools pip \
- && python3 -m pip install --no-compile --no-cache-dir /tmp/wheelhouse/*
-
-CMD ["jupyterhub"]

LICENSE

@@ -0,0 +1,11 @@
+Copyright 2014-, Jupyter Development Team
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -111,7 +111,7 @@ Visit `http://localhost:8000` in your browser, and sign in with your system user
 
 _Note_: To allow multiple users to sign in to the server, you will need to
 run the `jupyterhub` command as a _privileged user_, such as root.
-The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+The [documentation](https://jupyterhub.readthedocs.io/en/latest/howto/configuration/config-sudo.html)
 describes how to run the server as a _less privileged user_, which requires
 more configuration of the system.
 
@@ -220,7 +220,7 @@ docker container or Linux VM.
 We use a shared copyright model that enables all contributors to maintain the
 copyright on their contributions.
 
-All code is licensed under the terms of the [revised BSD license](./COPYING.md).
+All code is licensed under the terms of the [revised BSD license](./LICENSE).
 
 ## Help and resources
 

demo-image/Dockerfile

@@ -1,16 +0,0 @@
-# Demo JupyterHub Docker image
-#
-# 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=quay.io/jupyterhub/jupyterhub-onbuild
-FROM ${BASE_IMAGE}
-
-# Install the notebook package
-RUN python3 -m pip install notebook
-
-# Create a demo user
-RUN useradd --create-home demo
-RUN chown demo .
-
-USER demo

demo-image/README.md

@@ -1,26 +0,0 @@
-## Demo Dockerfile
-
-This is a demo JupyterHub Docker image to help you get a quick overview of what
-JupyterHub is and how it works.
-
-It uses the SimpleLocalProcessSpawner to spawn new user servers and
-DummyAuthenticator for authentication.
-The DummyAuthenticator allows you to log in with any username & password and the
-SimpleLocalProcessSpawner allows starting servers without having to create a
-local user for each JupyterHub user.
-
-### Important!
-
-This should only be used for demo or testing purposes!
-It shouldn't be used as a base image to build on.
-
-### Try it
-
-1. `cd` to the root of your jupyterhub repo.
-
-2. Build the demo image with `docker build -t jupyterhub-demo demo-image`.
-
-3. Run the demo image with `docker run -d -p 8000:8000 jupyterhub-demo`.
-
-4. Visit http://localhost:8000 and login with any username and password
-5. Happy demo-ing :tada:!

demo-image/jupyterhub_config.py

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

dockerfiles/test.py

@@ -1,14 +0,0 @@
-import os
-
-from jupyterhub._data import DATA_FILES_PATH
-
-print(f"DATA_FILES_PATH={DATA_FILES_PATH}")
-
-for sub_path in (
-    "templates",
-    "static/components",
-    "static/css/style.min.css",
-    "static/js/admin-react.js",
-):
-    path = os.path.join(DATA_FILES_PATH, sub_path)
-    assert os.path.exists(path), path

docs/Makefile

@@ -35,7 +35,7 @@ help:
 # - NOTE: If the pre-requisites for the html target is updated, also update the
 #         Read The Docs section in docs/source/conf.py.
 #
-html: metrics scopes
+html: metrics
 	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -44,10 +44,6 @@ metrics: source/reference/metrics.md
 source/reference/metrics.md:
 	python3 generate-metrics.py
 
-scopes: source/rbac/scope-table.md
-source/rbac/scope-table.md:
-	python3 source/rbac/generate-scope-table.py
-
 
 # Manually added targets - related to development
 # ----------------------------------------------------------------------------
@@ -56,7 +52,7 @@ source/rbac/scope-table.md:
 # - requires sphinx-autobuild, see
 #   https://sphinxcontrib-spelling.readthedocs.io/en/latest/
 # - builds and rebuilds html on changes to source, but does not re-generate
-#   metrics/scopes files
+#   metrics files
 # - starts a livereload enabled webserver and opens up a browser
 devenv: html
 	sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html"

docs/requirements.txt

@@ -2,6 +2,7 @@
 # don't depend on it here, as that often results in a duplicate
 # installation of jupyterhub that's already installed
 autodoc-traits
+intersphinx-registry
 jupyterhub-sphinx-theme
 myst-parser>=0.19
 pre-commit

docs/source/_static/rest-api.yml

@@ -7,7 +7,7 @@ info:
   license:
     name: BSD-3-Clause
     identifier: BSD-3-Clause
-  version: 5.0.0b2
+  version: 5.3.0
 servers:
   - url: /hub/api
 security:
@@ -62,8 +62,7 @@ paths:
                     properties:
                       class:
                         type: string
-                        description:
-                          The Python class currently active for JupyterHub
+                        description: The Python class currently active for JupyterHub
                           Authentication
                       version:
                         type: string
@@ -73,8 +72,7 @@ paths:
                     properties:
                       class:
                         type: string
-                        description:
-                          The Python class currently active for spawning
+                        description: The Python class currently active for spawning
                           single-user notebook servers
                       version:
                         type: string
@@ -258,8 +256,7 @@ paths:
       parameters:
         - $ref: "#/components/parameters/userName"
       requestBody:
-        description:
-          Updated user info. At least one key to be updated (name or admin)
+        description: Updated user info. At least one key to be updated (name or admin)
           is required.
         content:
           application/json:
@@ -268,13 +265,11 @@ paths:
               properties:
                 name:
                   type: string
-                  description:
-                    the new name (optional, if another key is updated i.e.
+                  description: the new name (optional, if another key is updated i.e.
                     admin)
                 admin:
                   type: boolean
-                  description:
-                    update admin (optional, if another key is updated i.e.
+                  description: update admin (optional, if another key is updated i.e.
                     name)
         required: true
       responses:
@@ -291,8 +286,7 @@ paths:
     post:
       operationId: post-user-activity
       summary: Notify Hub of activity for a given user
-      description:
-        Notify the Hub of activity by the user, e.g. accessing a service
+      description: Notify the Hub of activity by the user, e.g. accessing a service
         or (more likely) actively using a server.
       parameters:
         - $ref: "#/components/parameters/userName"
@@ -372,8 +366,7 @@ paths:
           description: The user's notebook server has started
           content: {}
         202:
-          description:
-            The user's notebook server has not yet started, but has been
+          description: The user's notebook server has not yet started, but has been
             requested
           content: {}
       security:
@@ -387,8 +380,7 @@ paths:
         - $ref: "#/components/parameters/userName"
       responses:
         202:
-          description:
-            The user's notebook server has not yet stopped as it is taking
+          description: The user's notebook server has not yet stopped as it is taking
             a while to stop
           content: {}
         204:
@@ -420,8 +412,7 @@ paths:
           description: The user's notebook named-server has started
           content: {}
         202:
-          description:
-            The user's notebook named-server has not yet started, but has
+          description: The user's notebook named-server has not yet started, but has
             been requested
           content: {}
       security:
@@ -457,8 +448,7 @@ paths:
         required: false
       responses:
         202:
-          description:
-            The user's notebook named-server has not yet stopped as it
+          description: The user's notebook named-server has not yet stopped as it
             is taking a while to stop
           content: {}
         204:
@@ -472,8 +462,7 @@ paths:
     get:
       operationId: get-user-shared
       summary: List servers shared with user
-      description:
-        Returns list of Shares granting the user access to servers owned
+      description: Returns list of Shares granting the user access to servers owned
         by others (new in 5.0)
       parameters:
         - $ref: "#/components/parameters/userName"
@@ -587,8 +576,7 @@ paths:
                 expires_in:
                   type: number
                   example: 3600
-                  description:
-                    lifetime (in seconds) after which the requested token
+                  description: lifetime (in seconds) after which the requested token
                     will expire. Omit, or specify null or 0 for no expiration.
                 note:
                   type: string
@@ -1176,8 +1164,16 @@ paths:
                         example: abc123
                       accept_url:
                         type: string
-                        description: The URL for accepting the code
+                        description: The URL path for accepting the code
                         example: /hub/accept-share?code=abc123
+                      full_accept_url:
+                        type:
+                          - string
+                          - "null"
+                        description: |
+                          The full URL for accepting the code,
+                          if JupyterHub.public_url configuration is defined.
+                        example: https://hub.example.org/hub/accept-share?code=abc123
       security:
         - oauth2:
             - shares
@@ -1254,8 +1250,7 @@ paths:
     get:
       operationId: get-proxy
       summary: Get the proxy's routing table
-      description:
-        A convenience alias for getting the routing table directly from
+      description: A convenience alias for getting the routing table directly from
         the proxy
       parameters:
         - $ref: "#/components/parameters/paginationOffset"
@@ -1267,8 +1262,7 @@ paths:
             application/json:
               schema:
                 type: object
-                description:
-                  configurable-http-proxy routing table (see configurable-http-proxy
+                description: configurable-http-proxy routing table (see configurable-http-proxy
                   docs for details)
       security:
         - oauth2:
@@ -1288,8 +1282,7 @@ paths:
       summary: Notify the Hub about a new proxy
       description: Notifies the Hub of a new proxy to use.
       requestBody:
-        description:
-          Any values that have changed for the new proxy. All keys are
+        description: Any values that have changed for the new proxy. All keys are
           optional.
         content:
           application/json:
@@ -1381,8 +1374,7 @@ paths:
     get:
       operationId: get-auth-cookie
       summary: Identify a user from a cookie
-      description:
-        Used by single-user notebook servers to hand off cookie authentication
+      description: Used by single-user notebook servers to hand off cookie authentication
         to the Hub
       parameters:
         - name: cookie_name
@@ -1507,13 +1499,11 @@ paths:
               properties:
                 proxy:
                   type: boolean
-                  description:
-                    Whether the proxy should be shutdown as well (default
+                  description: Whether the proxy should be shutdown as well (default
                     from Hub config)
                 servers:
                   type: boolean
-                  description:
-                    Whether users' notebook servers should be shutdown
+                  description: Whether users' notebook servers should be shutdown
                     as well (default from Hub config)
         required: false
       responses:
@@ -1638,6 +1628,11 @@ components:
         name:
           type: string
           description: The user's name
+        kind:
+          type: string
+          description: the string 'user' to distinguish from 'service'
+          enum:
+            - user
         admin:
           type: boolean
           description: Whether the user is an admin
@@ -1653,8 +1648,7 @@ components:
             type: string
         server:
           type: string
-          description:
-            The user's notebook server's base URL, if running; null if
+          description: The user's notebook server's base URL, if running; null if
             not.
         pending:
           type: string
@@ -1686,8 +1680,7 @@ components:
       properties:
         name:
           type: string
-          description:
-            The server's name. The user's default server has an empty name
+          description: The server's name. The user's default server has an empty name
             ('')
         ready:
           type: boolean
@@ -1750,15 +1743,13 @@ components:
         state:
           type: object
           properties: {}
-          description:
-            Arbitrary internal state from this server's spawner. Only available
+          description: Arbitrary internal state from this server's spawner. Only available
             on the hub's users list or get-user-by-name method, and only with admin:users:server_state
             scope. None otherwise.
         user_options:
           type: object
           properties: {}
-          description:
-            User specified options for the user's spawned instance of a
+          description: User specified options for the user's spawned instance of a
             single-user server.
     RequestIdentity:
       description: |
@@ -1776,6 +1767,13 @@ components:
               service: "#/components/schemas/Service"
         - type: object
           properties:
+            kind:
+              type: string
+              description: |
+                'user' or 'service' depending on the entity which owns the token
+              enum:
+                - user
+                - service
             session_id:
               type:
                 - string
@@ -1812,6 +1810,11 @@ components:
         name:
           type: string
           description: The group's name
+        kind:
+          type: string
+          description: Always the string 'group'
+          enum:
+            - group
         users:
           type: array
           description: The names of users who are members of this group
@@ -1837,6 +1840,11 @@ components:
         name:
           type: string
           description: The service's name
+        kind:
+          type: string
+          description: the string 'service' to distinguish from 'user'
+          enum:
+            - service
         admin:
           type: boolean
           description: Whether the service is an admin
@@ -1877,7 +1885,14 @@ components:
           description: the server name. '' for the default server.
         url:
           type: string
-          description: the server's URL
+          description: the server's URL (path only when not using subdomains)
+        full_url:
+          type:
+            - string
+            - "null"
+          description: |
+            The full URL of the server (`https://hub.example.org/user/:name/:servername`).
+            `null` unless JupyterHub.public_url or subdomains are configured.
         ready:
           type: boolean
           description: whether the server is ready
@@ -1903,8 +1918,7 @@ components:
           items:
             type: string
         group:
-          description:
-            the group being shared with (exactly one of 'user' or 'group'
+          description: the group being shared with (exactly one of 'user' or 'group'
             will be non-null, the other will be null)
           type:
             - object
@@ -1913,8 +1927,7 @@ components:
             name:
               type: string
         user:
-          description:
-            the user being shared with (exactly one of 'user' or 'group'
+          description: the user being shared with (exactly one of 'user' or 'group'
             will be non-null, the other will be null)
           type:
             - object
@@ -1928,8 +1941,7 @@ components:
           format: date-time
 
     ShareCode:
-      description:
-        A single sharing code. There is at most one of these objects per
+      description: A single sharing code. There is at most one of these objects per
         (server, user) or (server, group) combination.
       type: object
       properties:
@@ -1965,8 +1977,7 @@ components:
       properties:
         id:
           type: string
-          description:
-            The id of the API token. Used for modifying or deleting the
+          description: The id of the API token. Used for modifying or deleting the
             token.
         user:
           type: string
@@ -1976,22 +1987,19 @@ components:
           description: The service that owns the token (undefined of owned by a user)
         roles:
           type: array
-          description:
-            Deprecated in JupyterHub 3, always an empty list. Tokens have
+          description: Deprecated in JupyterHub 3, always an empty list. Tokens have
             'scopes' starting from JupyterHub 3.
           items:
             type: string
         scopes:
           type: array
-          description:
-            List of scopes this token has been assigned. New in JupyterHub
+          description: List of scopes this token has been assigned. New in JupyterHub
             3. In JupyterHub 2.x, tokens were assigned 'roles' instead of scopes.
           items:
             type: string
         note:
           type: string
-          description:
-            A note about the token, typically describing what it was created
+          description: A note about the token, typically describing what it was created
             for.
         created:
           type: string
@@ -2022,13 +2030,11 @@ components:
       properties:
         token:
           type: string
-          description:
-            The token itself. Only present in responses to requests for
+          description: The token itself. Only present in responses to requests for
             a new token.
         id:
           type: string
-          description:
-            The id of the API token. Used for modifying or deleting the
+          description: The id of the API token. Used for modifying or deleting the
             token.
         user:
           type: string
@@ -2038,22 +2044,19 @@ components:
           description: The service that owns the token (undefined of owned by a user)
         roles:
           type: array
-          description:
-            Deprecated in JupyterHub 3, always an empty list. Tokens have
+          description: Deprecated in JupyterHub 3, always an empty list. Tokens have
             'scopes' starting from JupyterHub 3.
           items:
             type: string
         scopes:
           type: array
-          description:
-            List of scopes this token has been assigned. New in JupyterHub
+          description: List of scopes this token has been assigned. New in JupyterHub
             3. In JupyterHub 2.x, tokens were assigned 'roles' instead of scopes.
           items:
             type: string
         note:
           type: string
-          description:
-            A note about the token, typically describing what it was created
+          description: A note about the token, typically describing what it was created
             for.
         created:
           type: string
@@ -2091,27 +2094,22 @@ components:
           tokenUrl: /hub/api/oauth2/token
           scopes:
             (no_scope): Identify the owner of the requesting entity.
-            self:
-              The user’s own resources _(metascope for users, resolves to (no_scope)
+            self: The user’s own resources _(metascope for users, resolves to (no_scope)
               for services)_
-            inherit:
-              Everything that the token-owning entity can access _(metascope
+            inherit: Everything that the token-owning entity can access _(metascope
               for tokens)_
-            admin-ui:
-              Access the admin page. Permission to take actions via the admin
+            admin-ui: Access the admin page. Permission to take actions via the admin
               page granted separately.
-            admin:users:
-              Read, write, create and delete users and their authentication
-              state, not including their servers or tokens.
+            admin:users: Read, modify, create, and delete users and their authentication
+              state, not including their servers or tokens. This is an extremely privileged
+              scope and should be considered tantamount to superuser.
             admin:auth_state: Read a user’s authentication state.
-            users:
-              Read and write permissions to user models (excluding servers, tokens
+            users: Read and write permissions to user models (excluding servers, tokens
               and authentication state).
             delete:users: Delete users.
             list:users: List users, including at least their names.
-            read:users:
-              Read user models (excluding including servers, tokens and
-              authentication state).
+            read:users: Read user models (including the URL of the default server
+              if it is running).
             read:users:name: Read names of users.
             read:users:groups: Read users’ group membership.
             read:users:activity: Read time of last user activity.
@@ -2120,27 +2118,23 @@ components:
             read:roles:services: Read service role assignments.
             read:roles:groups: Read group role assignments.
             users:activity: Update time of last user activity.
-            admin:servers:
-              Read, start, stop, create and delete user servers and their
+            admin:servers: Read, start, stop, create and delete user servers and their
               state.
             admin:server_state: Read and write users’ server state.
             servers: Start and stop user servers.
-            read:servers:
-              Read users’ names and their server models (excluding the
+            read:servers: Read users’ names and their server models (excluding the
               server state).
             delete:servers: Stop and delete users' servers.
             tokens: Read, write, create and delete user tokens.
             read:tokens: Read user tokens.
             admin:groups: Read and write group information, create and delete groups.
-            groups:
-              Read and write group information, including adding/removing users
-              to/from groups.
+            groups: 'Read and write group information, including adding/removing any
+              users to/from groups. Note: adding users to groups may affect permissions.'
             list:groups: List groups, including at least their names.
             read:groups: Read group models.
             read:groups:name: Read group names.
             delete:groups: Delete groups.
-            admin:services:
-              Create, read, update, delete services, not including services
+            admin:services: Create, read, update, delete services, not including services
               defined from config files.
             list:services: List services, including at least their names.
             read:services: Read service models.
@@ -2154,8 +2148,7 @@ components:
             read:groups:shares: Read servers shared with a group.
             read:shares: Read information about shared access to servers.
             shares: Manage access to shared servers.
-            proxy:
-              Read information about the proxy’s routing table, sync the Hub
+            proxy: Read information about the proxy’s routing table, sync the Hub
               with the proxy and notify the Hub about a new proxy.
             shutdown: Shutdown the hub.
             read:metrics: Read prometheus metrics.

docs/source/conf.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from urllib.request import urlretrieve
 
 from docutils import nodes
+from intersphinx_registry import get_intersphinx_mapping
 from ruamel.yaml import YAML
 from sphinx.directives.other import SphinxDirective
 from sphinx.util import logging
@@ -294,6 +295,8 @@ linkcheck_ignore = [
     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/.*",
+    # Occasionally blocks CI checks with 403
+    r"https://www\.mysql\.com",
 ]
 linkcheck_anchors_ignore = [
     "/#!",
@@ -303,12 +306,15 @@ linkcheck_anchors_ignore = [
 # -- Intersphinx -------------------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 #
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "tornado": ("https://www.tornadoweb.org/en/stable/", None),
-    "jupyter-server": ("https://jupyter-server.readthedocs.io/en/stable/", None),
-    "nbgitpuller": ("https://nbgitpuller.readthedocs.io/en/latest", None),
-}
+
+intersphinx_mapping = get_intersphinx_mapping(
+    packages={
+        "python",
+        "tornado",
+        "jupyter-server",
+        "nbgitpuller",
+    }
+)
 
 # -- Options for the opengraph extension -------------------------------------
 # ref: https://github.com/wpilibsuite/sphinxext-opengraph#options

docs/source/contributing/community.md

@@ -1,3 +1,5 @@
+(contributing:community)=
+
 # Community communication channels
 
 We use different channels of communication for different purposes. Whichever one you use will depend on what kind of communication you want to engage in.

docs/source/contributing/contributor-list.md

@@ -1,3 +1,5 @@
+(contributing:contributors)=
+
 # Contributors
 
 Project Jupyter thanks the following people for their help and

docs/source/contributing/docs.md

@@ -1,4 +1,4 @@
-(contributing-docs)=
+(contributing:docs)=
 
 # Contributing Documentation
 
@@ -13,7 +13,7 @@ stored under the `docs/source` directory) and converts it into various
 formats for people to read. To make sure the documentation you write or
 change renders correctly, it is good practice to test it locally.
 
-1. Make sure you have successfully completed {ref}`contributing/setup`.
+1. Make sure you have successfully completed {ref}`contributing:setup`.
 
 2. Install the packages required to build the docs.
 

docs/source/contributing/index.md

@@ -1,3 +1,5 @@
+(contributing)=
+
 # Contributing
 
 We want you to contribute to JupyterHub in ways that are most exciting

docs/source/contributing/roadmap.md

@@ -1,3 +1,5 @@
+(contributing:roadmap)=
+
 # The JupyterHub roadmap
 
 This roadmap collects "next steps" for JupyterHub. It is about creating a

docs/source/contributing/security.md

@@ -1,7 +1,9 @@
+(contributing:security)=
+
 # Reporting security issues in Jupyter or JupyterHub
 
 If you find a security vulnerability in Jupyter or JupyterHub,
-whether it is a failure of the security model described in [Security Overview](web-security)
+whether it is a failure of the security model described in [Security Overview](explanation:security)
 or a failure in implementation,
 please report it to <mailto:security@ipython.org>.
 

docs/source/contributing/setup.md

@@ -1,4 +1,4 @@
-(contributing/setup)=
+(contributing:setup)=
 
 # Setting up a development install
 

docs/source/contributing/tests.md

@@ -11,7 +11,7 @@ can find them under the [jupyterhub/tests](https://github.com/jupyterhub/jupyter
 
 ## Running the tests
 
-1. Make sure you have completed {ref}`contributing/setup`.
+1. Make sure you have completed {ref}`contributing:setup`.
    Once you are done, you would be able to run `jupyterhub` from the command line and access it from your web browser.
    This ensures that the dev environment is properly set up for tests to run.
 
@@ -126,7 +126,7 @@ For more information on asyncio and event-loops, here are some resources:
 
 ### All the tests are failing
 
-Make sure you have completed all the steps in {ref}`contributing/setup` successfully, and are able to access JupyterHub from your browser at http://localhost:8000 after starting `jupyterhub` in your command line.
+Make sure you have completed all the steps in {ref}`contributing:setup` successfully, and are able to access JupyterHub from your browser at http://localhost:8000 after starting `jupyterhub` in your command line.
 
 ## Code formatting and linting
 

docs/source/explanation/capacity-planning.md

@@ -1,3 +1,5 @@
+(explanation:capacity-planning)=
+
 # Capacity planning
 
 General capacity planning advice for JupyterHub is hard to give,
@@ -206,7 +208,7 @@ mybinder.org node CPU usage is low with 50-150 users sharing just 8 cores
 
 ### Concurrent users and culling idle servers
 
-Related to [][idleness], all of these resource consumptions and limits are calculated based on **concurrently active users**,
+Related to [](idleness), all of these resource consumptions and limits are calculated based on **concurrently active users**,
 not total users.
 You might have 10,000 users of your JupyterHub deployment, but only 100 of them running at any given time.
 That 100 is the main number you need to use for your capacity planning.

docs/source/explanation/concepts.md

@@ -0,0 +1,430 @@
+(explanation:concepts)=
+
+# JupyterHub: A conceptual overview
+
+```{warning}
+This page could be missing cross-links to other parts of
+the documentation. You can help by adding them!
+```
+
+JupyterHub is not what you think it is. Most things you think are
+part of JupyterHub are actually handled by some other component, for
+example the spawner or notebook server itself, and it's not always
+obvious how the parts relate. The knowledge contained here hasn't
+been assembled in one place before, and is essential to understand
+when setting up a sufficiently complex Jupyter(Hub) setup.
+
+This document was originally written to assist in debugging: very
+often, the actual problem is not where one thinks it is and thus
+people can't easily debug. In order to tell this story, we start at
+JupyterHub and go all the way down to the fundamental components of
+Jupyter.
+
+In this document, we occasionally leave things out or bend the truth
+where it helps in explanation, and give our explanations in terms of
+Python even though Jupyter itself is language-neutral. The "(&)"
+symbol highlights important points where this page leaves out or bends
+the truth for simplification of explanation, but there is more if you
+dig deeper.
+
+This guide is long, but after reading it you will be know of all major
+components in the Jupyter ecosystem and everything else you read
+should make sense.
+
+## What is Jupyter?
+
+Before we get too far, let's remember what our end goal is. A
+**Jupyter Notebook** is nothing more than a Python(&) process
+which is getting commands from a web browser and displaying the output
+via that browser. What the process actually sees is roughly like
+getting commands on standard input(&) and writing to standard
+output(&). There is nothing intrinsically special about this process
+
+- it can do anything a normal Python process can do, and nothing more.
+  The **Jupyter kernel** handles capturing output and converting things
+  such as graphics to a form usable by the browser.
+
+Everything we explain below is building up to this, going through many
+different layers which give you many ways of customizing how this
+process runs.
+
+## JupyterHub
+
+**JupyterHub** is the central piece that provides multi-user
+login capabilities. Despite this, the end user only briefly interacts with
+JupyterHub and most of the actual Jupyter session does not relate to
+the hub at all: the hub mainly handles authentication and creating (JupyterHub calls it "spawning") the
+single-user server. In short, anything which is related to _starting_
+the user's workspace/environment is about JupyterHub, anything about
+_running_ usually isn't.
+
+If you have problems connecting the authentication, spawning, and the
+proxy (explained below), the issue is usually with JupyterHub. To
+debug, JupyterHub has extensive logs which get printed to its console
+and can be used to discover most problems.
+
+The main pieces of JupyterHub are:
+
+### Authenticator
+
+JupyterHub itself doesn't actually manage your users. It has a
+database of users, but it is usually connected with some other system
+that manages the usernames and passwords. When someone tries to log
+in to JupyteHub, it asks the
+**authenticator**([basics](authenticators),
+[reference](../reference/authenticators)) if the
+username/password is valid(&). The authenticator returns a username(&),
+which is passed on to the spawner, which has to use it to start that
+user's environment. The authenticator can also return user
+groups and admin status of users, so that JupyterHub can do some
+higher-level management.
+
+The following authenticators are included with JupyterHub:
+
+- **PAMAuthenticator** uses the standard Unix/Linux operating system
+  functions to check users. Roughly, if someone already has access to
+  the machine (they can log in by ssh), they will be able to log in to
+  JupyterHub without any other setup. Thus, JupyterHub fills the role
+  of a ssh server, but providing a web-browser based way to access the
+  machine.
+
+There are [plenty of others to choose from](authenticators-reference).
+You can connect to almost any other existing service to manage your
+users. You either use all users from this other service (e.g. your
+company), or enable only the allowed users (e.g. your group's
+Github usernames). Some other popular authenticators include:
+
+- **OAuthenticator** uses the standard OAuth protocol to verify users.
+  For example, you can easily use Github to authenticate your users -
+  people have a "click to login with Github" button. This is often
+  done with a allowlist to only allow certain users.
+
+- **NativeAuthenticator** actually stores and validates its own
+  usernames and passwords, unlike most other authenticators. Thus,
+  you can manage all your users within JupyterHub only.
+
+- There are authenticators for LTI (learning management systems),
+  Shibboleth, Kerberos - and so on.
+
+The authenticator is configured with the
+`c.JupyterHub.authenticator_class` configuration option in the
+`jupyterhub_config.py` file.
+
+The authenticator runs internally to the Hub process but communicates
+with outside services.
+
+If you have trouble logging in, this is usually a problem of the
+authenticator. The authenticator logs are part of the the JupyterHub
+logs, but there may also be relevant information in whatever external
+services you are using.
+
+### Spawner
+
+The **spawner** ([basics](spawners),
+[reference](../reference/spawners)) is the real core of
+JupyterHub: when someone wants a notebook server, the spawner allocates
+resources and starts the server. The notebook server could run on the
+same machine as JupyterHub, on another machine, on some cloud service,
+or more. Administrators can limit resources (CPU, memory) or isolate users
+from each other - if the spawner supports it. They can also do no
+limiting and allow any user to access any other user's files if they
+are not configured properly.
+
+Some basic spawners included in JupyterHub are:
+
+- **LocalProcessSpawner** is built into JupyterHub. Upon launch it tries
+  to switch users to the given username (`su` (&)) and start the
+  notebook server. It requires that the hub be run as root (because
+  only root has permission to start processes as other user IDs).
+  LocalProcessSpawner is no different than a user logging in with
+  something like `ssh` and running `jupyter notebook`. PAMAuthenticator and
+  LocalProcessSpawner is the most basic way of using JupyterHub (and
+  what it does out of the box) and makes the hub not too dissimilar to
+  an advanced ssh server.
+
+There are [many more advanced spawners](/reference/spawners), and to
+show the diversity of spawning strategys some are listed below:
+
+- **SudoSpawner** is like LocalProcessSpawner but lets you run
+  JupyterHub without root. `sudo` has to be configured to allow the
+  hub's user to run processes under other user IDs.
+
+- **SystemdSpawner** uses Systemd to start other processes. It can
+  isolate users from each other and provide resource limiting.
+
+- **DockerSpawner** runs stuff in Docker, a containerization system.
+  This lets you fully isolate users, limit CPU, memory, and provide
+  other container images to fully customize the environment.
+
+- **KubeSpawner** runs on the Kubernetes, a cloud orchestration
+  system. The spawner can easily limit users and provide cloud
+  scaling - but the spawner doesn't actually do that, Kubernetes
+  does. The spawner just tells Kubernetes what to do. If you want to
+  get KubeSpawner to do something, first you would figure out how to
+  do it in Kubernetes, then figure out how to tell KubeSpawner to tell
+  Kubernetes that. Actually... this is true for most spawners.
+
+- **BatchSpawner** runs on computer clusters with batch job scheduling
+  systems (e.g Slurm, HTCondor, PBS, etc). The user processes are run
+  as batch jobs, having access to all the data and software that the
+  users normally will.
+
+In short, spawners are the interface to the rest of the operating
+system, and to configure them right you need to know a bit about how
+the corresponding operating system service works.
+
+The spawner is responsible for the environment of the single-user
+notebook servers (described in the next section). In the end, it just
+makes a choice about how to start these processes: for example, the
+Docker spawner starts a normal Docker container and runs the right
+command inside of it. Thus, the spawner is responsible for setting
+what kind of software and data is available to the user.
+
+The spawner runs internally to the Hub process but communicates with
+outside services. It is configured by `c.JupyterHub.spawner_class` in
+`jupyterhub_config.py`.
+
+If a user tries to launch a notebook server and it doesn't work, the
+error is usually with the spawner or the notebook server (as described
+in the next section). Each spawner outputs some logs to the main
+JupyterHub logs, but may also have logs in other places depending on
+what services it interacts with (for example, the Docker spawner
+somehow puts logs in the Docker system services, Kubernetes through
+the `kubectl` API).
+
+### Proxy
+
+The JupyterHub **proxy** relays connections between the users
+and their single-user notebook servers. What this basically means is
+that the hub itself can shut down and the proxy can continue to
+allow users to communicate with their notebook servers. (This
+further emphasizes that the hub is responsible for starting, not
+running, the notebooks). By default, the hub starts the proxy
+automatically
+and stops the proxy when the hub stops (so that connections get
+interrupted). But when you [configure the proxy to run
+separately](howto:separate-proxy),
+user's connections will continue to work even without the hub.
+
+The default proxy is **ConfigurableHttpProxy** which is simple but
+effective. A more advanced option is the [**Traefik Proxy**](https://blog.jupyter.org/introducing-traefikproxy-a-new-jupyterhub-proxy-based-on-traefik-4839e972faf6),
+which gives you redundancy and high-availability.
+
+When users "connect to JupyterHub", they _always_ first connect to the
+proxy and the proxy relays the connection to the hub. Thus, the proxy
+is responsible for SSL and accepting connections from the rest of the
+internet. The user uses the hub to authenticate and start the server,
+and then the hub connects back to the proxy to adjust the proxy routes
+for the user's server (e.g. the web path `/user/someone` redirects to
+the server of someone at a certain internal address). The proxy has
+to be able to internally connect to both the hub and all the
+single-user servers.
+
+The proxy always runs as a separate process to JupyterHub (even though
+JupyterHub can start it for you). JupyterHub has one set of
+configuration options for the proxy addresses (`bind_url`) and one for
+the hub (`hub_bind_url`). If `bind_url` is given, it is just passed to
+the automatic proxy to tell it what to do.
+
+If you have problems after users are redirected to their single-user
+notebook servers, or making the first connection to the hub, it is
+usually caused by the proxy. The ConfigurableHttpProxy's logs are
+mixed with JupyterHub's logs if it's started through the hub (the
+default case), otherwise from whatever system runs the proxy (if you
+do configure it, you'll know).
+
+### Services
+
+JupyterHub has the concept of **services** ([basics](tutorial:services),
+[reference](services-reference)), which are other web services
+started by the hub, but otherwise are not necessarily related to the
+hub itself. They are often used to do things related to Jupyter
+(things that user interacts with, usually not the hub), but could
+always be run some other way. Running from the hub provides an easy
+way to get Hub API tokens and authenticate users against the hub. It
+can also automatically add a proxy route to forward web requests to
+that service.
+
+A common example of a service is the [cull idle
+servers](https://github.com/jupyterhub/jupyterhub-idle-culler)
+service. When started by the hub, it automatically gets admin API
+tokens. It uses the API to list all running servers, compare against
+activity timeouts, and shut down servers exceeding the limits. Even
+though this is an intrinsic part of JupyterHub, it is only loosely
+coupled and running as a service provides convenience of
+authentication - it could be just as well run some other way, with a
+manually provided API token.
+
+The configuration option `c.JupyterHub.services` is used to start
+services from the hub.
+
+When a service is started from JupyterHub automatically, its logs are
+included in the JupyterHub logs.
+
+## Single-user notebook server
+
+The **single-user notebook server** is the same thing you get by
+running `jupyter notebook` or `jupyter lab` from the command line -
+the actual Jupyter user interface for a single person.
+
+The role of the spawner is to start this server - basically, running
+the command `jupyter notebook`. Actually it doesn't run that, it runs
+`jupyterhub-singleuser` which first communicates with the hub to say
+"I'm alive" before running a completely normal Jupyter server. The
+single-user server can be JupyterLab or classic notebooks. By this
+point, the hub is almost completely out of the picture (the web
+traffic is going through proxy unchanged). Also by this time, the
+spawner has already decided the environment which this single-user
+server will have and the single-user server has to deal with that.
+
+The spawner starts the server using `jupyterhub-singleuser` with some
+environment variables like `JUPYTERHUB_API_TOKEN` and
+`JUPYTERHUB_BASE_URL` which tell the single-user server how to connect
+back to the hub in order to say that it's ready.
+
+The single-user server options are **JupyterLab** and **classic
+Jupyter Notebook**. They both run through the same backend server process--the web
+frontend is an option when it is starting. The spawner can choose the
+command line when it starts the single-user server. Extensions are a
+property of the single-user server (in two parts: there can be a part
+that runs in the Python server process, and parts that run in
+javascript in lab or notebook).
+
+If one wants to install software for users, it is not a matter of
+"installing it for JupyerHub" - it's a matter of installing it for the
+single-user server, which might be the same environment as the hub,
+but not necessarily. (see below - it's a matter of the kernels!)
+
+After the single-user notebook server is started, any errors are only
+an issue of the single-user notebook server. Sometimes, it seems like
+the spawner is failing, but really the spawner is working but the
+single-user notebook server dies right away (in this case, you need to
+find the problem with the single-user server and adjust the spawner to
+start it correctly or fix the environment). This can happen, for
+example, if the spawner doesn't set an environment variable or doesn't
+provide storage.
+
+The single-user server's logs are printed to stdout/stderr, and the
+spawer decides where those streams are directed, so if you
+notice problems at this phase you need to check your spawner for
+instructions for accessing the single-user logs. For example, the
+LocalProcessSpawner logs are just outputted to the same JupyterHub
+output logs, the SystemdSpawner logs are
+written to the Systemd journal, Docker and Kubernetes logs are written
+to Docker and Kubernetes respectively, and batchspawner output goes to
+the normal output places of batch jobs and is an explicit
+configuration option of the spawner.
+
+**(Jupyter) Notebook** is the classic interface, where each notebook
+opens in a separate tab. It is traditionally started by `jupyter
+notebook`. Does anything need to be said here?
+
+**JupyterLab** is the new interface, where multiple notebooks are
+openable in the same tab in an IDE-like environment. It is
+traditionally started with `jupyter lab`. Both Notebook and Lab use
+the same `.ipynb` file format.
+
+JupyterLab is run thorugh the same server file, but at a path `/lab`
+instead of `/tree`. Thus, they can be active at the same time in the
+backend and you can switch between them at runtime by changing your
+URL path.
+
+Extensions need to be re-written for JupyterLab (if moving from
+classic notebooks). But, the server-side of the extensions can be
+shared by both.
+
+## Kernel
+
+The commands you run in the notebook session are not executed in the same process as
+the notebook itself, but in a separate **Jupyter kernel**. There are [many
+kernels
+available](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels).
+
+As a basic approximation, a **Jupyter kernel** is a process which
+accepts commands (cells that are run) and returns the output to
+Jupyter to display. One example is the **IPython Jupyter kernel**,
+which runs Python. There is nothing special about it, it can be
+considered a \*normal Python process. The kernel process can be
+approximated in UNIX terms as a process that takes commands on stdin
+and returns stuff on stdout(&). Obviously, it's more because it has
+to be able to disentangle all the possible outputs, such as figures,
+and present it to the user in a web browser.
+
+Kernel communication is via the the ZeroMQ protocol on the local
+computer. Kernels are separate processes from the main single-user
+notebook server (and thus obviously, different from the JupyterHub
+process and everything else). By default (and unless you do something
+special), kernels share the same environment as the notebook server
+(data, resource limits, permissions, user id, etc.). But they _can_
+run in a separate Python environment from the single-user server
+(search `--prefix` in the [ipykernel installation
+instructions](https://ipython.readthedocs.io/en/stable/install/kernel_install.html))
+There are also more fancy techniques such as the [Jupyter Kernel
+Gateway](https://jupyter-kernel-gateway.readthedocs.io/) and [Enterprise
+Gateway](https://jupyter-enterprise-gateway.readthedocs.io/), which
+allow you to run the kernels on a different machine and possibly with
+a different environment.
+
+A kernel doesn't just execute it's language - cell magics such as `%`,
+`%%`, and `!` are a property of the kernel - in particular, these are
+IPython kernel commands and don't necessarily work in any other
+kernel unless they specifically support them.
+
+Kernels are yet _another_ layer of configurability.
+Each kernel can run a different programming language, with different
+software, and so on. By default, they would run in the same
+environment as the single-user notebook server, and the most common
+other way they are configured is by
+running in different Python virtual environments or conda
+environments. They can be started and killed independently (there is
+normally one per notebook you have open). The kernel uses
+most of your memory and CPU when running Jupyter - the rest of the web
+interface has a small footprint.
+
+You can list your installed kernels with `jupyter kernelspec list`.
+If you look at one of `kernel.json` files in those directories, you
+will see exactly what command is run. These are normally
+automatically made by the kernels, but can be edited as needed. [The
+spec](https://jupyter-client.readthedocs.io/en/stable/kernels.html)
+tells you even more.
+
+The kernel normally has to be reachable by the single-user notebook server
+but the gateways mentioned above can get around that limitation.
+
+If you get problems with "Kernel died" or some other error in a single
+notebook but the single-user notebook server stays working, it is
+usually a problem with the kernel. It could be that you are trying to
+use more resources than you are allowed and the symptom is the kernel
+getting killed. It could be that it crashes for some other reason.
+In these cases, you need to find the kernel logs and investigate.
+
+The debug logs for the kernel are normally mixed in with the
+single-user notebook server logs.
+
+## JupyterHub distributions
+
+There are several "distributions" which automatically install all of
+the things above and configure them for a certain purpose. They are
+good ways to get started, but if you have custom needs, eventually it
+may become hard to adapt them to your requirements.
+
+- [**Zero to JupyterHub with
+  Kubernetes**](https://zero-to-jupyterhub.readthedocs.io/) installs
+  an entire scaleable system using Kubernetes. Uses KubeSpawner,
+  ....Authenticator, ....
+
+- [**The Littlest JupyterHub**](https://tljh.jupyter.org/) installs JupyterHub on a single system
+  using SystemdSpawner and NativeAuthenticator (which manages users
+  itself).
+
+- [**JupyterHub the hard way**](https://github.com/jupyterhub/jupyterhub-the-hard-way/blob/master/docs/installation-guide-hard.md)
+  takes you through everything yourself. It is a natural companion to
+  this guide, since you get to experience every little bit.
+
+## What's next?
+
+Now you know everything. Well, you know how everything relates, but
+there are still plenty of details, implementations, and exceptions.
+When setting up JupyterHub, the first step is to consider the above
+layers, decide the right option for each of them, then begin putting
+everything together.

docs/source/explanation/database.md

@@ -1,4 +1,4 @@
-(hub-database)=
+(explanation:hub-database)=
 
 # The Hub's Database
 

docs/source/explanation/index.md

@@ -1,3 +1,5 @@
+(explanation)=
+
 # Explanation
 
 _Explanation_ documentation provide big-picture descriptions of how JupyterHub works. This section is meant to build your understanding of particular topics.
@@ -5,6 +7,7 @@ _Explanation_ documentation provide big-picture descriptions of how JupyterHub w
 ```{toctree}
 :maxdepth: 1
 
+concepts
 capacity-planning
 database
 websecurity

docs/source/explanation/oauth.md

@@ -1,4 +1,4 @@
-(jupyterhub-oauth)=
+(explanation:hub-oauth)=
 
 # JupyterHub and OAuth
 

docs/source/explanation/singleuser.md

@@ -1,4 +1,4 @@
-(singleuser)=
+(explanation:singleuser)=
 
 # The JupyterHub single-user server
 
@@ -24,7 +24,7 @@ It's the same!
 
 ## Single-user server authentication
 
-Implementation-wise, JupyterHub single-user servers are a special-case of {ref}`services`
+Implementation-wise, JupyterHub single-user servers are a special-case of {ref}`services-reference`
 and as such use the same (OAuth) authentication mechanism (more on OAuth in JupyterHub at [](oauth)).
 This is primarily implemented in the {class}`~.HubOAuth` class.
 
@@ -104,6 +104,6 @@ But technically, all JupyterHub cares about is that it is:
 1. an http server at the prescribed URL, accessible from the Hub and proxy, and
 2. authenticated via [OAuth](oauth) with the Hub (it doesn't even have to do this, if you want to do your own authentication, as is done in BinderHub)
 
-which means that you can customize JupyterHub to launch _any_ web application that meets these criteria, by following the specifications in {ref}`services`.
+which means that you can customize JupyterHub to launch _any_ web application that meets these criteria, by following the specifications in {ref}`services-reference`.
 
 Most of the time, though, it's easier to use [jupyter-server-proxy](https://jupyter-server-proxy.readthedocs.io) if you want to launch additional web applications in JupyterHub.

docs/source/explanation/websecurity.md

@@ -1,4 +1,4 @@
-(web-security)=
+(explanation:security)=
 
 # Security Overview
 

docs/source/faq/faq.md

@@ -1,3 +1,5 @@
+(faq)=
+
 # Frequently asked questions
 
 ## How do I share links to notebooks?

docs/source/faq/institutional-faq.md

@@ -1,3 +1,5 @@
+(faq:institutional)=
+
 # Institutional FAQ
 
 This page contains common questions from users of JupyterHub,
@@ -64,7 +66,7 @@ industry, and government research labs. It is most-commonly used by two kinds of
 Here is a sample of organizations that use JupyterHub:
 
 - **Universities and colleges**: UC Berkeley, UC San Diego, Cal Poly SLO, Harvard University, University of Chicago,
-  University of Oslo, University of Sheffield, Université Paris Sud, University of Versailles
+  University of Oslo, University of Sheffield, Université Paris Sud, University of Versailles, University of Portland
 - **Research laboratories**: NASA, NCAR, NOAA, the Large Synoptic Survey Telescope, Brookhaven National Lab,
   Minnesota Supercomputing Institute, ALCF, CERN, Lawrence Livermore National Laboratory, HUNT
 - **Online communities**: Pangeo, Quantopian, mybinder.org, MathHub, Open Humans
@@ -130,7 +132,7 @@ level for several years, and makes a number of "default" security decisions that
 users.
 
 - For security considerations in the base JupyterHub application,
-  [see the JupyterHub security page](web-security).
+  [see the JupyterHub security page](explanation:security).
 - For security considerations when deploying JupyterHub on Kubernetes, see the
   [JupyterHub on Kubernetes security page](https://z2jh.jupyter.org/en/latest/security.html).
 

docs/source/faq/troubleshooting.md

@@ -1,4 +1,4 @@
-(troubleshooting)=
+(faq:troubleshooting)=
 
 # Troubleshooting
 
@@ -167,7 +167,7 @@ When your whole JupyterHub sits behind an organization proxy (_not_ a reverse pr
 
 ### Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error
 
-{ref}`services` allow processes to interact with JupyterHub's REST API. Example use-cases include:
+{ref}`services-reference` allow processes to interact with JupyterHub's REST API. Example use-cases include:
 
 - **Secure Testing**: provide a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems.
 - **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such as grading assignments.
@@ -198,6 +198,23 @@ With a docker container, pass in the environment variable with the run command:
 
 [This example](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-notebook/external) demonstrates how to combine the use of the `jupyterhub-singleuser` environment variables when launching a Notebook as an externally managed service.
 
+### Jupyter Notebook/Lab can be launched, but notebooks seem to hang when trying to execute a cell
+
+This often occurs when your browser is unable to open a websocket connection to a Jupyter kernel.
+
+#### Diagnose
+
+Open your browser console, e.g. [Chrome](https://developer.chrome.com/docs/devtools/console), [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/web_console/).
+If you see errors related to opening websockets this is likely to be the problem.
+
+#### Solutions
+
+This could be caused by anything related to the network between your computer/browser and the server running JupyterHub, such as:
+
+- reverse proxies (see {ref}`howto:config:reverse-proxy` for example configurations)
+- anti-virus or firewalls running on your computer or JupyterHub server
+- transparent proxies running on your network
+
 ## How do I...?
 
 ### Use a chained SSL certificate
@@ -259,17 +276,6 @@ the entire filesystem and set the default to the user's home directory.
     c.Spawner.notebook_dir = '/'
     c.Spawner.default_url = '/home/%U' # %U will be replaced with the username
 
-### How do I increase the number of pySpark executors on YARN?
-
-From the command line, pySpark executors can be configured using a command
-similar to this one:
-
-    pyspark --total-executor-cores 2 --executor-memory 1G
-
-[Cloudera documentation for configuring spark on YARN applications](https://www.cloudera.com/documentation/enterprise/latest/topics/cdh_ig_running_spark_on_yarn.html#spark_on_yarn_config_apps)
-provides additional information. The [pySpark configuration documentation](https://spark.apache.org/docs/0.9.0/configuration.html)
-is also helpful for programmatic configuration examples.
-
 ### How do I use JupyterLab's pre-release version with JupyterHub?
 
 While JupyterLab is still under active development, we have had users
@@ -300,6 +306,52 @@ notebook servers to default to JupyterLab:
 
 Users will need a GitHub account to log in and be authenticated by the Hub.
 
+### I'm seeing "403 Forbidden XSRF cookie does not match POST" when users try to login
+
+During login, JupyterHub takes the request IP into account for CSRF protection.
+If proxies are not configured to properly set forwarded ips,
+JupyterHub will see all requests as coming from an internal ip,
+likely the ip of the proxy itself.
+You can see this in the JupyterHub logs, which log the ip address of requests.
+If most requests look like they are coming from a small number `10.0.x.x` or `172.16.x.x` ips, the proxy is not forwarding the true request ip properly.
+If the proxy has multiple replicas,
+then it is likely the ip may change from one request to the next,
+leading to this error during login:
+
+> 403 Forbidden XSRF cookie does not match POST argument
+
+The best way to fix this is to ensure your proxies set the forwarded headers, e.g. for nginx:
+
+```nginx
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header Host $http_host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+```
+
+But if this is not available to you, you can instruct jupyterhub to ignore IPs from certain networks
+with the environment variable `$JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS`.
+For example, to ignore the common [private networks](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses):
+
+```bash
+export JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS="10.0.0.0/8;172.16.0.0/12;192.168.0.0/16"
+```
+
+The result will be that any request from an ip on one of these networks will be treated as coming from the same source.
+
+To totally disable taking the ip into consideration, set
+
+```bash
+export JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS="0.0.0.0/0"
+```
+
+If your proxy sets its own headers to identify a browser origin, you can instruct JupyterHub to use those:
+
+```bash
+export JUPYTERHUB_XSRF_ANONYMOUS_ID_HEADERS="My-Custom-Header;User-Agent"
+```
+
+Again, these things are only used to compute the XSRF token used while a user is not logged in (i.e. during login itself).
+
 ### How do I set up rotating daily logs?
 
 You can do this with [logrotate](https://linux.die.net/man/8/logrotate),

docs/source/howto/api-only.md

@@ -1,4 +1,4 @@
-(api-only)=
+(howto:api-only)=
 
 # Deploying JupyterHub in "API only mode"
 

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

@@ -1,3 +1,5 @@
+(howto:config:gh-oauth)=
+
 # Configure GitHub OAuth
 
 In this example, we show a configuration file for a fairly standard JupyterHub

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

@@ -1,3 +1,5 @@
+(howto:config:reverse-proxy)=
+
 # Using a reverse proxy
 
 In the following example, we show configuration files for a JupyterHub server

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

@@ -1,3 +1,5 @@
+(howto:config:no-sudo)=
+
 # Run JupyterHub without root privileges using `sudo`
 
 **Note:** Setting up `sudo` permissions involves many pieces of system
@@ -123,7 +125,7 @@ the shadow password database.
 **Note:** On [Fedora based distributions](https://fedoraproject.org/wiki/List_of_Fedora_remixes) there is no clear way to configure
 the PAM database to allow sufficient access for authenticating with the target user's password
 from JupyterHub. As a workaround we recommend use an
-[alternative authentication method](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+[alternative authentication method](authenticators-reference).
 
 ```bash
 $ ls -l /etc/shadow

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

@@ -1,3 +1,5 @@
+(howto:config:user-env)=
+
 # Configuring user environments
 
 To deploy JupyterHub means you are providing Jupyter notebook environments for

docs/source/howto/log-messages.md

@@ -1,3 +1,5 @@
+(howto:log-messages)=
+
 # Interpreting common log messages
 
 When debugging errors and outages, looking at the logs emitted by

docs/source/howto/proxy.md

@@ -1,3 +1,5 @@
+(howto:custom-proxy)=
+
 # Writing a custom Proxy implementation
 
 JupyterHub 0.8 introduced the ability to write a custom implementation of the

docs/source/howto/rest.md

@@ -1,4 +1,4 @@
-(using-jupyterhub-rest-api)=
+(howto:rest-api)=
 
 # Using JupyterHub's REST API
 

docs/source/howto/separate-proxy.md

@@ -1,4 +1,4 @@
-(separate-proxy)=
+(howto:separate-proxy)=
 
 # Running proxy separately from the hub
 

docs/source/howto/templates.md

@@ -1,3 +1,5 @@
+(howto:templates)=
+
 # Working with templates and UI
 
 The pages of the JupyterHub application are generated from

docs/source/howto/upgrading-v5.md

@@ -1,4 +1,4 @@
-(upgrading-v5)=
+(howto:upgrading-v5)=
 
 # Upgrading to JupyterHub 5
 

docs/source/howto/upgrading.md

@@ -1,4 +1,4 @@
-(upgrading-jupyterhub)=
+(howto:upgrading-jupyterhub)=
 
 # Upgrading JupyterHub
 

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

@@ -14,26 +14,52 @@ The files are:
        scopes descriptions are updated in it.
 """
 
-import os
 from collections import defaultdict
 from pathlib import Path
-from subprocess import run
 
 from pytablewriter import MarkdownTableWriter
 from ruamel.yaml import YAML
 
-from jupyterhub import __version__
-from jupyterhub.scopes import scope_definitions
-
-HERE = os.path.abspath(os.path.dirname(__file__))
-DOCS = Path(HERE).parent.parent.absolute()
+HERE = Path(__file__).parent.absolute()
+DOCS = HERE / ".." / ".."
 REST_API_YAML = DOCS.joinpath("source", "_static", "rest-api.yml")
-SCOPE_TABLE_MD = Path(HERE).joinpath("scope-table.md")
+SCOPE_TABLE_MD = HERE.joinpath("scope-table.md")
+
+
+def _load_jupyterhub_info():
+    """
+    The equivalent of
+
+        from jupyterhub import __version__
+        from jupyterhub.scopes import scope_definitions
+
+    but without needing to install JupyterHub and dependencies
+    so that we can run this pre-commit
+    """
+    root = HERE / ".." / ".." / ".."
+    g = {}
+    exec((root / "jupyterhub" / "_version.py").read_text(), g)
+
+    # To avoid parsing the whole of scope_definitions.py just pull out
+    # the relevant lines
+    scopes_file = root / "jupyterhub" / "scopes.py"
+    scopes_lines = []
+    for line in scopes_file.read_text().splitlines():
+        if not scopes_lines and line == "scope_definitions = {":
+            scopes_lines.append(line)
+        elif scopes_lines:
+            scopes_lines.append(line)
+            if line == "}":
+                break
+
+    exec("\n".join(scopes_lines), g)
+
+    return g["__version__"], g["scope_definitions"]
 
 
 class ScopeTableGenerator:
     def __init__(self):
-        self.scopes = scope_definitions
+        self.version, self.scopes = _load_jupyterhub_info()
 
     @classmethod
     def create_writer(cls, table_name, headers, values):
@@ -131,7 +157,7 @@ class ScopeTableGenerator:
         with open(filename) as f:
             content = yaml.load(f.read())
 
-        content["info"]["version"] = __version__
+        content["info"]["version"] = self.version
         for scope in self.scopes:
             description = self.scopes[scope]['description']
             doc_description = self.scopes[scope].get('doc_description', '')
@@ -145,12 +171,6 @@ class ScopeTableGenerator:
         with open(filename, 'w') as f:
             yaml.dump(content, f)
 
-        run(
-            ['pre-commit', 'run', 'prettier', '--files', filename],
-            cwd=HERE,
-            check=False,
-        )
-
 
 def main():
     table_generator = ScopeTableGenerator()

docs/source/rbac/scope-table.md

@@ -0,0 +1,58 @@
+Table 1. Available scopes and their hierarchy
+|                                    Scope                                    |                                                                                         Grants permission to:                                                                                         |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `(no_scope)`                                                                | Identify the owner of the requesting entity.                                                                                                                                                          |
+| `self`                                                                      | The user’s own resources _(metascope for users, resolves to (no_scope) for services)_                                                                                                                 |
+| `inherit`                                                                   | Everything that the token-owning entity can access _(metascope for tokens)_                                                                                                                           |
+| `admin-ui`                                                                  | Access the admin page. Permission to take actions via the admin page granted separately.                                                                                                              |
+| `admin:users`                                                               | Read, modify, create, and delete users and their authentication state, not including their servers or tokens. This is an extremely privileged scope and should be considered tantamount to superuser. |
+|    `admin:auth_state`                                        | Read a user’s authentication state.                                                                                                                                                                   |
+|    `users`                                                   | Read and write permissions to user models (excluding servers, tokens and authentication state).                                                                                                       |
+|       `read:users`                            | Read user models (including the URL of the default server if it is running).                                                                                                                          |
+|          `read:users:name`     | Read names of users.                                                                                                                                                                                  |
+|          `read:users:groups`   | Read users’ group membership.                                                                                                                                                                         |
+|          `read:users:activity` | Read time of last user activity.                                                                                                                                                                      |
+|       `list:users`                            | List users, including at least their names.                                                                                                                                                           |
+|          `read:users:name`     | Read names of users.                                                                                                                                                                                  |
+|       `users:activity`                        | Update time of last user activity.                                                                                                                                                                    |
+|          `read:users:activity` | Read time of last user activity.                                                                                                                                                                      |
+|    `read:roles:users`                                        | Read user role assignments.                                                                                                                                                                           |
+|    `delete:users`                                            | Delete users.                                                                                                                                                                                         |
+| `read:roles`                                                                | Read role assignments.                                                                                                                                                                                |
+|    `read:roles:users`                                        | Read user role assignments.                                                                                                                                                                           |
+|    `read:roles:services`                                     | Read service role assignments.                                                                                                                                                                        |
+|    `read:roles:groups`                                       | Read group role assignments.                                                                                                                                                                          |
+| `admin:servers`                                                             | Read, start, stop, create and delete user servers and their state.                                                                                                                                    |
+|    `admin:server_state`                                      | Read and write users’ server state.                                                                                                                                                                   |
+|    `servers`                                                 | Start and stop user servers.                                                                                                                                                                          |
+|       `read:servers`                          | Read users’ names and their server models (excluding the server state).                                                                                                                               |
+|          `read:users:name`     | Read names of users.                                                                                                                                                                                  |
+|       `delete:servers`                        | Stop and delete users' servers.                                                                                                                                                                       |
+| `tokens`                                                                    | Read, write, create and delete user tokens.                                                                                                                                                           |
+|    `read:tokens`                                             | Read user tokens.                                                                                                                                                                                     |
+| `admin:groups`                                                              | Read and write group information, create and delete groups.                                                                                                                                           |
+|    `groups`                                                  | Read and write group information, including adding/removing any users to/from groups. Note: adding users to groups may affect permissions.                                                            |
+|       `read:groups`                           | Read group models.                                                                                                                                                                                    |
+|          `read:groups:name`    | Read group names.                                                                                                                                                                                     |
+|       `list:groups`                           | List groups, including at least their names.                                                                                                                                                          |
+|          `read:groups:name`    | Read group names.                                                                                                                                                                                     |
+|    `read:roles:groups`                                       | Read group role assignments.                                                                                                                                                                          |
+|    `delete:groups`                                           | Delete groups.                                                                                                                                                                                        |
+| `admin:services`                                                            | Create, read, update, delete services, not including services defined from config files.                                                                                                              |
+|    `list:services`                                           | List services, including at least their names.                                                                                                                                                        |
+|       `read:services:name`                    | Read service names.                                                                                                                                                                                   |
+|    `read:services`                                           | Read service models.                                                                                                                                                                                  |
+|       `read:services:name`                    | Read service names.                                                                                                                                                                                   |
+|    `read:roles:services`                                     | Read service role assignments.                                                                                                                                                                        |
+| `read:hub`                                                                  | Read detailed information about the Hub.                                                                                                                                                              |
+| `access:services`                                                           | Access services via API or browser.                                                                                                                                                                   |
+| `shares`                                                                    | Manage access to shared servers.                                                                                                                                                                      |
+|    `access:servers`                                          | Access user servers via API or browser.                                                                                                                                                               |
+|    `read:shares`                                             | Read information about shared access to servers.                                                                                                                                                      |
+|    `users:shares`                                            | Read and revoke a user's access to shared servers.                                                                                                                                                    |
+|       `read:users:shares`                     | Read servers shared with a user.                                                                                                                                                                      |
+|    `groups:shares`                                           | Read and revoke a group's access to shared servers.                                                                                                                                                   |
+|       `read:groups:shares`                    | Read servers shared with a group.                                                                                                                                                                     |
+| `proxy`                                                                     | Read information about the proxy’s routing table, sync the Hub with the proxy and notify the Hub about a new proxy.                                                                                   |
+| `shutdown`                                                                  | Shutdown the hub.                                                                                                                                                                                     |
+| `read:metrics`                                                              | Read prometheus metrics.                                                                                                                                                                              |

docs/source/rbac/scopes.md

@@ -186,14 +186,14 @@ An **access scope** is used to govern _access_ to a JupyterHub service or a user
 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.
+When you attempt to access a service or server authenticated with JupyterHub, it will begin the [oauth flow](explanation:hub-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)
+[Further explanation of OAuth in JupyterHub](explanation:hub-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.
@@ -229,6 +229,32 @@ access:servers!server
 access:servers!server=username/
 : access to only `username`'s _default_ server.
 
+(granting-scopes)=
+
+### Considerations when allowing users to grant permissions via the `groups` scope
+
+In general, permissions are fixed by role assignments in configuration (or via [Authenticator-managed roles](#authenticator-roles) in JupyterHub 5) and can only be modified by administrators who can modify the Hub configuration.
+
+There is only one scope that allows users to modify permissions of themselves or others at runtime instead of via configuration:
+the `groups` scope, which allows adding and removing users from one or more groups.
+With the `groups` scope, a user can add or remove any users to/from any group.
+With the `groups!group=name` filtered scope, a user can add or remove any users to/from a specific group.
+There are two ways in which adding a user to a group may affect their permissions:
+
+- if the group is assigned one or more roles, adding a user to the group may increase their permissions (this is usually the point!)
+- if the group is the _target_ of a filter on this or another group, such as `access:servers!group=students`, adding a user to the group can grant _other_ users elevated access to that user's resources.
+
+With these in mind, when designing your roles, do not grant users the `groups` scope for any groups which:
+
+- have roles the user should not have authority over, or
+- would grant them access they shouldn't have for _any_ user (e.g. don't grant `teachers` both `access:servers!group=students` and `groups!group=students` which is tantamount to the unrestricted `access:servers` because they control which users the `group=students` filter applies to).
+
+If a group does not have role assignments and the group is not present in any `!group=` filter, there should be no permissions-related consequences for adding users to groups.
+
+:::{note}
+The legacy `admin` property of users, which grants extreme superuser permissions and is generally discouraged in favor of more specific roles and scopes, may be modified only by other users with the `admin` property (e.g. added via `admin_users`).
+:::
+
 (custom-scopes)=
 
 ### Custom scopes

docs/source/rbac/upgrade.md

@@ -11,7 +11,7 @@ No other database records are affected.
 ## Upgrade steps
 
 1. All running **servers must be stopped** before proceeding with the upgrade.
-2. To upgrade the Hub, follow the [Upgrading JupyterHub](upgrading-jupyterhub) instructions.
+2. To upgrade the Hub, follow the [Upgrading JupyterHub](howto:upgrading-jupyterhub) instructions.
    ```{attention}
    We advise against defining any new roles in the `jupyterhub.config.py` file right after the upgrade is completed and JupyterHub restarted for the first time. This preserves the 'current' state of the Hub. You can define and assign new roles on any other following startup.
    ```

docs/source/reference/api/auth.md

@@ -1,33 +1,42 @@
 # Authenticators
 
-## Module: {mod}`jupyterhub.auth`
-
 ```{eval-rst}
-.. automodule:: jupyterhub.auth
+.. module:: jupyterhub.auth
 ```
 
-### {class}`Authenticator`
+## {class}`Authenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: Authenticator
    :members:
 ```
 
-### {class}`LocalAuthenticator`
+## {class}`LocalAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: LocalAuthenticator
    :members:
 ```
 
-### {class}`PAMAuthenticator`
+## {class}`PAMAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: PAMAuthenticator
 ```
 
-### {class}`DummyAuthenticator`
+## {class}`DummyAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: DummyAuthenticator
 ```
+
+```{eval-rst}
+.. module:: jupyterhub.authenticators.shared
+```
+
+## {class}`SharedPasswordAuthenticator`
+
+```{eval-rst}
+.. autoconfigurable:: SharedPasswordAuthenticator
+   :no-inherited-members:
+```

docs/source/reference/api/index.md

@@ -11,7 +11,7 @@
 :Release: {{ version }}
 
 JupyterHub also provides a REST API for administration of the Hub and users.
-The documentation on [Using JupyterHub's REST API](using-jupyterhub-rest-api) provides
+The documentation on [Using JupyterHub's REST API](howto:rest-api) provides
 information on:
 
 - what you can do with the API

docs/source/reference/api/spawner.md

@@ -10,7 +10,7 @@
 
 ```{eval-rst}
 .. autoconfigurable:: Spawner
-   :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
+   :members: options_from_form, user_options, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
 ```
 
 ### {class}`LocalProcessSpawner`

docs/source/reference/authenticators.md

@@ -36,16 +36,56 @@ 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 a global password has been set. Once set, any username will
-still be accepted but the correct password will need to be provided.
+When testing, it may be helpful to use the {class}`~.jupyterhub.auth.DummyAuthenticator`:
+
+```python
+c.JupyterHub.authenticator_class = "dummy"
+# always a good idea to limit to localhost when testing with an insecure config
+c.JupyterHub.ip = "127.0.0.1"
+```
+
+This allows for any username and password to login, and is _wildly_ insecure.
+
+To use, specify
+
+```python
+c.JupyterHub.authenticator_class = "dummy"
+```
 
 :::{versionadded} 5.0
 The DummyAuthenticator's default `allow_all` is True,
 unlike most other Authenticators.
 :::
 
+:::{deprecated} 5.3
+Setting a password on DummyAuthenticator is deprecated.
+Use the new {class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator`
+if you want to set a shared password for users.
+:::
+
+## Shared Password Authenticator
+
+:::{versionadded} 5.3
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` is added and [DummyAuthenticator.password](#DummyAuthenticator.password) is deprecated.
+:::
+
+For short-term deployments like workshops where there is no real user data to protect and you trust users to not abuse the system or each other,
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` can be used.
+
+Set a [user password](#SharedPasswordAuthenticator.user_password) for users to login:
+
+```python
+c.JupyterHub.authenticator_class = "shared-password"
+c.SharedPasswordAuthenticator.user_password = "my-workshop-2042"
+```
+
+You can also grant admin users access by adding them to `admin_users` and setting a separate [admin password](#SharedPasswordAuthenticator.admin_password):
+
+```python
+c.Authenticator.admin_users = {"danger", "eggs"}
+c.SharedPasswordAuthenticator.admin_password = "extra-super-secret-secure-password"
+```
+
 ## Additional Authenticators
 
 Additional authenticators can be found on GitHub
@@ -469,8 +509,19 @@ 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,
-and roles cannot be specified with `load_groups` traitlet.
+groups cannot be specified with `load_groups` traitlet.
+
+:::{warning}
+When `manage_groups` is True,
+managing groups via the API is still permitted via the `admin:groups` scope (starting with 5.3),
+but any time a user logs in their group membership is completely reset via the login process.
+So it only really makes sense to make manual changes via the API that reflect upstream changes which are not automatically propagated, such as group deletion.
+
+:::
+
+:::{versionchanged} 5.3
+Prior to JupyterHub 5.3, all group management via the API was disabled if `Authenticator.manage_groups` is True.
+:::
 
 (authenticator-roles)=
 

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

@@ -82,15 +82,6 @@ Within CERN, there are two noteworthy JupyterHub deployments in operation:
 - Advanced Computing
   - [Palmetto cluster and JupyterHub](https://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html)
 
-### University of Colorado Boulder
-
-- (CU Research Computing) CURC
-
-  - [JupyterHub User Guide](https://curc.readthedocs.io/en/latest/gateways/jupyterhub.html)
-    - Slurm job dispatched on Crestone compute cluster
-    - 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.

docs/source/reference/monitoring.md

@@ -32,3 +32,28 @@ export JUPYTERHUB_METRICS_PREFIX=jupyterhub_prod
 ```
 
 would result in the metric `jupyterhub_prod_active_users`, etc.
+
+(monitoring_bucket_sizes)=
+
+## Customizing bucket sizes
+
+As of JupyterHub 5.3, the following environment variables in the Hub's environment can be overridden to support custom bucket sizes - below are the defaults:
+
+| Variable                                           | Default                                                            |
+| -------------------------------------------------- | ------------------------------------------------------------------ |
+| `JUPYTERHUB_SERVER_SPAWN_DURATION_SECONDS_BUCKETS` | `0.5,1,2.5,5,10,15,30,60,120,180,300,600,inf`                      |
+| `JUPYTERHUB_SERVER_STOP_DURATION_SECONDS_BUCKETS`  | `0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10,inf` |
+
+For example,
+
+```bash
+export JUPYTERHUB_SERVER_SPAWN_DURATION_SECONDS_BUCKETS="1,2,4,6,12,30,60,120,inf"
+```
+
+## Configuring metrics
+
+```{eval-rst}
+.. currentmodule:: jupyterhub.metrics
+
+.. autoconfigurable:: PeriodicMetricsCollector
+```

docs/source/reference/services.md

@@ -1,4 +1,4 @@
-(services)=
+(services-reference)=
 
 # Services
 
@@ -213,7 +213,7 @@ c.JupyterHub.load_roles = [
 ]
 ```
 
-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 service has a configured URL or explicit `oauth_client_id` or `oauth_redirect_uri`, it can operate as an [OAuth client](explanation:hub-oauth).
 When a user visits an oauth-authenticated service,
 completion of authentication results in issuing an oauth token.
 

docs/source/reference/sharing.md

@@ -264,7 +264,7 @@ Share codes are much like shares, except:
 To create a share code:
 
 ```{parsed-literal}
-[POST /api/share-code/:username/:servername](rest-api-post-share-code)
+[POST /api/share-codes/:username/:servername](rest-api-post-share-code)
 ```
 
 where the body should include the scopes to be granted and expiration.
@@ -286,6 +286,7 @@ The response contains the code itself:
 {
   "code": "abc1234....",
   "accept_url": "/hub/accept-share?code=abc1234",
+  "full_accept_url": "https://hub.example.org/hub/accept-share?code=abc1234",
   "id": "sc_1234",
   "scopes": [...],
   ...

docs/source/reference/spawners.md

@@ -2,7 +2,7 @@
 
 # Spawners
 
-A [Spawner][] starts each single-user notebook server.
+A [Spawner](#Spawner) starts each single-user notebook server.
 The Spawner represents an abstract interface to a process,
 and a custom Spawner needs to be able to take three actions:
 
@@ -37,7 +37,7 @@ Some examples include:
 
 ### Spawner.start
 
-`Spawner.start` should start a single-user server for a single user.
+[](#Spawner.start) should start a single-user server for a single user.
 Information about the user can be retrieved from `self.user`,
 an object encapsulating the user's name, authentication, and server info.
 
@@ -68,11 +68,11 @@ async def start(self):
 When `Spawner.start` returns, the single-user server process should actually be running,
 not just requested. JupyterHub can handle `Spawner.start` being very slow
 (such as PBS-style batch queues, or instantiating whole AWS instances)
-via relaxing the `Spawner.start_timeout` config value.
+via relaxing the [](#Spawner.start_timeout) config value.
 
 #### Note on IPs and ports
 
-`Spawner.ip` and `Spawner.port` attributes set the _bind_ URL,
+[](#Spawner.ip) and [](#Spawner.port) attributes set the _bind_ URL,
 which the single-user server should listen on
 (passed to the single-user process via the `JUPYTERHUB_SERVICE_URL` environment variable).
 The _return_ value is the IP and port (or full URL) the Hub should _connect to_.
@@ -124,7 +124,7 @@ If both attributes are not present, the Exception will be shown to the user as u
 
 ### Spawner.poll
 
-`Spawner.poll` checks if the spawner is still running.
+[](#Spawner.poll) checks if the spawner is still running.
 It should return `None` if it is still running,
 and an integer exit status, otherwise.
 
@@ -133,7 +133,7 @@ to check if the local process is still running. On Windows, it uses `psutil.pid_
 
 ### Spawner.stop
 
-`Spawner.stop` should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
+[](#Spawner.stop) should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
 
 ## Spawner state
 
@@ -166,17 +166,18 @@ def clear_state(self):
     self.pid = 0
 ```
 
+(spawner_user_options)=
+
 ## Spawner options form
 
-(new in 0.4)
-
 Some deployments may want to offer options to users to influence how their servers are started.
-This may include cluster-based deployments, where users specify what resources should be available,
-or docker-based deployments where users can select from a list of base images.
+This may include cluster-based deployments, where users specify what memory or cpu resources should be available,
+or container-based deployments where users can select from a list of base images,
+or more complex configurations where users select a "profile" representing a bundle of settings to be applied together.
 
-This feature is enabled by setting `Spawner.options_form`, which is an HTML form snippet
+This feature is enabled by setting [](#Spawner.options_form), which is an HTML form snippet
 inserted unmodified into the spawn form.
-If the `Spawner.options_form` is defined, when a user tries to start their server, they will be directed to a form page, like this:
+If the `Spawner.options_form` is defined, when a user tries to start their server they will be directed to a form page, like this:
 
 ![spawn-form](/images/spawn-form.png)
 
@@ -186,28 +187,40 @@ See [this example](https://github.com/jupyterhub/jupyterhub/blob/HEAD/examples/s
 
 ### `Spawner.options_from_form`
 
-Options from this form will always be a dictionary of lists of strings, e.g.:
+Inputs from an HTML form always arrive as a dictionary of lists of strings, e.g.:
 
 ```python
-{
+formdata = {
   'integer': ['5'],
+  'checkbox': ['on'],
   'text': ['some text'],
   'select': ['a', 'b'],
 }
 ```
 
-When `formdata` arrives, it is passed through `Spawner.options_from_form(formdata)`,
-which is a method to turn the form data into the correct structure.
-This method must return a dictionary, and is meant to interpret the lists-of-strings into the correct types. For example, the `options_from_form` for the above form would look like:
+When `formdata` arrives, it is passed through [](#Spawner.options_from_form):
 
 ```python
-def options_from_form(self, formdata):
+spawner.user_options = spawner.options_from_form(formdata, spawner=spawner)
+```
+
+to create `spawner.user_options`.
+
+[](#Spawner.options_from_form) is a configurable function to turn the HTTP form data into the correct structure for [](#Spawner.user_options).
+`options_from_form` must return a dictionary, _may_ be async, and is meant to interpret the lists-of-strings a web form produces into the correct types.
+For example, the `options_from_form` for the above form might look like:
+
+```python
+def options_from_form(formdata, spawner=None):
     options = {}
     options['integer'] = int(formdata['integer'][0]) # single integer value
+    options['checkbox'] = formdata['checkbox'] == ['on']
     options['text'] = formdata['text'][0] # single string value
     options['select'] = formdata['select'] # list already correct
     options['notinform'] = 'extra info' # not in the form at all
     return options
+
+c.Spawner.options_from_form = options_from_form
 ```
 
 which would return:
@@ -215,15 +228,115 @@ which would return:
 ```python
 {
   'integer': 5,
+  'checkbox': True,
   'text': 'some text',
   'select': ['a', 'b'],
   'notinform': 'extra info',
 }
 ```
 
-When `Spawner.start` is called, this dictionary is accessible as `self.user_options`.
+### Applying user options
 
-[spawner]: https://github.com/jupyterhub/jupyterhub/blob/HEAD/jupyterhub/spawner.py
+The base Spawner class doesn't do anything with `user_options`, that is also up to your deployment and/or chosen Spawner.
+This is because the users can specify arbitrary option dictionary by using the API,
+so it is part of your Spawner and/or deployment configuration to expose the options you trust your users to set.
+
+[](#Spawner.apply_user_options) is the hook for taking `user_options` and applying whatever configuration it may represent.
+It is critical that `apply_user_options` validates all input, since these are provided by the user.
+
+```python
+def apply_user_options(spawner, user_options):
+    if "image" in user_options and isinstance(user_options["image"], str):
+        spawner.image = user_options["image"]
+
+c.Spawner.apply_user_options = apply_user_options
+```
+
+:::{versionadded} 5.3
+JupyterHub 5.3 introduces [](#Spawner.apply_user_options) configuration.
+Previously, [](#Spawner.user_options) could only be consumed during [](#Spawner.start),
+at which point `user_options` is available to the Spawner instance as `self.user_options`.
+This approach requires subclassing, so it was not possible to apply new `user_options` via configuration.
+In JupyterHub 5.3, it is possible to fully expose user options,
+and for some simple cases, fully with _declarative_ configuration.
+:::
+
+### Declarative configuration for user options
+
+While [](#Spawner.options_from_form) and [](#Spawner.apply_user_options) are callables by nature,
+some simple cases can be represented by declarative configuration,
+which is most conveniently expressed in e.g. the yaml of the JupyterHub helm chart.
+The cases currently handled are:
+
+```python
+c.Spawner.options_form = """
+<input name="image_input" type="text" value="quay.io/jupyterhub/singleuser:5.2"/>
+<input name="debug_checkbox" type="checkbox" />
+"""
+c.Spawner.options_from_form = "simple"
+c.Spawner.apply_user_options = {"image_input": "image", "debug_checkbox": "debug"}
+```
+
+`options_from_form = "simple"` uses a built-in method to do the very simplest interpretation of an html form,
+casting the lists of strings to single strings by getting the first item when there is only one.
+The only extra processing it performs is casting the checkbox value of `on` to True.
+
+So it turns this formdata:
+
+```python
+{
+  "image_input": ["my_image"],
+  "debug_checkbox": ["on"],
+}
+```
+
+into this `user_options`
+
+```python
+{
+  "image_input": "my_image",
+  "debug_checkbox": True
+}
+```
+
+When `apply_user_options` is a dictionary, any input in `user_options` is looked up in this dictionary,
+and assigned to the corresponding Spawner attribute.
+Strings are passed through traitlets' `from_string` logic (what is used for setting values on the command-line),
+which means you can set numbers and things this way as well,
+even though `options_from_form` leaves these as strings.
+
+So in the above configuration, we have exposed `Spawner.debug` and `Spawner.image` without needing to write any functions.
+In the JupyterHub helm chart YAML, this would look like:
+
+```yaml
+hub:
+  config:
+    KubeSpawner:
+      options_form: |
+        <input name="image_input" type="text" value="quay.io/jupyterhub/singleuser:5.2"/>
+        <input name="debug_checkbox" type="checkbox" />
+      options_from_form: simple
+      apply_user_options:
+        image_input: image
+        debug_checkbox: debug
+```
+
+### Setting `user_options` directly via the REST API
+
+In addition to going through the options form, `user_options` may be set directly, via the REST API.
+The body of a POST request to spawn a server may be a JSON dictionary,
+which will be used to set `user_options` directly.
+When used this way, neither `options_form` nor `options_from_form` are involved,
+`user_options` is set directly, and only `apply_user_options` is called.
+
+```
+POST /hub/api/users/servers/:name
+{
+  "option": 5,
+  "bool": True,
+  "string": "value"
+}
+```
 
 ## Writing a custom spawner
 

docs/source/reference/urls.md

@@ -4,7 +4,7 @@
 
 This document describes how JupyterHub routes requests.
 
-This does not include the [REST API](using-jupyterhub-rest-api) URLs.
+This does not include the [REST API](howto:rest-api) URLs.
 
 In general, all URLs can be prefixed with `c.JupyterHub.base_url` to
 run the whole JupyterHub application on a prefix.
@@ -183,13 +183,6 @@ will send user `hortense` to `/user/hortense/notebooks/Index.ipynb`
 This will not work in general,
 unless you grant those users access to your server.
 
-**Contributions welcome:** The JupyterLab "shareable link" should share this link
-when run with JupyterHub, but it does not.
-See [jupyterlab-hub](https://github.com/jupyterhub/jupyterlab-hub)
-where this should probably be done and
-[this issue in JupyterLab](https://github.com/jupyterlab/jupyterlab/issues/5388)
-that is intended to make it possible.
-
 ## Spawning
 
 ### `/hub/spawn[/:username[/:servername]]`
@@ -240,7 +233,7 @@ and the page will show a link back to `/hub/spawn/...`.
 
 On this page, users can manage their JupyterHub API tokens.
 They can revoke access and request new tokens for writing scripts
-against the [JupyterHub REST API](using-jupyterhub-rest-api).
+against the [JupyterHub REST API](howto:rest-api).
 
 ## `/hub/admin`
 

docs/source/tutorial/collaboration-users.md

@@ -78,7 +78,7 @@ c.JupyterHub.load_roles = []
 c.JupyterHub.load_groups = {
     # collaborative accounts get added to this group
     # so it's easy to see which accounts are collaboration accounts
-    "collaborative": [],
+    "collaborative": {"users": []},
 }
 ```
 
@@ -102,12 +102,12 @@ for project_name, project in project_config["projects"].items():
     members = project.get("members", [])
     print(f"Adding project {project_name} with members {members}")
     # add them to a group for the project
-    c.JupyterHub.load_groups[project_name] = members
+    c.JupyterHub.load_groups[project_name] = {"users": members}
     # define a new user for the collaboration
     collab_user = f"{project_name}-collab"
     # add the collab user to the 'collaborative' group
     # so we can identify it as a collab account
-    c.JupyterHub.load_groups["collaborative"].append(collab_user)
+    c.JupyterHub.load_groups["collaborative"]["users"].append(collab_user)
 
     # finally, grant members of the project collaboration group
     # access to the collab user's server,

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

@@ -93,6 +93,25 @@ A set of initial admin users, `admin_users` can be configured as follows:
 c.Authenticator.admin_users = {'mal', 'zoe'}
 ```
 
+:::{warning}
+`admin_users` config can only be used to _grant_ admin permissions.
+Removing users from this set **does not** remove their admin permissions,
+which must be done via the admin page or API.
+
+Role assignments via `load_roles` are the only way to _revoke_ past permissions from configuration:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "admin",
+        "users": ["admin1", "..."],
+    }
+]
+```
+
+or, better yet, [specify your own roles](define-role-target) with only the permissions your admins actually need.
+:::
+
 Users in the admin set are automatically added to the user `allowed_users` set,
 if they are not already present.
 

docs/source/tutorial/getting-started/config-basics.md

@@ -99,4 +99,4 @@ maintenance, re-configuration, etc.), then user connections are not
 interrupted. For simplicity, by default the hub starts the proxy
 automatically, so if the hub restarts, the proxy restarts, and user
 connections are interrupted. It is easy to run the proxy separately,
-for information see [the separate proxy page](separate-proxy).
+for information see [the separate proxy page](howto:separate-proxy).

docs/source/tutorial/getting-started/security-basics.md

@@ -43,7 +43,7 @@ is important that these files be put in a secure location on your server, where
 they are not readable by regular users.
 
 If you are using a **chain certificate**, see also chained certificate for SSL
-in the JupyterHub [Troubleshooting FAQ](troubleshooting).
+in the JupyterHub [Troubleshooting FAQ](faq:troubleshooting).
 
 ### Using letsencrypt
 
@@ -68,7 +68,7 @@ c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/example.com/fullchain.pem'
 ### If SSL termination happens outside of the Hub
 
 In certain cases, for example, if the hub is running behind a reverse proxy, and
-[SSL termination is being provided by NGINX](https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/),
+[SSL termination is being provided by NGINX](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/),
 it is reasonable to run the hub without SSL.
 
 To achieve this, remove `c.JupyterHub.ssl_key` and `c.JupyterHub.ssl_cert`

docs/source/tutorial/getting-started/services-basics.md

@@ -1,3 +1,5 @@
+(tutorial:services)=
+
 # External services
 
 When working with JupyterHub, a **Service** is defined as a process

docs/source/tutorial/quickstart.md

@@ -90,6 +90,6 @@ To **allow multiple users to sign in** to the Hub server, you must start
 sudo jupyterhub
 ```
 
-The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+[](howto:config:no-sudo)
 describes how to run the server as a _less privileged user_. This requires
 additional configuration of the system.

docs/source/tutorial/server-api.md

@@ -1,7 +1,7 @@
 # Starting servers with the JupyterHub API
 
 Sometimes, when working with applications such as [BinderHub](https://binderhub.readthedocs.io), it may be necessary to launch Jupyter-based services on behalf of your users.
-Doing so can be achieved through JupyterHub's [REST API](using-jupyterhub-rest-api), which allows one to launch and manage servers on behalf of users through API calls instead of the JupyterHub UI.
+Doing so can be achieved through JupyterHub's [REST API](howto:rest-api), which allows one to launch and manage servers on behalf of users through API calls instead of the JupyterHub UI.
 This way, you can take advantage of other user/launch/lifecycle patterns that are not natively supported by the JupyterHub UI, all without the need to develop the server management features of JupyterHub Spawners and/or Authenticators.
 
 This tutorial goes through working with the JupyterHub API to manage servers for users.

docs/source/tutorial/sharing.md

@@ -159,11 +159,14 @@ which will have a JSON response:
   'last_exchanged_at': None,
   'code': 'U-eYLFT1lGstEqfMHpAIvTZ1MRjZ1Y1a-loGQ0K86to',
   'accept_url': '/hub/accept-share?code=U-eYLFT1lGstEqfMHpAIvTZ1MRjZ1Y1a-loGQ0K86to',
+  'full_accept_url': 'https://hub.example.org/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.
+If `public_url` configuration is defined, `full_accept_url` will be the full URL including the host.
+Otherwise, it will be null.
 
 Share codes are guaranteed to be url-safe, so no encoding is required.
 

jsx/.eslintrc.json

@@ -1,44 +0,0 @@
-{
-  "extends": ["plugin:react/recommended"],
-  "parserOptions": {
-    "ecmaVersion": 2018,
-    "sourceType": "module",
-    "ecmaFeatures": {
-      "jsx": true
-    }
-  },
-  "settings": {
-    "react": {
-      "version": "detect"
-    }
-  },
-  "plugins": ["eslint-plugin-react", "prettier", "unused-imports"],
-  "env": {
-    "es6": true,
-    "browser": true
-  },
-  "rules": {
-    "semi": "off",
-    "quotes": "off",
-    "prettier/prettier": "warn",
-    "no-unused-vars": "off",
-    "unused-imports/no-unused-imports": "error",
-    "unused-imports/no-unused-vars": [
-      "warn",
-      {
-        "vars": "all",
-        "varsIgnorePattern": "^regeneratorRuntime|^_",
-        "args": "after-used",
-        "argsIgnorePattern": "^_"
-      }
-    ]
-  },
-  "overrides": [
-    {
-      "files": ["**/*.test.js", "**/*.test.jsx"],
-      "env": {
-        "jest": true
-      }
-    }
-  ]
-}

jsx/eslint.config.mjs

@@ -0,0 +1,77 @@
+import { defineConfig } from "eslint/config";
+import react from "eslint-plugin-react";
+import prettier from "eslint-plugin-prettier";
+import unusedImports from "eslint-plugin-unused-imports";
+import globals from "globals";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default defineConfig([
+  {
+    extends: compat.extends("plugin:react/recommended"),
+
+    plugins: {
+      react,
+      prettier,
+      "unused-imports": unusedImports,
+    },
+
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+
+      ecmaVersion: 2018,
+      sourceType: "module",
+
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+
+    rules: {
+      semi: "off",
+      quotes: "off",
+      "prettier/prettier": "warn",
+      "no-unused-vars": "off",
+      "unused-imports/no-unused-imports": "error",
+
+      "unused-imports/no-unused-vars": [
+        "warn",
+        {
+          vars: "all",
+          varsIgnorePattern: "^regeneratorRuntime|^_",
+          args: "after-used",
+          argsIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
+  {
+    files: ["**/*.test.js", "**/*.test.jsx"],
+
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+  },
+]);

jsx/package.json

@@ -22,51 +22,58 @@
     "plugins": []
   },
   "jest": {
+    "fakeTimers": {
+      "enableGlobally": true
+    },
     "moduleNameMapper": {
       "\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$": "<rootDir>/__mocks__/fileMock.js",
       "\\.(css|less)$": "identity-obj-proxy"
     },
+    "setupFiles": [
+      "./testing/setup.jest.js"
+    ],
     "testEnvironment": "jsdom"
   },
   "dependencies": {
-    "bootstrap": "^5.2.3",
+    "bootstrap": "^5.3.5",
     "history": "^5.3.0",
     "lodash": "^4.17.21",
     "prop-types": "^15.8.1",
-    "react": "^17.0.2",
-    "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": "^6.22.2",
-    "recompose": "npm:react-recompose@^0.33.0",
-    "redux": "^4.2.1",
-    "regenerator-runtime": "^0.13.11"
+    "react": "^19.1.0",
+    "react-bootstrap": "^2.10.9",
+    "react-dom": "^19.1.0",
+    "react-icons": "^5.5.0",
+    "react-redux": "^9.2.0",
+    "react-router": "^7.5.0",
+    "redux": "^5.0.1",
+    "regenerator-runtime": "^0.14.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.21.4",
-    "@babel/preset-env": "^7.21.4",
-    "@babel/preset-react": "^7.18.6",
-    "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^12.1.5",
-    "@testing-library/user-event": "^13.5.0",
-    "@webpack-cli/serve": "^2.0.1",
-    "babel-jest": "^29.5.0",
-    "babel-loader": "^9.1.2",
-    "css-loader": "^6.7.3",
-    "eslint": "^8.38.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.32.2",
-    "eslint-plugin-unused-imports": "^2.0.0",
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-react": "^7.26.3",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.24.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@webpack-cli/serve": "^3.0.1",
+    "babel-jest": "^29.7.0",
+    "babel-loader": "^10.0.0",
+    "css-loader": "^7.1.2",
+    "eslint": "^9.24.0",
+    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "file-loader": "^6.2.0",
+    "globals": "^16.0.0",
     "identity-obj-proxy": "^3.0.0",
-    "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
-    "prettier": "^2.8.7",
-    "style-loader": "^3.3.2",
-    "webpack": "^5.79.0",
-    "webpack-cli": "^5.0.1",
-    "webpack-dev-server": "^4.13.3"
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.5.3",
+    "style-loader": "^4.0.0",
+    "webpack": "^5.99.5",
+    "webpack-cli": "^6.0.1",
+    "webpack-dev-server": "^5.2.1"
   }
 }

jsx/src/App.jsx

@@ -1,11 +1,11 @@
 import React from "react";
-import ReactDOM from "react-dom";
+import { createRoot } from "react-dom/client";
 import { Provider } from "react-redux";
 import { createStore } from "redux";
-import { compose } from "recompose";
+import { compose } from "./util/_recompose";
 import { initialState, reducers } from "./Store";
 import withAPI from "./util/withAPI";
-import { HashRouter, Routes, Route } from "react-router-dom";
+import { HashRouter, Routes, Route } from "react-router";
 
 import ServerDashboard from "./components/ServerDashboard/ServerDashboard";
 import Groups from "./components/Groups/Groups";
@@ -40,4 +40,5 @@ const App = () => {
   );
 };
 
-ReactDOM.render(<App />, document.getElementById("react-admin-hook"));
+const root = createRoot(document.getElementById("react-admin-hook"));
+root.render(<App />);

jsx/src/components/AddUser/AddUser.jsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import { Button, Col } from "react-bootstrap";
 import PropTypes from "prop-types";
 import ErrorAlert from "../../util/error";

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

@@ -1,11 +1,9 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
 import { Provider, useDispatch, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -46,6 +44,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useDispatch.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -67,7 +66,7 @@ test("Removes users when they fail Regex", async () => {
 
   fireEvent.blur(textarea, { target: { value: "foo \n bar\na@b.co\n  \n\n" } });
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenCalledWith(["foo", "bar", "a@b.co"], false);
@@ -79,15 +78,15 @@ test("Correctly submits admin", async () => {
   await act(async () => {
     render(addUserJsx(callbackSpy));
   });
-
   let textarea = screen.getByTestId("user-textarea");
   let submit = screen.getByTestId("submit");
   let check = screen.getByTestId("check");
 
-  userEvent.click(check);
-  fireEvent.blur(textarea, { target: { value: "foo" } });
+  await fireEvent.blur(textarea, { target: { value: "foo" } });
+  await fireEvent.click(check);
+  await fireEvent.click(submit);
   await act(async () => {
-    fireEvent.click(submit);
+    await jest.runAllTimers();
   });
 
   expect(callbackSpy).toHaveBeenCalledWith(["foo"], true);
@@ -103,7 +102,7 @@ test("Shows a UI error dialogue when user creation fails", async () => {
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to create user.");
@@ -122,7 +121,7 @@ test("Shows a more specific UI error dialogue when user creation returns an impr
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText(

jsx/src/components/CreateGroup/CreateGroup.jsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import { Button, Card } from "react-bootstrap";
 import PropTypes from "prop-types";
 import { MainContainer } from "../../util/layout";

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

@@ -1,11 +1,10 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { Provider, useDispatch, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 import CreateGroup from "./CreateGroup";
@@ -45,6 +44,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useDispatch.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -63,9 +63,10 @@ test("Calls createGroup on submit", async () => {
 
   let input = screen.getByTestId("group-input");
   let submit = screen.getByTestId("submit");
+  const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
 
-  userEvent.type(input, "groupname");
-  await act(async () => fireEvent.click(submit));
+  await user.type(input, "groupname");
+  await act(async () => await fireEvent.click(submit));
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, "groupname");
 });
@@ -80,7 +81,7 @@ test("Shows a UI error dialogue when group creation fails", async () => {
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to create group.");
@@ -99,7 +100,7 @@ test("Shows a more specific UI error dialogue when user creation returns an impr
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText(

jsx/src/components/EditUser/EditUser.jsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
 import PropTypes from "prop-types";
-import { Link, useLocation, useNavigate } from "react-router-dom";
+import { Link, useLocation, useNavigate } from "react-router";
 import { Button, Card } from "react-bootstrap";
 import { MainContainer } from "../../util/layout";
 

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

@@ -1,10 +1,9 @@
-import React from "react";
+import React, { act } 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 { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,8 +15,8 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useLocation: jest.fn().mockImplementation(() => {
     return { state: { username: "foo", has_admin: false } };
   }),
@@ -58,6 +57,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useDispatch.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -80,7 +80,7 @@ test("Calls the delete user function when the button is pressed", async () => {
   let deleteUser = screen.getByTestId("delete-user");
 
   await act(async () => {
-    fireEvent.click(deleteUser);
+    await fireEvent.click(deleteUser);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -95,7 +95,7 @@ test("Submits the edits when the button is pressed", async () => {
 
   let submit = screen.getByTestId("submit");
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -113,7 +113,7 @@ test("Shows a UI error dialogue when user edit fails", async () => {
 
   fireEvent.blur(usernameInput, { target: { value: "whatever" } });
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit user.");
@@ -134,7 +134,7 @@ test("Shows a UI error dialogue when user edit returns an improper status code",
 
   fireEvent.blur(usernameInput, { target: { value: "whatever" } });
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit user.");

jsx/src/components/GroupEdit/GroupEdit.jsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useState } from "react";
 import { useSelector, useDispatch } from "react-redux";
-import { Link, useNavigate, useLocation } from "react-router-dom";
+import { Link, useNavigate, useLocation } from "react-router";
 import PropTypes from "prop-types";
 import { Button, Card } from "react-bootstrap";
 import GroupSelect from "../GroupSelect/GroupSelect";
@@ -42,6 +42,10 @@ const GroupEdit = (props) => {
     }
   }, [location]);
 
+  useEffect(() => {
+    setSelected(group_data.users);
+  }, []);
+
   const { group_data } = location.state || {};
   if (!group_data) return <div></div>;
   const [propobject, setProp] = useState(group_data.properties);
@@ -175,6 +179,7 @@ GroupEdit.propTypes = {
   removeFromGroup: PropTypes.func,
   deleteGroup: PropTypes.func,
   updateGroups: PropTypes.func,
+  updateProp: PropTypes.func,
   validateUser: PropTypes.func,
 };
 

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

@@ -1,11 +1,10 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,8 +15,8 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useLocation: jest.fn().mockImplementation(() => {
     return { state: { group_data: { users: ["foo"], name: "group" } } };
   }),
@@ -58,6 +57,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useSelector.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -80,13 +80,15 @@ test("Adds user from input to user selectables on button click", async () => {
   let input = screen.getByTestId("username-input");
   let validateUser = screen.getByTestId("validate-user");
   let submit = screen.getByTestId("submit");
-
-  userEvent.type(input, "bar");
-  fireEvent.click(validateUser);
-  await act(async () => okPacket);
+  const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+  await user.type(input, "bar");
+  await user.click(validateUser);
+  await act(async () => {
+    await jest.runAllTimers();
+  });
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, ["bar"], "group");
@@ -100,7 +102,7 @@ test("Removes a user recently added from input from the selectables list", async
   });
 
   let selectedUser = screen.getByText("foo");
-  fireEvent.click(selectedUser);
+  await await fireEvent.click(selectedUser);
 
   let unselectedUser = screen.getByText("foo");
 
@@ -117,14 +119,14 @@ test("Grays out a user, already in the group, when unselected and calls deleteUs
   let submit = screen.getByTestId("submit");
 
   let groupUser = screen.getByText("foo");
-  fireEvent.click(groupUser);
+  await fireEvent.click(groupUser);
 
   let unselectedUser = screen.getByText("foo");
   expect(unselectedUser.className).toBe("item unselected");
 
   // test deleteUser call
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, ["foo"], "group");
@@ -140,7 +142,7 @@ test("Calls deleteGroup on button click", async () => {
   let deleteGroup = screen.getByTestId("delete-group");
 
   await act(async () => {
-    fireEvent.click(deleteGroup);
+    await fireEvent.click(deleteGroup);
   });
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, "group");
@@ -154,12 +156,12 @@ test("Shows a UI error dialogue when group edit fails", async () => {
   });
 
   let groupUser = screen.getByText("foo");
-  fireEvent.click(groupUser);
+  await fireEvent.click(groupUser);
 
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit group.");
@@ -176,12 +178,12 @@ test("Shows a UI error dialogue when group edit returns an improper status code"
   });
 
   let groupUser = screen.getByText("foo");
-  fireEvent.click(groupUser);
+  await fireEvent.click(groupUser);
 
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit group.");
@@ -200,7 +202,7 @@ test("Shows a UI error dialogue when group delete fails", async () => {
   let deleteGroup = screen.getByTestId("delete-group");
 
   await act(async () => {
-    fireEvent.click(deleteGroup);
+    await fireEvent.click(deleteGroup);
   });
 
   let errorDialog = screen.getByText("Failed to delete group.");
@@ -219,7 +221,7 @@ test("Shows a UI error dialogue when group delete returns an improper status cod
   let deleteGroup = screen.getByTestId("delete-group");
 
   await act(async () => {
-    fireEvent.click(deleteGroup);
+    await fireEvent.click(deleteGroup);
   });
 
   let errorDialog = screen.getByText("Failed to delete group.");

jsx/src/components/Groups/Groups.jsx

@@ -3,7 +3,7 @@ import { useSelector, useDispatch } from "react-redux";
 import PropTypes from "prop-types";
 
 import { Button, Card } from "react-bootstrap";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import { usePaginationParams } from "../../util/paginationParams";
 import PaginationFooter from "../PaginationFooter/PaginationFooter";
 import { MainContainer } from "../../util/layout";
@@ -14,15 +14,13 @@ const Groups = (props) => {
   const dispatch = useDispatch();
   const navigate = useNavigate();
 
-  const { setOffset, offset, handleLimit, limit, setPagination } =
-    usePaginationParams();
+  const { offset, setOffset, handleLimit, limit } = usePaginationParams();
 
   const total = groups_page ? groups_page.total : undefined;
 
   const { updateGroups } = props;
 
   const dispatchPageUpdate = (data, page) => {
-    setPagination(page);
     dispatch({
       type: "GROUPS_PAGE",
       value: {
@@ -32,11 +30,40 @@ const Groups = (props) => {
     });
   };
 
+  // single callback to reload the page
+  // uses current state
+  const loadPageData = (params) => {
+    const abortHandle = { cancelled: false };
+    (async () => {
+      try {
+        const data = await updateGroups(offset, limit);
+        // cancelled (e.g. param changed while waiting for response)
+        if (abortHandle.cancelled) return;
+        if (
+          data._pagination.offset &&
+          data._pagination.total <= data._pagination.offset
+        ) {
+          // reset offset if we're out of bounds,
+          // then load again
+          setOffset(0);
+          return;
+        }
+        // actually update page data
+        dispatchPageUpdate(data.items, data._pagination);
+      } catch (e) {
+        console.error("Failed to update group list.", e);
+      }
+    })();
+    // returns cancellation callback
+    return () => {
+      // cancel stale load
+      abortHandle.cancelled = true;
+    };
+  };
+
   useEffect(() => {
-    updateGroups(offset, limit).then((data) =>
-      dispatchPageUpdate(data.items, data._pagination),
-    );
-  }, [offset, limit]);
+    return loadPageData();
+  }, [limit, offset]);
 
   if (!groups_data || !groups_page) {
     return <div data-testid="no-show"></div>;
@@ -68,12 +95,16 @@ const Groups = (props) => {
             )}
           </ul>
           <PaginationFooter
-            offset={offset}
+            offset={groups_page.offset}
             limit={limit}
             visible={groups_data.length}
             total={total}
-            next={() => setOffset(offset + limit)}
-            prev={() => setOffset(offset - limit)}
+            next={() => setOffset(groups_page.offset + limit)}
+            prev={() =>
+              setOffset(
+                limit > groups_page.offset ? 0 : groups_page.offset - limit,
+              )
+            }
             handleLimit={handleLimit}
           />
         </Card.Body>

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

@@ -1,10 +1,9 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter, useSearchParams } from "react-router-dom";
+import { HashRouter, useSearchParams } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,8 +15,8 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useSearchParams: jest.fn(),
 }));
 
@@ -58,23 +57,45 @@ var mockAppState = () =>
     },
   });
 
+var mockUpdateGroups = () => {
+  const state = mockAppState();
+  return jest.fn().mockImplementation((offset, limit) =>
+    Promise.resolve({
+      items: state.groups_data.slice(0, limit),
+      _pagination: {
+        offset: offset,
+        limit: limit || 2,
+        total: state.groups_page.total,
+      },
+    }),
+  );
+};
+
+let searchParams = new URLSearchParams();
+
 beforeEach(() => {
   useSelector.mockImplementation((callback) => {
     return callback(mockAppState());
   });
-  useSearchParams.mockImplementation(() => {
-    return [new URLSearchParams(), jest.fn()];
-  });
+  searchParams = new URLSearchParams();
+  searchParams.set("limit", "2");
+  useSearchParams.mockImplementation(() => [
+    searchParams,
+    (callback) => {
+      searchParams = callback(searchParams);
+    },
+  ]);
 });
 
 afterEach(() => {
   useSelector.mockClear();
   mockReducers.mockClear();
   useSearchParams.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
-  let callbackSpy = mockAsync();
+  let callbackSpy = mockUpdateGroups();
 
   await act(async () => {
     render(groupsJsx(callbackSpy));
@@ -84,7 +105,7 @@ test("Renders", async () => {
 });
 
 test("Renders groups_data prop into links", async () => {
-  let callbackSpy = mockAsync();
+  let callbackSpy = mockUpdateGroups();
 
   await act(async () => {
     render(groupsJsx(callbackSpy));
@@ -102,7 +123,7 @@ test("Renders nothing if required data is not available", async () => {
     return callback({});
   });
 
-  let callbackSpy = mockAsync();
+  let callbackSpy = mockUpdateGroups();
 
   await act(async () => {
     render(groupsJsx(callbackSpy));
@@ -112,37 +133,25 @@ test("Renders nothing if required data is not available", async () => {
   expect(noShow).toBeVisible();
 });
 
-test("Interacting with PaginationFooter causes state update and refresh via useEffect call", async () => {
-  let upgradeGroupsSpy = mockAsync();
-  let setSearchParamsSpy = mockAsync();
-  let searchParams = new URLSearchParams({ limit: "2" });
-  useSearchParams.mockImplementation(() => [
-    searchParams,
-    (callback) => {
-      searchParams = callback(searchParams);
-      setSearchParamsSpy(searchParams.toString());
-    },
-  ]);
-  let _, setSearchParams;
+test("Interacting with PaginationFooter causes page refresh", async () => {
+  let updateGroupsSpy = mockUpdateGroups();
   await act(async () => {
-    render(groupsJsx(upgradeGroupsSpy));
-    [_, setSearchParams] = useSearchParams();
+    render(groupsJsx(updateGroupsSpy));
   });
 
-  expect(upgradeGroupsSpy).toBeCalledWith(0, 2);
+  expect(updateGroupsSpy).toBeCalledWith(0, 2);
 
   var lastState =
     mockReducers.mock.results[mockReducers.mock.results.length - 1].value;
   expect(lastState.groups_page.offset).toEqual(0);
   expect(lastState.groups_page.limit).toEqual(2);
+  expect(searchParams.get("offset")).toEqual(null);
 
   let next = screen.getByTestId("paginate-next");
   await act(async () => {
-    fireEvent.click(next);
+    await fireEvent.click(next);
   });
-  expect(setSearchParamsSpy).toBeCalledWith("limit=2&offset=2");
-
-  // FIXME: mocked useSelector, state seem to prevent updateGroups from being called
-  // making the test environment not representative
-  // expect(callbackSpy).toHaveBeenCalledWith(2, 2);
+  expect(searchParams.get("offset")).toEqual("2");
+  // FIXME: useSelector mocks prevent updateGroups from being called
+  // expect(updateGroupsSpy).toBeCalledWith(2, 2);
 });

jsx/src/components/PaginationFooter/PaginationFooter.jsx

@@ -2,8 +2,6 @@ import React from "react";
 import PropTypes from "prop-types";
 import { Button, FormControl } from "react-bootstrap";
 
-import "./pagination-footer.css";
-
 const PaginationFooter = (props) => {
   const { offset, limit, visible, total, next, prev, handleLimit } = props;
   return (
@@ -13,33 +11,45 @@ const PaginationFooter = (props) => {
         {total ? `of ${total}` : ""}
         <br />
         {offset >= 1 ? (
-          <Button variant="light" size="sm">
-            <span
-              className="active-pagination"
-              data-testid="paginate-prev"
-              onClick={prev}
-            >
-              Previous
-            </span>
+          <Button
+            variant="light"
+            size="sm"
+            onClick={prev}
+            className="me-2"
+            data-testid="paginate-prev"
+          >
+            Previous
           </Button>
         ) : (
-          <Button variant="light" size="sm">
-            <span className="inactive-pagination">Previous</span>
+          <Button
+            variant="light"
+            size="sm"
+            className="me-2"
+            disabled
+            aria-disabled="true"
+          >
+            Previous
           </Button>
         )}
         {offset + visible < total ? (
-          <Button variant="light" size="sm">
-            <span
-              className="active-pagination"
-              data-testid="paginate-next"
-              onClick={next}
-            >
-              Next
-            </span>
+          <Button
+            variant="light"
+            size="sm"
+            className="me-2"
+            onClick={next}
+            data-testid="paginate-next"
+          >
+            Next
           </Button>
         ) : (
-          <Button variant="light" size="sm">
-            <span className="inactive-pagination">Next</span>
+          <Button
+            variant="light"
+            size="sm"
+            className="me-2"
+            disabled
+            aria-disabled="true"
+          >
+            Next
           </Button>
         )}
         <label>

jsx/src/components/PaginationFooter/pagination-footer.css

@@ -1,14 +0,0 @@
-@import url(../../style/root.css);
-
-.pagination-footer * button {
-  margin-right: 10px;
-}
-
-.pagination-footer * .inactive-pagination {
-  color: gray;
-  cursor: not-allowed;
-}
-
-.pagination-footer * button.spaced {
-  color: var(--blue);
-}

jsx/src/components/ServerDashboard/ServerDashboard.jsx

@@ -3,6 +3,7 @@ import { useSelector, useDispatch } from "react-redux";
 import { debounce } from "lodash";
 import PropTypes from "prop-types";
 import ErrorAlert from "../../util/error";
+import { User, Server } from "../../util/jhapiUtil";
 
 import {
   Button,
@@ -16,7 +17,7 @@ import {
 } from "react-bootstrap";
 import ReactObjectTableViewer from "../ReactObjectTableViewer/ReactObjectTableViewer";
 
-import { Link, useSearchParams, useNavigate } from "react-router-dom";
+import { Link, useSearchParams, useNavigate } from "react-router";
 import { FaSort, FaSortUp, FaSortDown } from "react-icons/fa";
 
 import "./server-dashboard.css";
@@ -41,7 +42,7 @@ const ServerDashboard = (props) => {
   let user_data = useSelector((state) => state.user_data);
   const user_page = useSelector((state) => state.user_page);
 
-  const { setOffset, offset, setLimit, handleLimit, limit, setPagination } =
+  const { offset, setOffset, setLimit, handleLimit, limit } =
     usePaginationParams();
 
   const name_filter = searchParams.get("name_filter") || "";
@@ -64,12 +65,6 @@ const ServerDashboard = (props) => {
   } = 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",
@@ -123,26 +118,51 @@ const ServerDashboard = (props) => {
       } 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,
-    });
+  // single callback to reload the page
+  // uses current state
+  const loadPageData = () => {
+    const abortHandle = { cancelled: false };
+    (async () => {
+      try {
+        const data = await updateUsers({
+          offset,
+          limit,
+          name_filter,
+          sort,
+          state: state_filter,
+        });
+        // cancelled (e.g. param changed while waiting for response)
+        if (abortHandle.cancelled) return;
+        if (
+          data._pagination.offset &&
+          data._pagination.total <= data._pagination.offset
+        ) {
+          // reset offset if we're out of bounds,
+          // then load again
+          setOffset(0);
+          return;
+        }
+        // actually update page data
+        dispatchPageUpdate(data.items, data._pagination);
+      } catch (e) {
+        console.error("Failed to update user list.", e);
+        setErrorAlert("Failed to update user list.");
+      }
+    })();
+    // returns cancellation callback
+    return () => {
+      // cancel stale load
+      abortHandle.cancelled = true;
+    };
+  };
 
   useEffect(() => {
-    updateUsersWithParams()
-      .then((data) => dispatchPageUpdate(data.items, data._pagination))
-      .catch((err) => setErrorAlert("Failed to update user list."));
-  }, [offset, limit, name_filter, sort, state_filter]);
+    return loadPageData();
+  }, [limit, name_filter, offset, sort, state_filter]);
 
   if (!user_data || !user_page) {
     return <div data-testid="no-show"></div>;
@@ -172,14 +192,7 @@ const ServerDashboard = (props) => {
           action(user.name, server.name)
             .then((res) => {
               if (res.status < 300) {
-                updateUsersWithParams()
-                  .then((data) => {
-                    dispatchPageUpdate(data.items, data._pagination);
-                  })
-                  .catch(() => {
-                    setIsDisabled(false);
-                    setErrorAlert(`Failed to update users list.`);
-                  });
+                loadPageData();
               } else {
                 setErrorAlert(`Failed to ${name.toLowerCase()}.`);
                 setIsDisabled(false);
@@ -197,6 +210,15 @@ const ServerDashboard = (props) => {
     );
   };
 
+  ServerButton.propTypes = {
+    server: Server,
+    user: User,
+    action: PropTypes.string,
+    name: PropTypes.string,
+    variant: PropTypes.string,
+    extraClass: PropTypes.string,
+  };
+
   const StopServerButton = ({ server, user }) => {
     if (!server.ready) {
       return null;
@@ -210,6 +232,12 @@ const ServerDashboard = (props) => {
       extraClass: "stop-button",
     });
   };
+
+  StopServerButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const DeleteServerButton = ({ server, user }) => {
     if (!server.name) {
       // It's not possible to delete unnamed servers
@@ -228,6 +256,11 @@ const ServerDashboard = (props) => {
     });
   };
 
+  DeleteServerButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const StartServerButton = ({ server, user }) => {
     if (server.ready) {
       return null;
@@ -242,6 +275,11 @@ const ServerDashboard = (props) => {
     });
   };
 
+  StartServerButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const SpawnPageButton = ({ server, user }) => {
     if (server.ready) {
       return null;
@@ -259,6 +297,11 @@ const ServerDashboard = (props) => {
     );
   };
 
+  SpawnPageButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const AccessServerButton = ({ server }) => {
     if (!server.ready) {
       return null;
@@ -271,6 +314,9 @@ const ServerDashboard = (props) => {
       </a>
     );
   };
+  AccessServerButton.propTypes = {
+    server: Server,
+  };
 
   const EditUserButton = ({ user }) => {
     return (
@@ -291,10 +337,17 @@ const ServerDashboard = (props) => {
     );
   };
 
-  const ServerRowTable = ({ data }) => {
+  EditUserButton.propTypes = {
+    user: User,
+  };
+
+  const ServerRowTable = ({ data, exclude }) => {
     const sortedData = Object.keys(data)
       .sort()
       .reduce(function (result, key) {
+        if (exclude && exclude.includes(key)) {
+          return result;
+        }
         let value = data[key];
         switch (key) {
           case "last_activity":
@@ -334,88 +387,101 @@ const ServerDashboard = (props) => {
     );
   };
 
-  const serverRow = (user, server) => {
-    const { servers, ...userNoServers } = user;
+  ServerRowTable.propTypes = {
+    data: Server,
+    exclude: PropTypes.arrayOf(PropTypes.string),
+  };
+
+  const ServerRow = ({ user, server }) => {
     const serverNameDash = server.name ? `-${server.name}` : "";
     const userServerName = user.name + serverNameDash;
     const open = collapseStates[userServerName] || false;
-    return [
-      <tr
-        key={`${userServerName}-row`}
-        data-testid={`user-row-${userServerName}`}
-        className="user-row"
-      >
-        <td data-testid="user-row-name">
-          <span>
-            <Button
-              onClick={() =>
-                setCollapseStates({
-                  ...collapseStates,
-                  [userServerName]: !open,
-                })
-              }
-              aria-controls={`${userServerName}-collapse`}
-              aria-expanded={open}
-              data-testid={`${userServerName}-collapse-button`}
-              variant={open ? "secondary" : "primary"}
-              size="sm"
-            >
-              <span className="fa fa-caret-down"></span>
-            </Button>{" "}
-          </span>
-          <span data-testid={`user-name-div-${userServerName}`}>
-            {user.name}
-          </span>
-        </td>
-        <td data-testid="user-row-admin">{user.admin ? "admin" : ""}</td>
-
-        <td data-testid="user-row-server">
-          <p className="text-secondary">{server.name}</p>
-        </td>
-        <td data-testid="user-row-last-activity">
-          {server.last_activity ? timeSince(server.last_activity) : "Never"}
-        </td>
-        <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>
-      </tr>,
-      <tr key={`${userServerName}-detail`}>
-        <td
-          colSpan={6}
-          style={{ padding: 0 }}
-          data-testid={`${userServerName}-td`}
+    return (
+      <Fragment key={`${userServerName}-row`}>
+        <tr
+          key={`${userServerName}-row`}
+          data-testid={`user-row-${userServerName}`}
+          className="user-row"
         >
-          <Collapse in={open} data-testid={`${userServerName}-collapse`}>
-            <CardGroup
-              id={`${userServerName}-card-group`}
-              style={{ width: "100%", margin: "0 auto", float: "none" }}
-            >
-              <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
-                <Card.Title>User</Card.Title>
-                <ServerRowTable data={userNoServers} />
-              </Card>
-              <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
-                <Card.Title>Server</Card.Title>
-                <ServerRowTable data={server} />
-              </Card>
-            </CardGroup>
-          </Collapse>
-        </td>
-      </tr>,
-    ];
+          <td data-testid="user-row-name">
+            <span>
+              <Button
+                onClick={() =>
+                  setCollapseStates({
+                    ...collapseStates,
+                    [userServerName]: !open,
+                  })
+                }
+                aria-controls={`${userServerName}-collapse`}
+                aria-expanded={open}
+                data-testid={`${userServerName}-collapse-button`}
+                variant={open ? "secondary" : "primary"}
+                size="sm"
+              >
+                <span className="fa fa-caret-down"></span>
+              </Button>{" "}
+            </span>
+            <span data-testid={`user-name-div-${userServerName}`}>
+              {user.name}
+            </span>
+          </td>
+          <td data-testid="user-row-admin">{user.admin ? "admin" : ""}</td>
+
+          <td data-testid="user-row-server">
+            <p className="text-secondary">{server.name}</p>
+          </td>
+          <td data-testid="user-row-last-activity">
+            {server.last_activity ? timeSince(server.last_activity) : "Never"}
+          </td>
+          <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>
+        </tr>
+        <tr key={`${userServerName}-detail`}>
+          <td
+            colSpan={6}
+            style={{ padding: 0 }}
+            data-testid={`${userServerName}-td`}
+          >
+            <Collapse in={open} data-testid={`${userServerName}-collapse`}>
+              <CardGroup
+                id={`${userServerName}-card-group`}
+                style={{ width: "100%", margin: "0 auto", float: "none" }}
+              >
+                <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
+                  <Card.Title>User</Card.Title>
+                  <ServerRowTable data={user} exclude={["server", "servers"]} />
+                </Card>
+                <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
+                  <Card.Title>Server</Card.Title>
+                  <ServerRowTable data={server} />
+                </Card>
+              </CardGroup>
+            </Collapse>
+          </td>
+        </tr>
+      </Fragment>
+    );
   };
 
-  let servers = user_data.flatMap((user) => {
-    let userServers = Object.values({
+  ServerRow.propTypes = {
+    user: User,
+    server: Server,
+  };
+
+  const serverRows = user_data.flatMap((user) => {
+    const userServers = Object.values({
+      // eslint-disable-next-line react/prop-types
       "": user.server || {},
+      // eslint-disable-next-line react/prop-types
       ...(user.servers || {}),
     });
-    return userServers.map((server) => [user, server]);
+    return userServers.map((server) => ServerRow({ user, server }));
   });
 
   return (
@@ -447,7 +513,7 @@ const ServerDashboard = (props) => {
                   setStateFilter(event.target.checked ? "active" : null);
                 }}
               />
-              <Form.Check.Label for="active-servers-filter">
+              <Form.Check.Label htmlFor="active-servers-filter">
                 {"only active servers"}
               </Form.Check.Label>
             </Form.Check>
@@ -502,7 +568,7 @@ const ServerDashboard = (props) => {
                   variant="primary"
                   className="start-all"
                   data-testid="start-all"
-                  title="start all servers on the current page"
+                  title="Start all default servers on the current page"
                   onClick={() => {
                     Promise.all(startAll(user_data.map((e) => e.name)))
                       .then((res) => {
@@ -519,13 +585,7 @@ const ServerDashboard = (props) => {
                         return res;
                       })
                       .then((res) => {
-                        updateUsersWithParams()
-                          .then((data) => {
-                            dispatchPageUpdate(data.items, data._pagination);
-                          })
-                          .catch(() =>
-                            setErrorAlert(`Failed to update users list.`),
-                          );
+                        loadPageData();
                         return res;
                       })
                       .catch(() => setErrorAlert(`Failed to start servers.`));
@@ -539,11 +599,12 @@ const ServerDashboard = (props) => {
                   variant="danger"
                   className="stop-all"
                   data-testid="stop-all"
-                  title="stop all servers on the current page"
+                  title="Stop all servers including named servers on the current page"
                   onClick={() => {
                     Promise.all(stopAll(user_data.map((e) => e.name)))
                       .then((res) => {
-                        let failedServers = res.filter((e) => !e.ok);
+                        // Array of arrays of servers for each user
+                        let failedServers = res.flat().filter((e) => !e.ok);
                         if (failedServers.length > 0) {
                           setErrorAlert(
                             `Failed to stop ${failedServers.length} ${
@@ -556,13 +617,7 @@ const ServerDashboard = (props) => {
                         return res;
                       })
                       .then((res) => {
-                        updateUsersWithParams()
-                          .then((data) => {
-                            dispatchPageUpdate(data.items, data._pagination);
-                          })
-                          .catch(() =>
-                            setErrorAlert(`Failed to update users list.`),
-                          );
+                        loadPageData();
                         return res;
                       })
                       .catch(() => setErrorAlert(`Failed to stop servers.`));
@@ -582,16 +637,21 @@ const ServerDashboard = (props) => {
                 </Button>
               </td>
             </tr>
-            {servers.flatMap(([user, server]) => serverRow(user, server))}
+            {serverRows}
           </tbody>
         </table>
         <PaginationFooter
-          offset={offset}
+          // use user_page for display, which is what's on the page
+          // setOffset immediately updates url state and _requests_ an update
+          // but takes finite time before user_page is updated
+          offset={user_page.offset}
           limit={limit}
           visible={user_data.length}
           total={total}
-          next={() => setOffset(offset + limit)}
-          prev={() => setOffset(offset - limit)}
+          next={() => setOffset(user_page.offset + limit)}
+          prev={() =>
+            setOffset(limit > user_page.offset ? 0 : user_page.offset - limit)
+          }
           handleLimit={handleLimit}
         />
         <br></br>
@@ -601,7 +661,7 @@ const ServerDashboard = (props) => {
 };
 
 ServerDashboard.propTypes = {
-  user_data: PropTypes.array,
+  user_data: PropTypes.arrayOf(User),
   updateUsers: PropTypes.func,
   shutdownHub: PropTypes.func,
   startServer: PropTypes.func,

jsx/src/components/ServerDashboard/ServerDashboard.test.js

@@ -1,7 +1,6 @@
-import React from "react";
-import { withProps } from "recompose";
+import React, { act } from "react";
+import { withProps } from "../../util/_recompose";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import userEvent from "@testing-library/user-event";
 import {
   render,
@@ -10,8 +9,7 @@ import {
   getByText,
   getAllByRole,
 } from "@testing-library/react";
-import { HashRouter, Routes, Route, useSearchParams } from "react-router-dom";
-// import { CompatRouter,  } from "react-router-dom-v5-compat";
+import { HashRouter, Routes, Route, useSearchParams } from "react-router";
 import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
 // eslint-disable-next-line
@@ -24,8 +22,8 @@ jest.mock("react-redux", () => ({
   ...jest.requireActual("react-redux"),
   useSelector: jest.fn(),
 }));
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useSearchParams: jest.fn(),
 }));
 
@@ -207,7 +205,6 @@ let mockUpdateUsers = jest.fn(({ offset, limit, sort, name_filter, state }) => {
 let searchParams = new URLSearchParams();
 
 beforeEach(() => {
-  jest.useFakeTimers();
   useSelector.mockImplementation((callback) => {
     return callback(mockAppState());
   });
@@ -291,7 +288,7 @@ test("Invokes the startServer event on button click", async () => {
   expect(start_elems.length).toBe(Object.keys(bar_servers).length);
 
   await act(async () => {
-    fireEvent.click(start_elems[0]);
+    await fireEvent.click(start_elems[0]);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -307,7 +304,7 @@ test("Invokes the stopServer event on button click", async () => {
   let stop = screen.getByText("Stop Server");
 
   await act(async () => {
-    fireEvent.click(stop);
+    await fireEvent.click(stop);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -323,7 +320,7 @@ test("Invokes the shutdownHub event on button click", async () => {
   let shutdown = screen.getByText("Shutdown Hub");
 
   await act(async () => {
-    fireEvent.click(shutdown);
+    await fireEvent.click(shutdown);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -338,7 +335,7 @@ test("Sorts according to username", async () => {
 
   expect(searchParams.get("sort")).toEqual(null);
   let handler = screen.getByTestId(testId);
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("name");
 
   await act(async () => {
@@ -346,7 +343,7 @@ test("Sorts according to username", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("-name");
 
   await act(async () => {
@@ -354,7 +351,7 @@ test("Sorts according to username", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("name");
 });
 
@@ -367,7 +364,7 @@ test("Sorts according to last activity", async () => {
 
   expect(searchParams.get("sort")).toEqual(null);
   let handler = screen.getByTestId(testId);
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("last_activity");
 
   await act(async () => {
@@ -375,7 +372,7 @@ test("Sorts according to last activity", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("-last_activity");
 
   await act(async () => {
@@ -383,7 +380,7 @@ test("Sorts according to last activity", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("last_activity");
 });
 
@@ -392,12 +389,10 @@ test("Filter according to server status (running/not running)", async () => {
   await act(async () => {
     rerender = render(serverDashboardJsx()).rerender;
   });
-  console.log(rerender);
-  console.log("begin test");
   const label = "only active servers";
   let handler = screen.getByLabelText(label);
   expect(handler.checked).toEqual(false);
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
 
   // FIXME: need to force a rerender to get updated checkbox
   // I don't think this should be required
@@ -408,7 +403,7 @@ test("Filter according to server status (running/not running)", async () => {
   expect(searchParams.get("state")).toEqual("active");
   expect(handler.checked).toEqual(true);
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
 
   await act(async () => {
     rerender(serverDashboardJsx());
@@ -431,17 +426,14 @@ test("Shows server details with button click", async () => {
   expect(collapse).toHaveClass("collapse");
   expect(collapse).not.toHaveClass("show");
   expect(collapseBar).not.toHaveClass("show");
-
+  await fireEvent.click(button);
   await act(async () => {
-    fireEvent.click(button);
     jest.runAllTimers();
   });
-
   expect(collapse).toHaveClass("collapse show");
   expect(collapseBar).not.toHaveClass("show");
-
+  await fireEvent.click(button);
   await act(async () => {
-    fireEvent.click(button);
     jest.runAllTimers();
   });
 
@@ -449,8 +441,8 @@ test("Shows server details with button click", async () => {
   expect(collapse).not.toHaveClass("show");
   expect(collapseBar).not.toHaveClass("show");
 
+  await fireEvent.click(button);
   await act(async () => {
-    fireEvent.click(button);
     jest.runAllTimers();
   });
 
@@ -480,7 +472,7 @@ test("Shows a UI error dialogue when start all servers fails", async () => {
   let startAll = screen.getByTestId("start-all");
 
   await act(async () => {
-    fireEvent.click(startAll);
+    await fireEvent.click(startAll);
   });
 
   let errorDialog = screen.getByText("Failed to start servers.");
@@ -496,7 +488,7 @@ test("Shows a UI error dialogue when stop all servers fails", async () => {
   let stopAll = screen.getByTestId("stop-all");
 
   await act(async () => {
-    fireEvent.click(stopAll);
+    await fireEvent.click(stopAll);
   });
 
   let errorDialog = screen.getByText("Failed to stop servers.");
@@ -513,7 +505,7 @@ test("Shows a UI error dialogue when start user server fails", async () => {
   expect(start_elems.length).toBe(Object.keys(bar_servers).length);
 
   await act(async () => {
-    fireEvent.click(start_elems[0]);
+    await fireEvent.click(start_elems[0]);
   });
 
   let errorDialog = screen.getByText("Failed to start server.");
@@ -531,7 +523,7 @@ test("Shows a UI error dialogue when start user server returns an improper statu
   expect(start_elems.length).toBe(Object.keys(bar_servers).length);
 
   await act(async () => {
-    fireEvent.click(start_elems[0]);
+    await fireEvent.click(start_elems[0]);
   });
 
   let errorDialog = screen.getByText("Failed to start server.");
@@ -550,7 +542,7 @@ test("Shows a UI error dialogue when stop user servers fails", async () => {
   let stop = screen.getByText("Stop Server");
 
   await act(async () => {
-    fireEvent.click(stop);
+    await fireEvent.click(stop);
   });
 
   let errorDialog = screen.getByText("Failed to stop server.");
@@ -569,7 +561,7 @@ test("Shows a UI error dialogue when stop user server returns an improper status
   let stop = screen.getByText("Stop Server");
 
   await act(async () => {
-    fireEvent.click(stop);
+    await fireEvent.click(stop);
   });
 
   let errorDialog = screen.getByText("Failed to stop server.");
@@ -584,12 +576,13 @@ test("Search for user calls updateUsers with name filter", async () => {
     render(serverDashboardJsx());
   });
 
+  const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
   let search = screen.getByLabelText("user-search");
 
   expect(mockUpdateUsers.mock.calls).toHaveLength(1);
 
   expect(searchParams.get("offset")).toEqual("2");
-  userEvent.type(search, "a");
+  await user.type(search, "a");
   expect(search.value).toEqual("a");
   await act(async () => {
     jest.runAllTimers();
@@ -599,7 +592,7 @@ test("Search for user calls updateUsers with name filter", async () => {
   // FIXME: useSelector mocks prevent updateUsers from being called
   // expect(mockUpdateUsers.mock.calls).toHaveLength(2);
   // expect(mockUpdateUsers).toBeCalledWith(0, 100, "a");
-  userEvent.type(search, "b");
+  await user.type(search, "b");
   expect(search.value).toEqual("ab");
   await act(async () => {
     jest.runAllTimers();
@@ -608,7 +601,7 @@ test("Search for user calls updateUsers with name filter", async () => {
   // expect(mockUpdateUsers).toBeCalledWith(0, 100, "ab");
 });
 
-test("Interacting with PaginationFooter causes state update and refresh via useEffect call", async () => {
+test("Interacting with PaginationFooter requests page update", async () => {
   await act(async () => {
     render(serverDashboardJsx());
   });
@@ -624,15 +617,12 @@ test("Interacting with PaginationFooter causes state update and refresh via useE
     fireEvent.click(next);
     jest.runAllTimers();
   });
-
   expect(searchParams.get("offset")).toEqual("2");
-  expect(searchParams.get("limit")).toEqual("2");
-
-  // FIXME: should call updateUsers, does in reality.
-  // tests don't reflect reality due to mocked state/useSelector
-  // unclear how to fix this.
-  // expect(callbackSpy.mock.calls).toHaveLength(2);
-  // expect(callbackSpy).toHaveBeenCalledWith(2, 2, "");
+  // FIXME: useSelector mocks prevent updateUsers from being called
+  // expect(mockUpdateUsers).toBeCalledWith({
+  //   ...defaultUpdateUsersParams,
+  //   offset: 2,
+  // });
 });
 
 test("Server delete button exists for named servers", async () => {
@@ -676,7 +666,7 @@ test("Start server and confirm pending state", async () => {
   expect(buttons[2].textContent).toBe("Edit User");
 
   await act(async () => {
-    fireEvent.click(buttons[0]);
+    await fireEvent.click(buttons[0]);
   });
   expect(mockUpdateUsers.mock.calls).toHaveLength(1);
 

jsx/src/util/_recompose.js

@@ -0,0 +1,35 @@
+// extracted tiny subset we use from react-recompose
+// we probably don't need these at all,
+// but vendor before refactoring
+
+// https://github.com/acdlite/recompose
+// License: MIT
+// Copyright (c) 2015-2018 Andrew Clark
+
+import { createElement } from "react";
+
+function createFactory(type) {
+  return createElement.bind(null, type);
+}
+
+export const compose = (...funcs) =>
+  funcs.reduce(
+    (a, b) =>
+      (...args) =>
+        a(b(...args)),
+    (arg) => arg,
+  );
+
+const mapProps = (propsMapper) => (BaseComponent) => {
+  const factory = createFactory(BaseComponent);
+  const MapProps = (props) => factory(propsMapper(props));
+  return MapProps;
+};
+
+export const withProps = (input) => {
+  const hoc = mapProps((props) => ({
+    ...props,
+    ...(typeof input === "function" ? input(props) : input),
+  }));
+  return hoc;
+};

jsx/src/util/jhapiUtil.js

@@ -1,9 +1,11 @@
+import PropTypes from "prop-types";
+
 const jhdata = window.jhdata || {};
 const base_url = jhdata.base_url || "/";
 const xsrfToken = jhdata.xsrf_token;
 
 export const jhapiRequest = (endpoint, method, data) => {
-  let api_url = new URL(`${base_url}hub/api` + endpoint, location.origin);
+  let api_url = new URL(`${base_url}api` + endpoint, location.origin);
   if (xsrfToken) {
     api_url.searchParams.set("_xsrf", xsrfToken);
   }
@@ -17,3 +19,21 @@ export const jhapiRequest = (endpoint, method, data) => {
     body: data ? JSON.stringify(data) : null,
   });
 };
+
+// need to declare the subset of fields we use, at least
+export const Server = PropTypes.shape({
+  name: PropTypes.string,
+  url: PropTypes.string,
+  active: PropTypes.boolean,
+  pending: PropTypes.string,
+  last_activity: PropTypes.string,
+});
+
+export const User = PropTypes.shape({
+  admin: PropTypes.boolean,
+  name: PropTypes.string,
+  last_activity: PropTypes.string,
+  url: PropTypes.string,
+  server: Server,
+  servers: PropTypes.objectOf(Server),
+});

jsx/src/util/layout.jsx

@@ -1,7 +1,7 @@
 import React from "react";
-import { withProps } from "recompose";
 import { Col, Row, Container } from "react-bootstrap";
 import PropTypes from "prop-types";
+import { withProps } from "./_recompose";
 import ErrorAlert from "./error";
 
 export const MainCol = (props) => {
@@ -34,5 +34,5 @@ export const MainContainer = (props) => {
 MainContainer.propTypes = {
   errorAlert: PropTypes.string,
   setErrorAlert: PropTypes.func,
-  children: PropTypes.array,
+  children: PropTypes.node,
 };

jsx/src/util/paginationParams.js

@@ -1,5 +1,5 @@
 import { debounce } from "lodash";
-import { useSearchParams } from "react-router-dom";
+import { useSearchParams } from "react-router";
 
 export const usePaginationParams = () => {
   // get offset, limit, name filter from URL

jsx/src/util/withAPI.js

@@ -1,4 +1,4 @@
-import { withProps } from "recompose";
+import { withProps } from "./_recompose";
 import { jhapiRequest } from "./jhapiUtil";
 
 const withAPI = withProps(() => ({
@@ -30,7 +30,17 @@ const withAPI = withProps(() => ({
   startAll: (names) =>
     names.map((e) => jhapiRequest("/users/" + e + "/server", "POST")),
   stopAll: (names) =>
-    names.map((e) => jhapiRequest("/users/" + e + "/server", "DELETE")),
+    names.map((name) =>
+      jhapiRequest("/users/" + name, "GET")
+        .then((data) => data.json())
+        .then((data) =>
+          Promise.all(
+            Object.keys(data.servers).map((server) =>
+              jhapiRequest("/users/" + name + "/servers/" + server, "DELETE"),
+            ),
+          ),
+        ),
+    ),
   addToGroup: (users, groupname) =>
     jhapiRequest("/groups/" + groupname + "/users", "POST", { users }),
   updateProp: (propobject, groupname) =>

jsx/testing/setup.jest.js

@@ -0,0 +1,5 @@
+// Workaround "ReferenceError: TextEncoder is not defined"
+// https://stackoverflow.com/questions/68468203/why-am-i-getting-textencoder-is-not-defined-in-jest/68468204#68468204
+// https://jestjs.io/docs/configuration#setupfiles-array
+import { TextEncoder, TextDecoder } from "util";
+Object.assign(global, { TextDecoder, TextEncoder });

jupyterhub/_version.py

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