Bump to 5.1.0

changelog for 5.1.0

.dockerignore

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

.github/dependabot.yaml

@@ -1,4 +1,4 @@
-# dependabot.yml reference: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+# dependabot.yaml reference: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 #
 # Notes:
 # - Status and logs from dependabot are provided at
@@ -8,8 +8,9 @@ version: 2
 updates:
   # Maintain dependencies in our GitHub Workflows
   - package-ecosystem: github-actions
-    directory: "/"
+    directory: /
+    labels: [ci]
     schedule:
-      interval: weekly
+      interval: monthly
       time: "05:00"
-      timezone: "Etc/UTC"
+      timezone: Etc/UTC

.github/workflows/registry-overviews.yml

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

.github/workflows/release.yml

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

.github/workflows/support-bot.yml

@@ -12,7 +12,7 @@ jobs:
   action:
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/support-requests@v3
+      - uses: dessant/support-requests@v4
         with:
           github-token: ${{ github.token }}
           support-label: "support"
@@ -25,7 +25,7 @@ jobs:
 
             Our goal is to sustain a positive experience for both users and developers. We use GitHub issues for specific discussions related to changing a repository's content, and let the forum be where we can more generally help and inspire each other.
 
-            Thanks you for being an active member of our community! :heart:
+            Thank you for being an active member of our community! :heart:
           close-issue: true
           lock-issue: false
           issue-lock-reason: "off-topic"

.github/workflows/test-docs.yml

@@ -36,26 +36,39 @@ env:
 
 jobs:
   validate-rest-api-definition:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
 
       - name: Validate REST API definition
-        uses: char0n/swagger-editor-validate@v1.3.2
-        with:
-          definition-file: docs/source/_static/rest-api.yml
+        run: |
+          npx @redocly/cli lint
 
   test-docs:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
         with:
-          python-version: "3.9"
+          # make rediraffecheckdiff requires git history to compare current
+          # commit with the main branch and previous releases.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            docs/requirements.txt
 
       - name: Install requirements
         run: |
-          pip install -r docs/requirements.txt pytest
+          pip install -e . -r docs/requirements.txt pytest
 
       - name: pytest docs/
         run: |
@@ -72,3 +85,31 @@ jobs:
         run: |
           cd docs
           make linkcheck
+
+      # make rediraffecheckdiff compares files for different changesets
+      # these diff targets aren't always available
+      # - compare with base ref (usually 'main', always on 'origin') for pull requests
+      # - only compare with tags when running against jupyterhub/jupyterhub
+      #   to avoid errors on forks, which often lack tags
+      - name: check redirects for this PR
+        if: github.event_name == 'pull_request'
+        run: |
+          cd docs
+          export REDIRAFFE_BRANCH=origin/${{ github.base_ref }}
+          make rediraffecheckdiff
+
+      # this should check currently published 'stable' links for redirects
+      - name: check redirects since last release
+        if: github.repository == 'jupyterhub/jupyterhub'
+        run: |
+          cd docs
+          export REDIRAFFE_BRANCH=$(git describe --tags --abbrev=0)
+          make rediraffecheckdiff
+
+      # longer-term redirect check (fixed version) for older links
+      - name: check redirects since 3.0.0
+        if: github.repository == 'jupyterhub/jupyterhub'
+        run: |
+          cd docs
+          export REDIRAFFE_BRANCH=3.0.0
+          make rediraffecheckdiff

.github/workflows/test-jsx.yml

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

.github/workflows/test.yml

@@ -36,7 +36,7 @@ permissions:
 jobs:
   # Run "pytest jupyterhub/tests" in various configurations
   pytest:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 15
 
     strategy:
@@ -65,7 +65,7 @@ jobs:
         #   unencrypted HTTP
         #
         # main_dependencies:
-        #   Tests everything when the we use the latest available dependencies
+        #   Tests everything when we use the latest available dependencies
         #   from: traitlets.
         #
         # NOTE: Since only the value of these parameters are presented in the
@@ -74,7 +74,7 @@ jobs:
         # Python versions available at:
         #   https://github.com/actions/python-versions/blob/HEAD/versions-manifest.json
         include:
-          - python: "3.7"
+          - python: "3.8"
             oldest_dependencies: oldest_dependencies
             legacy_notebook: legacy_notebook
           - python: "3.8"
@@ -84,12 +84,15 @@ jobs:
             db: mysql
           - python: "3.10"
             db: postgres
-          - python: "3.11"
+          - python: "3.12"
             subdomain: subdomain
             serverextension: serverextension
           - python: "3.11"
             ssl: ssl
             serverextension: serverextension
+          - python: "3.11"
+            jupyverse: jupyverse
+            subset: singleuser
           - python: "3.11"
             subdomain: subdomain
             noextension: noextension
@@ -99,8 +102,11 @@ jobs:
             noextension: noextension
             subset: singleuser
           - python: "3.11"
-            selenium: selenium
+            browser: browser
           - python: "3.11"
+            subdomain: subdomain
+            browser: browser
+          - python: "3.12"
             main_dependencies: main_dependencies
 
     steps:
@@ -114,7 +120,7 @@ jobs:
           fi
           if [ "${{ matrix.db }}" == "mysql" ]; then
               echo "MYSQL_HOST=127.0.0.1" >> $GITHUB_ENV
-              echo "JUPYTERHUB_TEST_DB_URL=mysql+mysqlconnector://root@127.0.0.1:3306/jupyterhub" >> $GITHUB_ENV
+              echo "JUPYTERHUB_TEST_DB_URL=mysql+mysqldb://root@127.0.0.1:3306/jupyterhub" >> $GITHUB_ENV
           fi
           if [ "${{ matrix.ssl }}" == "ssl" ]; then
               echo "SSL_ENABLED=1" >> $GITHUB_ENV
@@ -130,41 +136,50 @@ jobs:
           elif [ "${{ matrix.noextension }}" != "" ]; then
               echo "JUPYTERHUB_SINGLEUSER_EXTENSION=0" >> $GITHUB_ENV
           fi
-      - uses: actions/checkout@v3
-      # NOTE: actions/setup-node@v3 make use of a cache within the GitHub base
+          if [ "${{ matrix.jupyverse }}" != "" ]; then
+              echo "JUPYTERHUB_SINGLEUSER_APP=jupyverse" >> $GITHUB_ENV
+          fi
+      - uses: actions/checkout@v4
+      # NOTE: actions/setup-node@v4 make use of a cache within the GitHub base
       #       environment and setup in a fraction of a second.
-      - name: Install Node v14
-        uses: actions/setup-node@v3
+      - name: Install Node
+        uses: actions/setup-node@v4
         with:
-          node-version: "14"
+          node-version: "20"
       - name: Install Javascript dependencies
         run: |
           npm install
           npm install -g configurable-http-proxy yarn
           npm list
 
-      # NOTE: actions/setup-python@v4 make use of a cache within the GitHub base
+      # NOTE: actions/setup-python@v5 make use of a cache within the GitHub base
       #       environment and setup in a fraction of a second.
       - name: Install Python ${{ matrix.python }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "${{ matrix.python }}"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements.txt
+            ci/oldest-dependencies/requirements.old
 
       - name: Install Python dependencies
         run: |
           pip install --upgrade pip
-          pip install -e ".[test]"
 
           if [ "${{ matrix.oldest_dependencies }}" != "" ]; then
-            # take any dependencies in requirements.txt such as tornado>=5.0
-            # and transform them to tornado==5.0 so we can run tests with
-            # the earliest-supported versions
-            cat requirements.txt | grep '>=' | sed -e 's@>=@==@g' > oldest-requirements.txt
-            pip install -r oldest-requirements.txt
+            # frozen env with oldest dependencies
+            # make sure our `>=` pins really do express our minimum supported versions
+            pip install -r ci/oldest-dependencies/requirements.old -e .
+          else
+            pip install -e ".[test]"
           fi
 
           if [ "${{ matrix.main_dependencies }}" != "" ]; then
-              pip install git+https://github.com/ipython/traitlets#egg=traitlets --force
+              # Tests are broken:
+              # https://github.com/jupyterhub/jupyterhub/issues/4418
+              # pip install git+https://github.com/ipython/traitlets#egg=traitlets --force
               pip install --upgrade --pre sqlalchemy
           fi
           if [ "${{ matrix.legacy_notebook }}" != "" ]; then
@@ -174,8 +189,12 @@ jobs:
           if [ "${{ matrix.jupyter_server }}" != "" ]; then
               pip install "jupyter_server==${{ matrix.jupyter_server }}"
           fi
+          if [ "${{ matrix.jupyverse }}" != "" ]; then
+              pip install "jupyverse[jupyterlab,auth-jupyterhub]"
+              pip install -e .
+          fi
           if [ "${{ matrix.db }}" == "mysql" ]; then
-              pip install mysql-connector-python
+              pip install mysqlclient
           fi
           if [ "${{ matrix.db }}" == "postgres" ]; then
               pip install psycopg2-binary
@@ -227,28 +246,31 @@ jobs:
               DB=postgres bash ci/init-db.sh
           fi
 
-      - name: Configure selenium tests
-        if: matrix.selenium
-        run: echo "PYTEST_ADDOPTS=$PYTEST_ADDOPTS -m selenium" >> "${GITHUB_ENV}"
+      - name: Configure browser tests
+        if: matrix.browser
+        run: echo "PYTEST_ADDOPTS=$PYTEST_ADDOPTS -m browser" >> "${GITHUB_ENV}"
+
+      - name: Ensure browsers are installed for playwright
+        if: matrix.browser
+        run: python -m playwright install --with-deps
 
       - name: Run pytest
         run: |
           pytest -k "${{ matrix.subset }}" --maxfail=2 --cov=jupyterhub jupyterhub/tests
 
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
 
   docker-build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: build images
         run: |
-          docker build -t jupyterhub/jupyterhub .
+          DOCKER_BUILDKIT=1 docker build -t jupyterhub/jupyterhub .
           docker build -t jupyterhub/jupyterhub-onbuild onbuild
-          docker build -t jupyterhub/jupyterhub:alpine -f dockerfiles/Dockerfile.alpine .
           docker build -t jupyterhub/singleuser singleuser
 
       - name: smoke test jupyterhub

.gitignore

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

.pre-commit-config.yaml

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

.prettierignore

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

.readthedocs.yaml

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

Dockerfile

@@ -6,7 +6,7 @@
 #
 # Option 1:
 #
-# FROM jupyterhub/jupyterhub:latest
+# FROM quay.io/jupyterhub/jupyterhub:latest
 #
 # And put your configuration file jupyterhub_config.py in /srv/jupyterhub/jupyterhub_config.py.
 #
@@ -14,90 +14,133 @@
 #
 # Or you can create your jupyterhub config and database on the host machine, and mount it with:
 #
-# docker run -v $PWD:/srv/jupyterhub -t jupyterhub/jupyterhub
+# docker run -v $PWD:/srv/jupyterhub -t quay.io/jupyterhub/jupyterhub
 #
 # NOTE
-# If you base on jupyterhub/jupyterhub-onbuild
+# If you base on quay.io/jupyterhub/jupyterhub-onbuild
 # your jupyterhub_config.py will be added automatically
 # from your docker directory.
 
+######################################################################
+# 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
-FROM $BASE_IMAGE AS builder
 
-USER root
 
-ENV DEBIAN_FRONTEND noninteractive
-RUN apt-get update \
- && apt-get install -yq --no-install-recommends \
+######################################################################
+# 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 \
-    nodejs \
-    npm \
- && apt-get clean \
- && rm -rf /var/lib/apt/lists/*
-
-RUN python3 -m pip install --upgrade setuptools pip build wheel
-RUN npm install --global yarn
+ && 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 . /src/jupyterhub/
-WORKDIR /src/jupyterhub
+COPY . .
 
-# Build client component packages (they will be copied into ./share and
-# packaged with the built wheel.)
-RUN python3 -m build --wheel
-RUN python3 -m pip wheel --wheel-dir wheelhouse dist/*.whl
+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
 
-FROM $BASE_IMAGE
-
-USER root
+######################################################################
+# All other wheels required by JupyterHub, some are platform specific
+FROM $BASE_IMAGE AS wheel-builder
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get update \
- && apt-get install -yq --no-install-recommends \
+RUN apt-get update -qq \
+ && apt-get install -yqq --no-install-recommends \
+    build-essential \
     ca-certificates \
     curl \
-    gnupg \
     locales \
+    python3-dev \
     python3-pip \
     python3-pycurl \
-    nodejs \
-    npm \
- && apt-get clean \
- && rm -rf /var/lib/apt/lists/*
+    python3-venv \
+ && python3 -m pip install --no-cache-dir --upgrade setuptools pip build wheel
 
-ENV SHELL=/bin/bash \
+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
-
-RUN  locale-gen $LC_ALL
-
-# always make sure pip is up to date!
-RUN python3 -m pip install --no-cache --upgrade setuptools pip
-
-RUN npm install -g configurable-http-proxy@^4.2.0 \
- && rm -rf ~/.npm
-
-# install the wheels we built in the first stage
-COPY --from=builder /src/jupyterhub/wheelhouse /tmp/wheelhouse
-RUN python3 -m pip install --no-cache /tmp/wheelhouse/*
-
-RUN mkdir -p /srv/jupyterhub/
-WORKDIR /srv/jupyterhub/
+    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"]

MANIFEST.in

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

README.md

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

bower-lite

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

ci/init-db.sh

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

ci/oldest-dependencies/oldest-dependencies.txt

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

ci/oldest-dependencies/requirements.in

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

ci/oldest-dependencies/requirements.old

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

demo-image/Dockerfile

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

demo-image/jupyterhub_config.py

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

dockerfiles/Dockerfile.alpine

@@ -1,14 +0,0 @@
-FROM alpine:3.13
-ENV LANG=en_US.UTF-8
-RUN apk add --no-cache \
-        python3 \
-        py3-pip \
-        py3-ruamel.yaml \
-        py3-cryptography \
-        py3-sqlalchemy
-
-ARG JUPYTERHUB_VERSION=1.3.0
-RUN pip3 install --no-cache jupyterhub==${JUPYTERHUB_VERSION}
-
-USER nobody
-CMD ["jupyterhub"]

dockerfiles/README.md

@@ -1,22 +0,0 @@
-## What is Dockerfile.alpine
-
-Dockerfile.alpine contains the base image for jupyterhub. It does not work independently, but only as part of a full jupyterhub cluster
-
-## How to use it?
-
-You will need:
-
-1. A running configurable-http-proxy, whose API is accessible.
-2. A jupyterhub_config file.
-3. Authentication and other libraries required by the specific jupyterhub_config file.
-
-## Steps to test it outside a cluster
-
-- start configurable-http-proxy in another container
-- specify CONFIGPROXY_AUTH_TOKEN env in both containers
-- put both containers on the same network (e.g. docker network create jupyterhub; docker run ... --net jupyterhub)
-- tell jupyterhub where CHP is (e.g. c.ConfigurableHTTPProxy.api_url = 'http://chp:8001')
-- tell jupyterhub not to start the proxy itself (c.ConfigurableHTTPProxy.should_start = False)
-- Use a dummy authenticator for ease of testing. Update following in jupyterhub_config file
-  - c.JupyterHub.authenticator_class = 'dummyauthenticator.DummyAuthenticator'
-  - c.DummyAuthenticator.password = "your strong password"

docs/requirements.txt

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

docs/source/_templates/page.html

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

docs/source/_templates/redoc.html

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

docs/source/conf.py

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

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

docs/source/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,

docs/source/explanation/concepts.md

@@ -0,0 +1,430 @@
+(explanation:concepts)=
+
+# JupyterHub: A conceptual overview
+
+```{warning}
+This page could is 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](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+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
 
@@ -82,7 +82,7 @@ Additionally, there is usually _very_ little load on the database itself.
 By far the most taxing activity on the database is the 'list all users' endpoint, primarily used by the [idle-culling service](https://github.com/jupyterhub/jupyterhub-idle-culler).
 Database-based optimizations have been added to make even these operations feasible for large numbers of users:
 
-1. State filtering on [GET /hub/api/users?state=active](../reference/rest-api.html#/default/get_users){.external},
+1. State filtering on [GET /hub/api/users?state=active](rest-api-get-users),
    which limits the number of results in the query to only the relevant subset (added in JupyterHub 1.3), rather than all users.
 2. [Pagination](api-pagination) of all list endpoints, allowing the request of a large number of resources to be more fairly balanced with other Hub activities across multiple requests (added in 2.0).
 
@@ -95,8 +95,14 @@ The Hub and its database are not involved in most requests to single-user server
 
 JupyterHub supports a variety of database backends via [SQLAlchemy][].
 The default is sqlite, which works great for many cases, but you should be able to use many backends supported by SQLAlchemy.
-Usually, this will mean PostgreSQL or MySQL, both of which are well tested with JupyterHub.
+Usually, this will mean PostgreSQL or MySQL, both of which are officially supported and well tested with JupyterHub, but others may work as well.
+See [SQLAlchemy's docs][sqlalchemy-dialect] for how to connect to different database backends.
+Doing so generally involves:
 
+1. installing a Python package that provides a client implementation, and
+2. setting [](JupyterHub.db_url) to connect to your database with the specified implementation
+
+[sqlalchemy-dialect]: https://docs.sqlalchemy.org/en/20/dialects/
 [sqlalchemy]: https://www.sqlalchemy.org
 
 ### Default backend: SQLite
@@ -109,14 +115,16 @@ For production systems, SQLite has some disadvantages when used with JupyterHub:
 
 - `upgrade-db` may not always work, and you may need to start with a fresh database
 - `downgrade-db` **will not** work if you want to rollback to an earlier
-  version, so backup the `jupyterhub.sqlite` file before upgrading
+  version, so backup the `jupyterhub.sqlite` file before upgrading (JupyterHub automatically creates a date-stamped backup file when upgrading sqlite)
 
 The sqlite documentation provides a helpful page about [when to use SQLite and
 where traditional RDBMS may be a better choice](https://sqlite.org/whentouse.html).
 
 ### Picking your database backend (PostgreSQL, MySQL)
 
-When running a long term deployment or a production system, we recommend using a full-fledged relational database, such as [PostgreSQL](https://www.postgresql.org) or [MySQL](https://www.mysql.com), that supports the SQL `ALTER TABLE` statement.
+When running a long term deployment or a production system, we recommend using a full-fledged relational database, such as [PostgreSQL](https://www.postgresql.org) or [MySQL](https://www.mysql.com), that supports the SQL `ALTER TABLE` statement, which is used in some database upgrade steps.
+
+In general, you select your database backend with [](JupyterHub.db_url), and can further configure it (usually not necessary) with [](JupyterHub.db_kwargs).
 
 ## Notes and Tips
 
@@ -132,14 +140,25 @@ multiple processes which might try to access the file at the same time.
 ### PostgreSQL
 
 We recommend using PostgreSQL for production if you are unsure whether to use
-MySQL or PostgreSQL or if you do not have a strong preference. There is
-additional configuration required for MySQL that is not needed for PostgreSQL.
+MySQL or PostgreSQL or if you do not have a strong preference.
+There is additional configuration required for MySQL that is not needed for PostgreSQL.
+
+For example, to connect to a PostgreSQL database with psycopg2:
+
+1. install psycopg2: `pip install psycopg2` (or `psycopg2-binary` to avoid compilation, which is [not recommended for production][psycopg2-binary])
+2. set authentication via environment variables `PGUSER` and `PGPASSWORD`
+3. configure [](JupyterHub.db_url):
+
+   ```python
+   c.JupyterHub.db_url = "postgresql+psycopg2://my-postgres-server:5432/my-db-name"
+   ```
+
+[psycopg2-binary]: https://www.psycopg.org/docs/install.html#psycopg-vs-psycopg-binary
 
 ### MySQL / MariaDB
 
-- You should use the `pymysql` sqlalchemy provider (the other one, MySQLdb,
-  isn't available for py3).
-- You also need to set `pool_recycle` to some value (typically 60 - 300)
+- You should probably use the `pymysql` or `mysqlclient` sqlalchemy provider, or another backend [recommended by sqlalchemy](https://docs.sqlalchemy.org/en/20/dialects/mysql.html#dialect-mysql)
+- You also need to set `pool_recycle` to some value (typically 60 - 300, JupyterHub will default to 60)
   which depends on your MySQL setup. This is necessary since MySQL kills
   connections serverside if they've been idle for a while, and the connection
   from the hub will be idle for longer than most connections. This behavior
@@ -153,3 +172,12 @@ additional configuration required for MySQL that is not needed for PostgreSQL.
   correctly. Later versions of MariaDB and MySQL should set these values by
   default, as well as have a default `DYNAMIC` `row_format` and pose no trouble
   to users.
+
+For example, to connect to a mysql database with mysqlclient:
+
+1. install mysqlclient: `pip install mysqlclient`
+2. configure [](JupyterHub.db_url):
+
+   ```python
+   c.JupyterHub.db_url = "mysql+mysqldb://myuser:mypassword@my-sql-server:3306/my-db-name"
+   ```

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,3 +1,5 @@
+(explanation:hub-oauth)=
+
 # JupyterHub and OAuth
 
 JupyterHub uses [OAuth 2](https://oauth.net/2/) as an internal mechanism for authenticating users.

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

docs/source/faq/faq.md

@@ -1,36 +1,78 @@
+(faq)=
+
 # Frequently asked questions
 
 ## How do I share links to notebooks?
 
-In short, where you see `/user/name/notebooks/foo.ipynb` use `/hub/user-redirect/notebooks/foo.ipynb` (replace `/user/name` with `/hub/user-redirect`).
-
 Sharing links to notebooks is a common activity,
-and can look different based on what you mean.
+and can look different depending on what you mean by 'share.'
 Your first instinct might be to copy the URL you see in the browser,
-e.g. `hub.jupyter.org/user/yourname/notebooks/coolthing.ipynb`.
-However, let's break down what this URL means:
+e.g. `jupyterhub.example/user/yourname/notebooks/coolthing.ipynb`,
+but this usually won't work, depending on the permissions of the person you share the link with.
 
-`hub.jupyter.org/user/yourname/` is the URL prefix handled by _your server_,
-which means that sharing this URL is asking the person you share the link with
-to come to _your server_ and look at the exact same file.
-In most circumstances, this is forbidden by permissions because the person you share with does not have access to your server.
-What actually happens when someone visits this URL will depend on whether your server is running and other factors.
+Unfortunately, 'share' means at least a few things to people in a JupyterHub context.
+We'll cover 3 common cases here, when they are applicable, and what assumptions they make:
 
-**But what is our actual goal?**
+1. sharing links that will open the same file on the visitor's own server
+2. sharing links that will bring the visitor to _your_ server (e.g. for real-time collaboration, or RTC)
+3. publishing notebooks and sharing links that will download the notebook into the user's server
 
-A typical situation is that you have some shared or common filesystem,
-such that the same path corresponds to the same document
-(either the exact same document or another copy of it).
-Typically, what folks want when they do sharing like this
-is for each visitor to open the same file _on their own server_,
-so Breq would open `/user/breq/notebooks/foo.ipynb` and
-Seivarden would open `/user/seivarden/notebooks/foo.ipynb`, etc.
+### link to the same file on the visitor's server
 
-JupyterHub has a special URL that does exactly this!
-It's called `/hub/user-redirect/...`.
-So if you replace `/user/yourname` in your URL bar
-with `/hub/user-redirect` any visitor should get the same
-URL on their own server, rather than visiting yours.
+This is for the case where you have JupyterHub on a shared (or sufficiently similar) filesystem, where you want to share a link that will cause users to login and start their _own_ server, to view or edit the file.
 
-In JupyterLab 2.0, this should also be the result of the "Copy Shareable Link"
-action in the file browser.
+**Assumption:** the same path on someone else's server is valid and points to the same file
+
+This is useful in e.g. classes where you know students have certain files in certain locations, or collaborations where you know you have a shared filesystem where everyone has access to the same files.
+
+A link should look like `https://jupyterhub.example/hub/user-redirect/lab/tree/foo.ipynb`.
+You can hand-craft these URLs from the URL you are looking at, where you see `/user/name/lab/tree/foo.ipynb` use `/hub/user-redirect/lab/tree/foo.ipynb` (replace `/user/name/` with `/hub/user-redirect/`).
+Or you can use JupyterLab's "copy shareable link" in the context menu in the file browser:
+
+![copy shareable link in JupyterLab](../images/shareable_link.webp)
+
+which will produce a correct URL with `/hub/user-redirect/` in it.
+
+### link to the file on your server
+
+This is for the case where you want to both be using _your_ server, e.g. for real-time collaboration (RTC).
+
+**Assumption:** the user has (or should have) access to your server.
+
+**Assumption:** your server is running _or_ the user has permission to start it.
+
+By default, JupyterHub users don't have access to each other's servers, but JupyterHub 2.0 administrators can grant users limited access permissions to each other's servers.
+If the visitor doesn't have access to the server, these links will result in a 403 Permission Denied error.
+
+In many cases, for this situation you can copy the link in your URL bar (`/user/yourname/lab`), or you can add `/tree/path/to/specific/notebook.ipynb` to open a specific file.
+
+The [jupyterlab-link-share] JupyterLab extension generates these links, and even can _grant_ other users access to your server.
+
+[jupyterlab-link-share]: https://github.com/jupyterlab-contrib/jupyterlab-link-share
+
+:::{warning}
+Note that the way the extension _grants_ access is handing over credentials to allow the other user to **_BECOME YOU_**.
+This is usually not appropriate in JupyterHub.
+:::
+
+### link to a published copy
+
+Another way to 'share' notebooks is to publish copies, e.g. pushing the notebook to a git repository and sharing a download link.
+This way is especially useful for course materials,
+where no assumptions are necessary about the user's environment,
+except for having one package installed.
+
+**Assumption:** The [nbgitpuller](inv:nbgitpuller#index) server extension is installed
+
+Unlike the other two methods, nbgitpuller doesn't provide an extension to copy a shareable link for the document you're currently looking at,
+but it does provide a [link generator](inv:nbgitpuller#link),
+which uses the `user-redirect` approach above.
+
+When visiting an nbgitpuller link:
+
+- The visitor will be directed to their own server
+- Your repo will be cloned (or updated if it's already been cloned)
+- and then the file opened when it's ready
+
+[nbgitpuller]: https://nbgitpuller.readthedocs.io
+[nbgitpuller-link]: https://nbgitpuller.readthedocs.io/en/latest/link.html

docs/source/faq/institutional-faq.md

@@ -1,3 +1,5 @@
+(faq:institutional)=
+
 # Institutional FAQ
 
 This page contains common questions from users of JupyterHub,
@@ -66,7 +68,7 @@ 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
 - **Research laboratories**: NASA, NCAR, NOAA, the Large Synoptic Survey Telescope, Brookhaven National Lab,
-  Minnesota Supercomputing Institute, ALCF, CERN, Lawrence Livermore National Laboratory
+  Minnesota Supercomputing Institute, ALCF, CERN, Lawrence Livermore National Laboratory, HUNT
 - **Online communities**: Pangeo, Quantopian, mybinder.org, MathHub, Open Humans
 - **Computing infrastructure providers**: NERSC, San Diego Supercomputing Center, Compute Canada
 - **Companies**: Capital One, SANDVIK code, Globus
@@ -124,13 +126,13 @@ as more resources are needed - allowing you to utilize the benefits of a flexibl
 
 ### Is JupyterHub secure?
 
-The short answer: yes.  
+The short answer: yes.
 JupyterHub as a standalone application has been battle-tested at an institutional
 level for several years, and makes a number of "default" security decisions that are reasonable for most
 users.
 
 - For security considerations in the base JupyterHub application,
-  [see the JupyterHub security page](https://jupyterhub.readthedocs.io/en/stable/reference/websecurity.html).
+  [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
 
@@ -46,13 +46,13 @@ things like inspect other users' servers or modify the user list at runtime).
 ### JupyterHub Docker container is not accessible at localhost
 
 Even though the command to start your Docker container exposes port 8000
-(`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`),
+(`docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub`),
 it is possible that the IP address itself is not accessible/visible. As a result,
 when you try http://localhost:8000 in your browser, you are unable to connect
 even though the container is running properly. One workaround is to explicitly
 tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this
 command:
-`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000`
+`docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000`
 
 ### How can I kill ports from JupyterHub-managed services that have been orphaned?
 
@@ -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
 
-[JupyterHub services](https://jupyterhub.readthedocs.io/en/stable/reference/services.html) 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.
@@ -347,12 +347,12 @@ In order to resolve this issue, there are two potential options.
 
 ### Where do I find Docker images and Dockerfiles related to JupyterHub?
 
-Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/).
-The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/)
+Docker images can be found at the [JupyterHub organization on Quay.io](https://quay.io/organization/jupyterhub).
+The Docker image [jupyterhub/singleuser](https://quay.io/repository/jupyterhub/singleuser)
 provides an example single-user notebook server for use with DockerSpawner.
 
 Additional single-user notebook server images can be found at the [Jupyter
-organization on DockerHub](https://hub.docker.com/r/jupyter/) and information
+organization on Quay.io](https://quay.io/organization/jupyter) and information
 about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks).
 
 ### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner?

docs/source/howto/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
@@ -79,7 +81,7 @@ server {
     location / {
         proxy_pass http://127.0.0.1:8000;
         proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_host;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 
         # websocket headers

docs/source/howto/configuration/config-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

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

docs/source/howto/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
 
@@ -24,6 +24,7 @@ such as:
 
 - Checking which users are active
 - Adding or removing users
+- Adding or removing services
 - Stopping or starting single user notebook servers
 - Authenticating services
 - Communicating with an individual Jupyter server's REST API
@@ -33,36 +34,13 @@ such as:
 To send requests using the JupyterHub API, you must pass an API token with
 the request.
 
-The preferred way of generating an API token is by running:
-
-```bash
-openssl rand -hex 32
-```
-
-This `openssl` command generates a potential token that can then be
-added to JupyterHub using `.api_tokens` configuration setting in
-`jupyterhub_config.py`.
-
-```{note}
-The api_tokens configuration has been softly deprecated since the introduction of services.
-```
-
-Alternatively, you can use the `jupyterhub token` command to generate a token
-for a specific hub user by passing the **username**:
-
-```bash
-jupyterhub token <username>
-```
-
-This command generates a random string to use as a token and registers
-it for the given user with the Hub's database.
-
-In [version 0.8.0](changelog), a token request page for
-generating an API token is available from the JupyterHub user interface:
+While JupyterHub is running, any JupyterHub user can request a token via the `token` page.
+This is accessible via a `token` link in the top nav bar from the JupyterHub home page,
+or at the URL `/hub/token`.
 
 :::{figure-md}
 
-![token request page](../images/token-request.png)
+![token request page](../images/token-page.png)
 
 JupyterHub's API token page
 :::
@@ -74,6 +52,40 @@ JupyterHub's token page after successfully requesting a token.
 
 :::
 
+### Register API tokens via configuration
+
+Sometimes, you'll want to pre-generate a token for access to JupyterHub,
+typically for use by external services,
+so that both JupyterHub and the service have access to the same value.
+
+First, you need to generate a good random secret.
+A good way of generating an API token is by running:
+
+```bash
+openssl rand -hex 32
+```
+
+This `openssl` command generates a random token that can be added to the JupyterHub configuration in `jupyterhub_config.py`.
+
+For external services, this would be registered with JupyterHub via configuration:
+
+```python
+c.JupyterHub.services = [
+    {
+        "name": "my-service",
+        "api_token": the_secret_value,
+    },
+]
+```
+
+At this point, requests authenticated with the token will be associated with The service `my-service`.
+
+```{note}
+You can also load additional tokens for users via the `JupyterHub.api_tokens` configuration.
+
+However, this option has been deprecated since the introduction of services.
+```
+
 ## Assigning permissions to a token
 
 Prior to JupyterHub 2.0, there were two levels of permissions:
@@ -87,9 +99,46 @@ In JupyterHub 2.0,
 specific permissions are now defined as '**scopes**',
 and can be assigned both at the user/service level,
 and at the individual token level.
+The previous behavior is represented by the scope `inherit`,
+and is still the default behavior for requesting a token if limited permissions are not specified.
 
 This allows e.g. a user with full admin permissions to request a token with limited permissions.
 
+In JupyterHub 5.0, you can specify scopes for a token when requesting it via the `/hub/tokens` page as a space-separated list.
+In JupyterHub 3.0 and later, you can also request tokens with limited scopes via the JupyterHub API (provided you already have a token!):
+
+```python
+import json
+from urllib.parse import quote
+
+import requests
+
+def request_token(
+    username, *, api_token, scopes=None, expires_in=0, hub_url="http://127.0.0.1:8081"
+):
+    """Request a new token for a user"""
+    request_body = {}
+    if expires_in:
+        request_body["expires_in"] = expires_in
+    if scopes:
+        request_body["scopes"] = scopes
+    url = hub_url.rstrip("/") + f"/hub/api/users/{quote(username)}/tokens"
+    r = requests.post(
+        url,
+        data=json.dumps(request_body),
+        headers={"Authorization": f"token {api_token}"},
+    )
+    if r.status_code >= 400:
+        # extract error message for nicer error messages
+        r.reason = r.json().get("message", r.text)
+    r.raise_for_status()
+    # response is a dict and will include the token itself in the 'token' field,
+    # as well as other fields about the token
+    return r.json()
+
+request_token("myusername", scopes=["list:users"], api_token="abc123")
+```
+
 ## Updating to admin services
 
 ```{note}
@@ -153,7 +202,7 @@ Authorization header.
 ### Use requests
 
 Using the popular Python [requests](https://docs.python-requests.org)
-library, an API GET request is made, and the request sends an API token for
+library, an API GET request is made to [/users](rest-api-get-users), and the request sends an API token for
 authorization. The response contains information about the users, here's example code to make an API request for the users of a JupyterHub deployment
 
 ```python
@@ -171,7 +220,7 @@ r.raise_for_status()
 users = r.json()
 ```
 
-This example provides a slightly more complicated request, yet the
+This example provides a slightly more complicated request (to [/groups/formgrade-data301/users](rest-api-post-group-users)), yet the
 process is very similar:
 
 ```python
@@ -205,7 +254,7 @@ provided by notebook servers managed by JupyterHub if it has the necessary `acce
 
 Pagination is available through the `offset` and `limit` query parameters on
 list endpoints, which can be used to return ideally sized windows of results.
-Here's example code demonstrating pagination on the `GET /users`
+Here's example code demonstrating pagination on the [`GET /users`](rest-api-get-users)
 endpoint to fetch the first 20 records.
 
 ```python
@@ -304,12 +353,18 @@ hub:
 
 With that setting in place, a new named-server is activated like this:
 
+```{parsed-literal}
+[POST /api/users/:username/servers/:servername](rest-api-post-user-server-name)
+```
+
+e.g.
+
 ```bash
 curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverA>"
 curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverB>"
 ```
 
-The same servers can be stopped by substituting `DELETE` for `POST` above.
+The same servers can be [stopped](rest-api-delete-user-server-name) by substituting `DELETE` for `POST` above.
 
 ### Some caveats for using named-servers
 

docs/source/howto/separate-proxy.md

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

docs/source/howto/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

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

docs/source/howto/upgrading.md

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

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

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

docs/source/rbac/scopes.md

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

docs/source/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/redirects.txt

@@ -1,23 +1,54 @@
 # This file contains rediraffe redirects as generated from the docs/source/conf.py file
 # For more information, see rediraffe configuration in the conf.py file.
 
+
 "changelog.md" "reference/changelog.md"
+"contributor-list.md" "contributing/contributor-list.md"
+"gallery-jhub-deployments.md" "reference/gallery-jhub-deployments.md"
+"installation-basics.md" "tutorial/installation-basics.md"
+"quickstart.md" "tutorial/quickstart.md"
+"quickstart-docker.md" "tutorial/quickstart-docker.md"
+"troubleshooting.md" "faq/troubleshooting.md"
+
+"admin/capacity-planning.md" "explanation/capacity-planning.md"
+"admin/log-messages.md" "howto/log-messages.md"
+"admin/upgrading.md" "howto/upgrading.md"
+
+"events/index.md" "reference/event-logging.md"
+
+"getting-started/authenticators-users-basics.md" "tutorial/getting-started/authenticators-users-basics.md"
+"getting-started/config-basics.md" "tutorial/getting-started/config-basics.md"
 "getting-started/faq.md" "faq/faq.md"
+"getting-started/institutional-faq.md" "faq/institutional-faq.md"
+"getting-started/networking-basics.md" "tutorial/getting-started/networking-basics.md"
+"getting-started/services-basics.md" "tutorial/getting-started/services-basics.md"
+"getting-started/spawners-basics.md" "tutorial/getting-started/spawners-basics.md"
+
 "reference/api-only.md" "howto/api-only.md"
 "reference/config-ghoauth.md" "howto/configuration/config-ghoauth.md"
 "reference/config-proxy.md" "howto/configuration/config-proxy.md"
-"admin/log-messages.md" "howto/log-messages.md"
+"reference/database.md" "explanation/database.md"
+"reference/oauth.md" "explanation/oauth.md"
 "reference/proxy.md" "howto/proxy.md"
 "reference/templates.md" "howto/templates.md"
-"quickstart-docker.md" "tutorial/quickstart-docker.md"
 "reference/config-examples.md" "howto/index.md"
-"getting-started/institutional-faq.md" "faq/institutional-faq.md"
-"troubleshooting.md" "faq/troubleshooting.md"
 "reference/config-sudo.md" "howto/configuration/config-sudo.md"
 "reference/config-user-env.md" "howto/configuration/config-user-env.md"
 "reference/rest.md" "howto/rest.md"
 "reference/separate-proxy.md" "howto/separate-proxy.md"
-"admin/upgrading.md" "howto/upgrading.md"
-"installation-basics.md" "tutorial/installation-basics.md"
-"quickstart.md" "tutorial/quickstart.md"
-"events/index.md" "reference/event-logging.md"
+"reference/server-api.md" "tutorial/server-api.md"
+"reference/websecurity.md" "explanation/websecurity.md"
+
+"api/app.md" "reference/api/app.md"
+"api/auth.md" "reference/api/auth.md"
+"api/index.md" "reference/api/index.md"
+"api/proxy.md" "reference/api/proxy.md"
+"api/service.md" "reference/api/service.md"
+"api/services.auth.md" "reference/api/services.auth.md"
+"api/spawner.md" "reference/api/spawner.md"
+"api/user.md" "reference/api/user.md"
+
+#  -- JupyterHub 4.0 --
+# redirects above are up-to-date as of JupyterHub 4.0
+# add future redirects below
+# (e.g. with `make rediraffewritediff`)

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/authenticators.md

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

docs/source/reference/config-reference.md

@@ -14,6 +14,12 @@ section, the `jupyterhub_config.py` can be automatically generated via
 > jupyterhub --generate-config
 > ```
 
+Most of this information is available in a nicer format in:
+
+- [](./api/app.md)
+- [](./api/auth.md)
+- [](./api/spawner.md)
+
 The following contains the output of that command for reference.
 
 ```{eval-rst}

docs/source/reference/event-logging.md

@@ -1,28 +1,23 @@
 # Event logging and telemetry
 
-JupyterHub can be configured to record structured events from a running server using Jupyter's [Telemetry System]. The types of events that JupyterHub emits are defined by [JSON schemas] listed at the bottom of this [page].
+JupyterHub can be configured to record structured events from a running server using Jupyter's [Events System]. The types of events that JupyterHub emits are defined by [JSON schemas] listed at the bottom of this page.
 
 ## How to emit events
 
-Event logging is handled by its `Eventlog` object. This leverages Python's standing [logging] library to emit, filter, and collect event data.
+Event logging is handled by its `EventLogger` object. This leverages Python's standing [logging] library to emit, filter, and collect event data.
 
-To begin recording events, you'll need to set two configurations:
+To begin recording events, you'll need to set at least one configuration option:
 
-> 1. `handlers`: tells the EventLog _where_ to route your events. This trait is a list of Python logging handlers that route events to the event log file.
-> 2. `allows_schemas`: tells the EventLog _which_ events should be recorded. No events are emitted by default; all recorded events must be listed here.
+> `EventLogger.handlers`: tells the EventLogger _where_ to route your events. This trait is a list of Python logging handlers that route events to e.g. an event log file.
 
 Here's a basic example:
 
-```
+```python
 import logging
 
-c.EventLog.handlers = [
+c.EventLogger.handlers = [
     logging.FileHandler('event.log'),
 ]
-
-c.EventLog.allowed_schemas = [
-    'hub.jupyter.org/server-action'
-]
 ```
 
 The output is a file, `"event.log"`, with events recorded as JSON data.
@@ -37,6 +32,15 @@ The output is a file, `"event.log"`, with events recorded as JSON data.
 server-actions
 ```
 
+:::{versionchanged} 5.0
+JupyterHub 5.0 changes from the deprecated jupyter-telemetry to jupyter-events.
+
+The main changes are:
+
+- `EventLog` configuration is now called `EventLogger`
+- The `hub.jupyter.org/server-action` schema is now called `https://schema.jupyter.org/jupyterhub/events/server-action`
+  :::
+
 [json schemas]: https://json-schema.org/
 [logging]: https://docs.python.org/3/library/logging.html
-[telemetry system]: https://github.com/jupyter/telemetry
+[events system]: https://jupyter-events.readthedocs.io

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

@@ -16,8 +16,6 @@ Please submit pull requests to update information or to add new institutions or
 
 - [BIDS - Berkeley Institute for Data Science](https://bids.berkeley.edu/)
 
-  - [Teaching with Jupyter notebooks and JupyterHub](https://bids.berkeley.edu/resources/videos/teaching-ipythonjupyter-notebooks-and-jupyterhub)
-
 - [Data 8](http://data8.org/)
 
   - [GitHub organization](https://github.com/data-8)
@@ -63,6 +61,15 @@ easy to do with RStudio too.
 
 - [jupyterhub-deploy-teaching](https://github.com/jupyterhub/jupyterhub-deploy-teaching) based on work by Brian Granger for Cal Poly's Data Science 301 Course
 
+### CERN
+
+[CERN](https://home.cern/), also known as the European Organization for Nuclear Research, is a world-renowned scientific research centre and the home of the Large Hadron Collider (LHC).
+
+Within CERN, there are two noteworthy JupyterHub deployments in operation:
+
+- [SWAN](https://swan.web.cern.ch/swan/), which stands for Service for Web based Analysis, serves as an interactive data analysis platform primarily utilized at CERN.
+- [VRE](https://vre-hub.github.io/), which stands for Virtual Research Environment, is an analysis platform developed within the [EOSC Project](https://eoscfuture.eu/) to cater to the needs of scientific communities involved in European projects.
+
 ### Chameleon
 
 [Chameleon](https://www.chameleoncloud.org) is a NSF-funded configurable experimental environment for large-scale computer science systems research with [bare metal reconfigurability](https://chameleoncloud.readthedocs.io/en/latest/technical/baremetal.html). Chameleon users utilize JupyterHub to document and reproduce their complex CISE and networking experiments.
@@ -84,6 +91,14 @@ easy to do with RStudio too.
     - log troubleshooting
     - Profiles in IPython Clusters tab
 
+### ETH Zurich
+
+[ETH Zurich](https://ethz.ch/en.html), (Federal Institute of Technology Zurich), is a public research university in Zürich, Switzerland, with focus on science, technology, engineering, and mathematics, although its 16 departments span a variety of disciplines and subjects.
+
+The [Educational Development and Technology](https://ethz.ch/en/the-eth-zurich/organisation/departments/educational-development-and-technology.html) unit provides JupyterHub exclusively for teaching and learning, integrated in the learning management system [Moodle](https://ethz.ch/staffnet/en/teaching/academic-support/it-services-teaching/teaching-applications/moodle-service.html). Each course gets its individually configured JupyterHub environment deployed on a on-premise Kubernetes cluster.
+
+- [ETH JupyterHub](https://ethz.ch/staffnet/en/teaching/academic-support/it-services-teaching/teaching-applications/jupyterhub.html) for teaching and learning
+
 ### George Washington University
 
 - [JupyterHub](https://go.gwu.edu/jupyter) with university single-sign-on. Deployed early 2017.
@@ -179,6 +194,12 @@ easy to do with RStudio too.
 
 - [Deploying JupyterHub on Hadoop](https://jupyterhub-on-hadoop.readthedocs.io)
 
+### Sirepo
+
+- Sirepo is an online Computer-Aided Engineering gateway that contains a JupyterHub instance. Sirepo is provided at no cost for community use, but users must request login access.
+- [Sirepo.com](https://www.sirepo.com)
+- [Sirepo Jupyter](https://www.sirepo.com/jupyter)
+
 ## Miscellaneous
 
 - https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1

docs/source/reference/index.md

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

docs/source/reference/monitoring.md

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

docs/source/reference/rest-api.md

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

docs/source/reference/services.md

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

docs/source/reference/sharing.md

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

docs/source/reference/spawners.md

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

docs/source/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.
@@ -240,7 +240,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

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

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

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

docs/source/tutorial/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
@@ -39,7 +41,7 @@ openssl rand -hex 32
 In [version 0.8.0](changelog), a TOKEN request page for
 generating an API token is available from the JupyterHub user interface:
 
-![Request API TOKEN page](/images/token-request.png)
+![Request API TOKEN page](/images/token-page.png)
 
 ![API TOKEN success page](/images/token-request-success.png)
 

docs/source/tutorial/index.md

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

docs/source/tutorial/quickstart-docker.md

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

docs/source/tutorial/quickstart.md

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

docs/source/tutorial/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

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

examples/bootstrap-script/jupyterhub_config.py

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

examples/collaboration-accounts/README.md

@@ -2,4 +2,4 @@
 
 An example of enabling real-time collaboration with dedicated accounts for collaborations.
 
-See [collaboration account docs](docs/source/tutorial/collaboration-accounts.md) for details.
+See [collaboration account docs](../../docs/source/tutorial/collaboration-users.md) for details.

examples/external-oauth/README.md

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

examples/external-oauth/jupyterhub_config.py

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

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

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

examples/postgres/hub/jupyterhub_config.py

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

examples/read-only/README.md

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

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

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

examples/service-announcement/jupyterhub_config.py

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