Bump to 5.3.0

changelog for 5.3.0

.dockerignore

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

.github/dependabot.yaml

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

.github/workflows/release.yml

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

.github/workflows/support-bot.yml

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

.github/workflows/test-docs.yml

@@ -29,6 +29,9 @@ on:
       - "**"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 env:
   # UTF-8 content may be interpreted as ascii and causes errors without this.
   LANG: C.UTF-8
@@ -36,31 +39,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
+        run: |
-        with:
+          npx @redocly/cli lint
-          definition-file: docs/source/_static/rest-api.yml
 
   test-docs:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # make rediraffecheckdiff requires git history to compare current
           # commit with the main branch and previous releases.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
+          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: |
@@ -73,10 +84,12 @@ jobs:
           cd docs
           make html
 
+      # Output broken and permanently redirected links in a readable format
       - name: check links
-        run: |
+        uses: manics/action-sphinx-linkcheck-summary@main
-          cd docs
+        with:
-          make linkcheck
+          docs-dir: docs
+          build-dir: docs/_build
 
       # make rediraffecheckdiff compares files for different changesets
       # these diff targets aren't always available

.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/checkout@v4
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
-          node-version: "14"
+          node-version: "20"
 
-      - name: Install yarn
+      - name: install jsx
-        run: |
-          npm install -g yarn
-
-      - name: yarn
         run: |
           cd jsx
-          yarn
+          npm ci
 
-      - name: yarn test
+      - name: test
         run: |
           cd jsx
-          yarn test
+          npm test

.github/workflows/test.yml

@@ -36,7 +36,7 @@ permissions:
 jobs:
   # Run "pytest jupyterhub/tests" in various configurations
   pytest:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 15
 
     strategy:
@@ -65,7 +65,7 @@ jobs:
         #   unencrypted HTTP
         #
         # main_dependencies:
-        #   Tests everything when the we use the latest available dependencies
+        #   Tests everything when we use the latest available dependencies
         #   from: traitlets.
         #
         # NOTE: Since only the value of these parameters are presented in the
@@ -74,7 +74,7 @@ jobs:
         # Python versions available at:
         #   https://github.com/actions/python-versions/blob/HEAD/versions-manifest.json
         include:
-          - python: "3.7"
+          - python: "3.8"
             oldest_dependencies: oldest_dependencies
             legacy_notebook: legacy_notebook
           - python: "3.8"
@@ -84,12 +84,15 @@ jobs:
             db: mysql
           - python: "3.10"
             db: postgres
-          - python: "3.11"
+          - python: "3.12"
             subdomain: subdomain
             serverextension: serverextension
           - python: "3.11"
             ssl: ssl
             serverextension: serverextension
+          - python: "3.11"
+            jupyverse: jupyverse
+            subset: singleuser
           - python: "3.11"
             subdomain: subdomain
             noextension: noextension
@@ -101,6 +104,9 @@ jobs:
           - python: "3.11"
             browser: browser
           - python: "3.11"
+            subdomain: subdomain
+            browser: browser
+          - python: "3.12"
             main_dependencies: main_dependencies
 
     steps:
@@ -130,37 +136,44 @@ jobs:
           elif [ "${{ matrix.noextension }}" != "" ]; then
               echo "JUPYTERHUB_SINGLEUSER_EXTENSION=0" >> $GITHUB_ENV
           fi
-      - uses: actions/checkout@v3
+          if [ "${{ matrix.jupyverse }}" != "" ]; then
-      # NOTE: actions/setup-node@v3 make use of a cache within the GitHub base
+              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
+      - name: Install Node
-        uses: actions/setup-node@v3
+        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
+            # frozen env with oldest dependencies
-            # and transform them to tornado==5.0 so we can run tests with
+            # make sure our `>=` pins really do express our minimum supported versions
-            # the earliest-supported versions
+            pip install -r ci/oldest-dependencies/requirements.old -e .
-            cat requirements.txt | grep '>=' | sed -e 's@>=@==@g' > oldest-requirements.txt
+          else
-            pip install -r oldest-requirements.txt
+            pip install --pre -e ".[test]"
           fi
 
           if [ "${{ matrix.main_dependencies }}" != "" ]; then
@@ -176,6 +189,10 @@ jobs:
           if [ "${{ matrix.jupyter_server }}" != "" ]; then
               pip install "jupyter_server==${{ matrix.jupyter_server }}"
           fi
+          if [ "${{ matrix.jupyverse }}" != "" ]; then
+              pip install "jupyverse[jupyterlab,auth-jupyterhub]"
+              pip install -e .
+          fi
           if [ "${{ matrix.db }}" == "mysql" ]; then
               pip install mysqlclient
           fi
@@ -235,31 +252,10 @@ jobs:
 
       - name: Ensure browsers are installed for playwright
         if: matrix.browser
-        run: python -m playwright install --with-deps
+        run: python -m playwright install --with-deps firefox
 
       - name: Run pytest
         run: |
           pytest -k "${{ matrix.subset }}" --maxfail=2 --cov=jupyterhub jupyterhub/tests
 
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v5
-
-  docker-build:
-    runs-on: ubuntu-20.04
-    timeout-minutes: 20
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: build images
-        run: |
-          DOCKER_BUILDKIT=1 docker build -t jupyterhub/jupyterhub .
-          docker build -t jupyterhub/jupyterhub-onbuild onbuild
-          docker build -t jupyterhub/singleuser singleuser
-
-      - name: smoke test jupyterhub
-        run: |
-          docker run --rm -t jupyterhub/jupyterhub jupyterhub --help
-
-      - name: verify static files
-        run: |
-          docker run --rm -t -v $PWD/dockerfiles:/io jupyterhub/jupyterhub python3 /io/test.py

.gitignore

@@ -7,11 +7,11 @@ node_modules
 dist
 docs/_build
 docs/build
-docs/source/_static/rest-api
-docs/source/rbac/scope-table.md
 docs/source/reference/metrics.md
 
 .ipynb_checkpoints
+.virtual_documents
+
 jsx/build/
 # ignore config file at the top-level of the repo
 # but not sub-dirs
@@ -19,8 +19,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 +38,5 @@ docs/source/reference/metrics.rst
 oldest-requirements.txt
 jupyterhub-proxy.pid
 examples/server-api/service-token
+
+*.hot-update*

.pre-commit-config.yaml

@@ -14,44 +14,42 @@ ci:
   autoupdate_schedule: monthly
 
 repos:
-  # Autoformat: Python code, syntax patterns are modernized
+  # autoformat and lint Python code
-  - repo: https://github.com/asottile/pyupgrade
+  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v3.4.0
+    rev: v0.11.4
     hooks:
-      - id: pyupgrade
+      - id: ruff
-        args:
+        types_or:
-          - --py37-plus
+          - python
-
+          - jupyter
-  # Autoformat: Python code
+        args: ["--fix", "--show-fixes"]
-  - repo: https://github.com/PyCQA/autoflake
+      - id: ruff-format
-    rev: v2.1.1
+        types_or:
-    hooks:
+          - python
-      - id: autoflake
+          - jupyter
-        # args ref: https://github.com/PyCQA/autoflake#advanced-usage
-        args:
-          - --in-place
-
-  # Autoformat: Python code
-  - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-
-  # Autoformat: Python code
-  - repo: https://github.com/psf/black
-    rev: 23.3.0
-    hooks:
-      - id: black
 
   # Autoformat: markdown, yaml, javascript (see the file .prettierignore)
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0-alpha.9-for-vscode
+    rev: v4.0.0-alpha.8
     hooks:
       - id: prettier
+        exclude: .*/templates/.*|docs/source/_static/rest-api.yml|docs/source/rbac/scope-table.md
+
+  # autoformat HTML templates
+  - repo: https://github.com/djlint/djLint
+    rev: v1.36.4
+    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: v5.0.0
     hooks:
       - id: end-of-file-fixer
         exclude: share/jupyterhub/static/js/admin-react.js
@@ -59,8 +57,30 @@ repos:
       - id: check-case-conflict
       - id: check-executables-have-shebangs
 
-  # Linting: Python code (see the file .flake8)
+  # source docs: rest-api.yml and scope-table.md are autogenerated
-  - repo: https://github.com/PyCQA/flake8
+  - repo: local
-    rev: "6.0.0"
     hooks:
-      - id: flake8
+      - id: update-api-and-scope-docs
+        name: Update rest-api.yml and scope-table.md based on scopes.py
+        language: python
+        additional_dependencies: ["pytablewriter", "ruamel.yaml"]
+        entry: python docs/source/rbac/generate-scope-table.py
+        args:
+          - --update
+        files: jupyterhub/scopes.py
+        pass_filenames: false
+
+      # run eslint in the jsx directory
+      # need to pass through 'jsx:install-run' hook in
+      # top-level package.json to ensure dependencies are installed
+      # eslint pre-commit hook doesn't really work with eslint 9,
+      # so use `npm run lint:fix`
+      - id: jsx-eslint
+        name: eslint in jsx/
+        entry: npm run jsx:install-run lint:fix
+        pass_filenames: false
+        language: node
+        files: "jsx/.*"
+        # can't run on pre-commit; hangs, for some reason
+        stages:
+          - manual

.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,13 @@ sphinx:
   configuration: docs/source/conf.py
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    nodejs: "16"
+    python: "3.13"
-    python: "3.9"
 
 python:
   install:
+    - path: .
     - requirements: docs/requirements.txt
 
 formats:

CONTRIBUTING.md

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

COPYING.md

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

Dockerfile

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

LICENSE

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

MANIFEST.in

@@ -1,29 +1,13 @@
-include README.md
+# using setuptools-scm means we only need to handle _non-tracked files here_
-include COPYING.md
+
-include setupegg.py
-include bower-lite
-include package.json
 include package-lock.json
-include *requirements.txt
-include Dockerfile
 
-graft onbuild
+# include untracked js/css artifacts, components
-graft jsx
-graft jupyterhub
-graft scripts
 graft share
-graft singleuser
-graft ci
 
-# Documentation
+# prune some large unused files from components.
-graft docs
+# these patterns affect source distributions (sdists)
-prune docs/node_modules
+# we have stricter exclusions from installation in setup.py:get_data_files
-
-# Intermediate javascript files
-prune jsx/node_modules
-prune jsx/build
-
-# prune some large unused files from components
 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
@@ -112,7 +111,7 @@ Visit `http://localhost:8000` in your browser, and sign in with your system user
 
 _Note_: To allow multiple users to sign in to the server, you will need to
 run the `jupyterhub` command as a _privileged user_, such as root.
-The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+The [documentation](https://jupyterhub.readthedocs.io/en/latest/howto/configuration/config-sudo.html)
 describes how to run the server as a _less privileged user_, which requires
 more configuration of the system.
 
@@ -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`.
@@ -221,7 +220,7 @@ docker container or Linux VM.
 We use a shared copyright model that enables all contributors to maintain the
 copyright on their contributions.
 
-All code is licensed under the terms of the [revised BSD license](./COPYING.md).
+All code is licensed under the terms of the [revised BSD license](./LICENSE).
 
 ## Help and resources
 

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

@@ -1,16 +0,0 @@
-# Demo JupyterHub Docker image
-#
-# This should only be used for demo or testing and not as a base image to build on.
-#
-# It includes the notebook package and it uses the DummyAuthenticator and the SimpleLocalProcessSpawner.
-ARG BASE_IMAGE=jupyterhub/jupyterhub-onbuild
-FROM ${BASE_IMAGE}
-
-# Install the notebook package
-RUN python3 -m pip install notebook
-
-# Create a demo user
-RUN useradd --create-home demo
-RUN chown demo .
-
-USER demo

demo-image/README.md

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

demo-image/jupyterhub_config.py

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

dockerfiles/test.py

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

docs/Makefile

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

docs/requirements.txt

@@ -1,14 +1,8 @@
-# We install the jupyterhub package to help autodoc-traits inspect it and
+# docs also require jupyterhub itself to be installed
-# generate documentation.
+# don't depend on it here, as that often results in a duplicate
-#
+# installation of jupyterhub that's already installed
-# 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 .
-
 autodoc-traits
+intersphinx-registry
 jupyterhub-sphinx-theme
 myst-parser>=0.19
 pre-commit

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,21 @@ 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 intersphinx_registry import get_intersphinx_mapping
+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 +49,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 +71,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 +132,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 +236,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=str(docs))
-    subprocess.check_call(["make", "metrics", "scopes"], cwd=docs)
 
 
 # -- Spell checking ----------------------------------------------------------
@@ -182,12 +286,17 @@ 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://linux.die.net/.*",  # linux.die.net seems to block requests from CI with 403 sometimes
-    r"https://jupyter.chameleoncloud.org",  # FIXME: ignore (presumably) short-term SSL issue
+    # don't check links to unpublished advisories
+    r"https://github.com/jupyterhub/jupyterhub/security/advisories/.*",
+    # Occasionally blocks CI checks with 403
+    r"https://www\.mysql\.com",
 ]
 linkcheck_anchors_ignore = [
     "/#!",
@@ -197,12 +306,15 @@ linkcheck_anchors_ignore = [
 # -- Intersphinx -------------------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 #
-intersphinx_mapping = {
+
-    "python": ("https://docs.python.org/3/", None),
+intersphinx_mapping = get_intersphinx_mapping(
-    "tornado": ("https://www.tornadoweb.org/en/stable/", None),
+    packages={
-    "jupyter-server": ("https://jupyter-server.readthedocs.io/en/stable/", None),
+        "python",
-    "nbgitpuller": ("https://nbgitpuller.readthedocs.io/en/latest", None),
+        "tornado",
-}
+        "jupyter-server",
+        "nbgitpuller",
+    }
+)
 
 # -- Options for the opengraph extension -------------------------------------
 # ref: https://github.com/wpilibsuite/sphinxext-opengraph#options

docs/source/contributing/community.md

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

docs/source/contributing/contributor-list.md

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

docs/source/contributing/docs.md

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

docs/source/contributing/index.md

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

docs/source/contributing/roadmap.md

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

docs/source/contributing/security.md

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

docs/source/contributing/setup.md

@@ -1,4 +1,4 @@
-(contributing/setup)=
+(contributing:setup)=
 
 # Setting up a development install
 
@@ -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.
+5. You are now ready to start JupyterHub!
-
-   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!
 
    ```bash
    jupyterhub
    ```
 
-7. You can access JupyterHub from your browser at
+6. You can access JupyterHub from your browser at
    `http://localhost:8000` now.
 
 Happy developing!
@@ -130,6 +123,14 @@ configuration:
 jupyterhub -f testing/jupyterhub_config.py
 ```
 
+The test configuration enables a few things to make testing easier:
+
+- use 'dummy' authentication and 'simple' spawner
+- named servers are enabled
+- listen only on localhost
+- 'admin' is an admin user, if you want to test the admin page
+- disable caching of static files
+
 The default JupyterHub [authenticator](PAMAuthenticator)
 & [spawner](LocalProcessSpawner)
 require your system to have user accounts for each user you want to log in to
@@ -146,6 +147,29 @@ SimpleLocalProcessSpawner. If you are working on just authenticator-related
 parts, use only SimpleLocalProcessSpawner. Similarly, if you are working on
 just spawner-related parts, use only DummyAuthenticator.
 
+## Building frontend components
+
+The testing configuration file also disables caching of static files,
+which allows you to edit and rebuild these files without restarting JupyterHub.
+
+If you are working on the admin react page, which is in the `jsx` directory, you can run:
+
+```bash
+cd jsx
+npm install
+npm run build:watch
+```
+
+to continuously rebuild the admin page, requiring only a refresh of the page.
+
+If you are working on the frontend SCSS files, you can run the same `build:watch` command
+in the _top level_ directory of the repo:
+
+```bash
+npm install
+npm run build:watch
+```
+
 ## Troubleshooting
 
 This section lists common ways setting up your development environment may
@@ -173,3 +197,46 @@ python3 setup.py js    # fetch updated client-side js
 python3 setup.py css   # recompile CSS from LESS sources
 python3 setup.py jsx   # build React admin app
 ```
+
+### Failed to bind XXX to `http://127.0.0.1:<port>/<path>`
+
+This error can happen when there's already an application or a service using this
+port.
+
+Use the following command to find out which service is using this port.
+
+```bash
+lsof -P -i TCP:<port> -sTCP:LISTEN
+```
+
+If nothing shows up, it likely means there's a system service that uses it but
+your current user cannot list it. Reuse the same command with sudo.
+
+```bash
+sudo lsof -P -i TCP:<port> -sTCP:LISTEN
+```
+
+Depending on the result of the above commands, the most simple solution is to
+configure JupyterHub to use a different port for the service that is failing.
+
+As an example, the following is a frequently seen issue:
+
+`Failed to bind hub to http://127.0.0.1:8081/hub/`
+
+Using the procedure described above, start with:
+
+```bash
+lsof -P -i TCP:8081 -sTCP:LISTEN
+```
+
+and if nothing shows up:
+
+```bash
+sudo lsof -P -i TCP:8081 -sTCP:LISTEN
+```
+
+Finally, depending on your findings, you can apply the following change and start JupyterHub again:
+
+```python
+c.JupyterHub.hub_port = 9081 # Or any other free port
+```

docs/source/contributing/tests.md

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

docs/source/explanation/capacity-planning.md

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

docs/source/explanation/concepts.md

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

docs/source/explanation/database.md

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

docs/source/explanation/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
+domains. This means the cross-origin protections between servers has the
-desired effect, and user servers and the Hub are protected from each other. A
+desired effect, and user servers and the Hub are protected from each other.
-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
+**Subdomains are the only way to reliably isolate user servers from each other.**
-accomplished with wildcard DNS. Since this spreads the service across multiple
+
-domains, you will need wildcard SSL as well. Unfortunately, for many
+To enable subdomains, set:
-institutional domains, wildcard DNS and SSL are not available. **If you do plan
+
-to serve untrusted users, enabling subdomains is highly encouraged**, as it
+```python
-resolves the cross-site issues.
+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
+The user must not have permission to install packages into the environment where the singleuser-server runs.
-a virtualenv with disabled system-site-packages. The user should not have
+On a shared system, package isolation is most easily handled by running the single-user server in
-permission to install packages into this environment.
+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
+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 user's kernel(s)
+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
+By default, all communications within JupyterHub—between the proxy, hub, and single
--user notebooks are performed unencrypted. Setting the `internal_ssl` flag in
+-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,3 +1,5 @@
+(faq)=
+
 # Frequently asked questions
 
 ## How do I share links to notebooks?

docs/source/faq/institutional-faq.md

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

docs/source/faq/troubleshooting.md

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

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

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

docs/source/howto/separate-proxy.md

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

docs/source/rbac/scope-table.md

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

docs/source/rbac/scopes.md

@@ -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/reference/api/auth.md

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

docs/source/reference/api/index.md

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

docs/source/reference/api/spawner.md

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

docs/source/reference/authenticators.md

@@ -30,22 +30,66 @@ 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.
 
 ## The Dummy Authenticator
 
-When testing, it may be helpful to use the
+When testing, it may be helpful to use the {class}`~.jupyterhub.auth.DummyAuthenticator`:
-{class}`jupyterhub.auth.DummyAuthenticator`. This allows for any username and
+
-password unless if a global password has been set. Once set, any username will
+```python
-still be accepted but the correct password will need to be provided.
+c.JupyterHub.authenticator_class = "dummy"
+# always a good idea to limit to localhost when testing with an insecure config
+c.JupyterHub.ip = "127.0.0.1"
+```
+
+This allows for any username and password to login, and is _wildly_ insecure.
+
+To use, specify
+
+```python
+c.JupyterHub.authenticator_class = "dummy"
+```
+
+:::{versionadded} 5.0
+The DummyAuthenticator's default `allow_all` is True,
+unlike most other Authenticators.
+:::
+
+:::{deprecated} 5.3
+Setting a password on DummyAuthenticator is deprecated.
+Use the new {class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator`
+if you want to set a shared password for users.
+:::
+
+## Shared Password Authenticator
+
+:::{versionadded} 5.3
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` is added and [DummyAuthenticator.password](#DummyAuthenticator.password) is deprecated.
+:::
+
+For short-term deployments like workshops where there is no real user data to protect and you trust users to not abuse the system or each other,
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` can be used.
+
+Set a [user password](#SharedPasswordAuthenticator.user_password) for users to login:
+
+```python
+c.JupyterHub.authenticator_class = "shared-password"
+c.SharedPasswordAuthenticator.user_password = "my-workshop-2042"
+```
+
+You can also grant admin users access by adding them to `admin_users` and setting a separate [admin password](#SharedPasswordAuthenticator.admin_password):
+
+```python
+c.Authenticator.admin_users = {"danger", "eggs"}
+c.SharedPasswordAuthenticator.admin_password = "extra-super-secret-secure-password"
+```
 
 ## Additional Authenticators
 
-A partial list of other authenticators is available on the
+Additional authenticators can be found on GitHub
-[JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+by searching for [topic:jupyterhub topic:authenticator](https://github.com/search?q=topic%3Ajupyterhub%20topic%3Aauthenticator&type=repositories).
 
 ## Technical Overview of Authentication
 
@@ -55,9 +99,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 +110,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
+- the username (non-empty str) of the authenticated user
-  authentication is successful
+- or a dictionary with fields:
-- return `None` otherwise
+  - `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 +137,14 @@ class DictionaryAuthenticator(Authenticator):
     )
 
     async def authenticate(self, handler, data):
-        if self.passwords.get(data['username']) == data['password']:
+        username = data["username"]
-            return 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 +188,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 +200,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 +235,168 @@ Additionally, configurable attributes for your authenticator will
 appear in jupyterhub help output and auto-generated configuration files
 via `jupyterhub --generate-config`.
 
+(authenticator-allow)=
+
+### Allowing access
+
+When dealing with logging in, there are generally two _separate_ steps:
+
+authentication
+: identifying who is trying to log in, and
+
+authorization
+: deciding whether an authenticated user is allowed to access your JupyterHub
+
+{meth}`Authenticator.authenticate` is responsible for authenticating users.
+It is perfectly fine in the simplest cases for `Authenticator.authenticate` to be responsible for authentication _and_ authorization,
+in which case `authenticate` may return `None` if the user is not authorized.
+
+However, Authenticators also have two methods, {meth}`~.Authenticator.check_allowed` and {meth}`~.Authenticator.check_blocked_users`, which are called after successful authentication to further check if the user is allowed.
+
+If `check_blocked_users()` returns False, authorization stops and the user is not allowed.
+
+If `Authenticator.allow_all` is True OR `check_allowed()` returns True, authorization proceeds.
+
+:::{versionadded} 5.0
+{attr}`.Authenticator.allow_all` and {attr}`.Authenticator.allow_existing_users` are new in JupyterHub 5.0.
+
+By default, `allow_all` is False,
+which is a change from pre-5.0, where `allow_all` was implicitly True if `allowed_users` was empty.
+:::
+
+### Overriding `check_allowed`
+
+:::{versionchanged} 5.0
+`check_allowed()` is **not called** if `allow_all` is True.
+:::
+
+:::{versionchanged} 5.0
+Starting with 5.0, `check_allowed()` should **NOT** return True if no allow config
+is specified (`allow_all` should be used instead).
+
+:::
+
+The base implementation of {meth}`~.Authenticator.check_allowed` checks:
+
+- if username is in the `allowed_users` set, return True
+- else return False
+
+:::{versionchanged} 5.0
+Prior to 5.0, this would also return True if `allowed_users` was empty.
+
+For clarity, this is no longer the case. A new `allow_all` property (default False) has been added which is checked _before_ calling `check_allowed`.
+If `allow_all` is True, this takes priority over `check_allowed`, which will be ignored.
+
+If your Authenticator subclass similarly returns True when no allow config is defined,
+this is fully backward compatible for your users, but means `allow_all = False` has no real effect.
+
+You can make your Authenticator forward-compatible with JupyterHub 5 by defining `allow_all` as a boolean config trait on your class:
+
+```python
+class MyAuthenticator(Authenticator):
+
+    # backport allow_all from JupyterHub 5
+    allow_all = Bool(False, config=True)
+
+    def check_allowed(self, username, authentication):
+        if self.allow_all:
+            # replaces previous "if no auth config"
+            return True
+        ...
+```
+
+:::
+
+If an Authenticator defines additional sources of `allow` configuration,
+such as membership in a group or other information,
+it should override `check_allowed` to account for this.
+
+:::{note}
+`allow_` configuration should generally be _additive_,
+i.e. if access is granted by _any_ allow configuration,
+a user should be authorized.
+
+JupyterHub recommends that Authenticators applying _restrictive_ configuration should use names like `block_` or `require_`,
+and check this during `check_blocked_users` or `authenticate`, not `check_allowed`.
+:::
+
+In general, an Authenticator's skeleton should look like:
+
+```python
+class MyAuthenticator(Authenticator):
+    # backport allow_all for compatibility with JupyterHub < 5
+    allow_all = Bool(False, config=True)
+    require_something = List(config=True)
+    allowed_something = Set()
+
+    def authenticate(self, data, handler):
+        ...
+        if success:
+            return {"username": username, "auth_state": {...}}
+        else:
+            return None
+
+    def check_blocked_users(self, username, authentication=None):
+        """Apply _restrictive_ configuration"""
+
+        if self.require_something and not has_something(username, self.request_):
+            return False
+        # repeat for each restriction
+        if restriction_defined and restriction_not_met:
+            return False
+        return super().check_blocked_users(self, username, authentication)
+
+    def check_allowed(self, username, authentication=None):
+        """Apply _permissive_ configuration
+
+        Only called if check_blocked_users returns True
+        AND allow_all is False
+        """
+        if self.allow_all:
+            # check here to backport allow_all behavior
+            # from JupyterHub 5
+            # this branch will never be taken with jupyterhub >=5
+            return True
+        if self.allowed_something and user_has_something(username):
+            return True
+        # repeat for each allow
+        if allow_config and allow_met:
+            return True
+        # should always have this at the end
+        if self.allowed_users and username in self.allowed_users:
+            return True
+        # do not call super!
+        # super().check_allowed is not safe with JupyterHub < 5.0,
+        # as it will return True if allowed_users is empty
+        return False
+```
+
+Key points:
+
+- `allow_all` is backported from JupyterHub 5, for consistent behavior in all versions of JupyterHub (optional)
+- restrictive configuration is checked in `check_blocked_users`
+- if any restriction is not met, `check_blocked_users` returns False
+- permissive configuration is checked in `check_allowed`
+- if any `allow` condition is met, `check_allowed` returns True
+
+So the logical expression for a user being authorized should look like:
+
+> if ALL restrictions are met AND ANY admissions are met: user is authorized
+
+#### Custom error messages
+
+Any of these authentication and authorization methods may raise a `web.HTTPError` Exception
+
+```python
+from tornado import web
+
+raise web.HTTPError(403, "informative message")
+```
+
+if you want to show a more informative login failure message rather than the generic one.
+
+(authenticator-auth-state)=
+
 ### Authentication state
 
 JupyterHub 0.8 adds the ability to persist state related to authentication,
@@ -284,7 +498,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 +509,62 @@ 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.
+groups cannot be specified with `load_groups` traitlet.
+
+:::{warning}
+When `manage_groups` is True,
+managing groups via the API is still permitted via the `admin:groups` scope (starting with 5.3),
+but any time a user logs in their group membership is completely reset via the login process.
+So it only really makes sense to make manual changes via the API that reflect upstream changes which are not automatically propagated, such as group deletion.
+
+:::
+
+:::{versionchanged} 5.3
+Prior to JupyterHub 5.3, all group management via the API was disabled if `Authenticator.manage_groups` is True.
+:::
+
+(authenticator-roles)=
+
+## 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/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.
+> `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.
-> 2. `allows_schemas`: tells the EventLog _which_ events should be recorded. No events are emitted by default; all recorded events must be listed here.
 
 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)
@@ -84,14 +82,13 @@ Within CERN, there are two noteworthy JupyterHub deployments in operation:
 - Advanced Computing
   - [Palmetto cluster and JupyterHub](https://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html)
 
-### University of Colorado Boulder
+### ETH Zurich
 
-- (CU Research Computing) CURC
+[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.
 
-  - [JupyterHub User Guide](https://curc.readthedocs.io/en/latest/gateways/jupyterhub.html)
+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.
-    - Slurm job dispatched on Crestone compute cluster
+
-    - log troubleshooting
+- [ETH JupyterHub](https://ethz.ch/staffnet/en/teaching/academic-support/it-services-teaching/teaching-applications/jupyterhub.html) for teaching and learning
-    - Profiles in IPython Clusters tab
 
 ### George Washington University
 
@@ -188,6 +185,12 @@ Within CERN, there are two noteworthy JupyterHub deployments in operation:
 
 - [Deploying JupyterHub on Hadoop](https://jupyterhub-on-hadoop.readthedocs.io)
 
+### Sirepo
+
+- Sirepo is an online Computer-Aided Engineering gateway that contains a JupyterHub instance. Sirepo is provided at no cost for community use, but users must request login access.
+- [Sirepo.com](https://www.sirepo.com)
+- [Sirepo Jupyter](https://www.sirepo.com/jupyter)
+
 ## Miscellaneous
 
 - https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1

docs/source/reference/index.md

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

docs/source/reference/monitoring.md

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

docs/source/reference/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">
+```markdown
-<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.1/swagger-ui-bundle.js"></script>
+you cat [GET /api/users](rest-api-get-users)
-<!-- `SwaggerUIBundle` is now available on the page -->
+```
 
-<!-- render the ui here -->
+```{jupyterhub-rest-api-links}
-<div id="openapi-ui"></div>
 
-<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
+When working with JupyterHub, a **Service** is defined as something (usually a process) that can interact with the Hub's REST API.
-with the Hub's REST API. A Service may perform a specific
+A Service may perform a specific action or task.
-action or task. For example, the following tasks can each be a unique Service:
+For example, the following tasks can each be a unique Service:
 
-- shutting down individuals' single user notebook servers that have been idle
+- shutting down individuals' single user notebook servers that have been idle for some time
-  for some time
+- an additional web application which uses the Hub as an OAuth provider to authenticate and authorize user access
-- registering additional web servers which should use the Hub's authentication
+- a script run once in a while, which performs any API action
-  and be served behind the Hub's proxy.
+- 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
+- Does the Service have a web server that should be added to the proxy's table?
-  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
+- `url: str (default - None)` - The URL where the service should be running (from the proxy's perspective).
-  administrative privileges
+  Typically a localhost URL for Hub-managed services.
-- `url: str (default - None)` - The URL where the service is/should be. If a
+  If a url is specified,
-  url is specified for where the Service runs its own web server,
+  the service will be added to the proxy at `/services/:name`.
-  the service will be added to the proxy at `/services/:name`
+- `api_token: str (default - None)` - For Externally-Managed Services,
-- `api_token: str (default - None)` - For Externally-Managed Services you need to specify
+  you need to specify an API token to perform API requests to the Hub.
-  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
+- `user: str` - the name of a system user to manage the Service.
-  unspecified, run as the same user as the Hub.
+  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
+A configuration example of an Externally-Managed Service running its own web
-running its own web server is:
+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))
+and [service-whoami](https://github.com/jupyterhub/jupyterhub/tree/master/examples/service-whoami))
-
-(TODO: Where is this API TOKen set?)
 
 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

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

docs/source/tutorial/collaboration-users.md

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

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

@@ -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
+Users in the `allowed_users` set are added to the Hub database when the Hub is started.
-started.
 
-```{warning}
+:::{versionchanged} 5.0
-If this configuration value is not set, then **all authenticated users will be allowed into your hub**.
+{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
+The `access:servers` scope can be granted to users to give them permission to visit other users' servers.
-do not have permission to log in to the single user notebook servers
+For example, to give members of the `teachers` group access to the servers of members of the `students` group:
-owned by _other users_. If `JupyterHub.admin_access` is set to `True`,
+
-then admins have permission to log in _as other users_ on their
+```python
-respective machines for debugging. **As a courtesy, you should make
+c.JupyterHub.load_roles = [
-sure your users know if admin_access is enabled.**
+  {
+    "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
+panel or the REST API.
-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,
+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

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

docs/source/tutorial/server-api.md

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

docs/source/tutorial/sharing.md

@@ -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/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
+           # can be randomly generated or hand-written, but must
-           "oauth_client_id": "abc123",
+           # 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(
+c.JupyterHub.db_url = f'postgresql://jupyterhub:{pg_pass}@{pg_host}:5432/jupyterhub'
-    pg_pass, pg_host
-)

examples/read-only/README.md

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

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

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

examples/service-announcement/jupyterhub_config.py

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

examples/service-announcement/templates/page.html

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