hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-07 10:04:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

run rst2myst

Browse Source
This commit is contained in:
Min RK
2022-12-07 08:58:00 +01:00
parent e9c0fc6eb7
commit 832e8c0348
46 changed files with 1345 additions and 1401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
docs/source/admin/upgrading.md Normal file
View File

@@ -0,0 +1,139 @@
# Upgrading JupyterHub
JupyterHub offers easy upgrade pathways between minor versions. This
document describes how to do these upgrades.
If you are using {ref}`a JupyterHub distribution <index/distributions>`, you
should consult the distribution's documentation on how to upgrade. This documentation is
for those who have set up their JupyterHub without using a distribution.
This documentation is lengthy because it is quite detailed. Most likely, upgrading
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.
## Read the Changelog
The [changelog](../changelog.md) contains information on what has
changed with the new JupyterHub release and any deprecation warnings.
Read these notes to familiarize yourself with the coming changes. There
might be new releases of the authenticators & spawners you use, so
read the changelogs for those too!
## Notify your users
If you use the default configuration where `configurable-http-proxy`
is managed by JupyterHub, your users will see service disruption during
the upgrade process. You should notify them, and pick a time to do the
upgrade where they will be least disrupted.
If you use a different proxy or run `configurable-http-proxy`
independent of JupyterHub, your users will be able to continue using notebook
servers they had already launched, but will not be able to launch new servers or sign in.
## Backup database & config
Before doing an upgrade, it is critical to back up:
1. Your JupyterHub database (SQLite by default, or MySQL / Postgres if you used those).
If you use SQLite (the default), you should backup the `jupyterhub.sqlite` file.
2. Your `jupyterhub_config.py` file.
3. Your users' home directories. This is unlikely to be affected directly by
a JupyterHub upgrade, but we recommend a backup since user data is critical.
## Shut down JupyterHub
Shut down the JupyterHub process. This would vary depending on how you
have set up JupyterHub to run. It is most likely using a process
supervisor of some sort (`systemd` or `supervisord` or even `docker`).
Use the supervisor-specific command to stop the JupyterHub process.
## Upgrade JupyterHub packages
There are two environments where the `jupyterhub` package is installed:
1. The _hub environment_: where the JupyterHub server process
runs. This is started with the `jupyterhub` command, and is what
people generally think of as JupyterHub.
2. The _notebook user environments_: where the user notebook
servers are launched from, and is probably custom to your own
installation. This could be just one environment (different from the
hub environment) that is shared by all users, one environment
per user, or the same environment as the hub environment. The hub
launched the `jupyterhub-singleuser` command in this environment,
which in turn starts the notebook server.
You need to make sure the version of the `jupyterhub` package matches
in both these environments. If you installed `jupyterhub` with pip,
you can upgrade it with:
```bash
python3 -m pip install --upgrade jupyterhub==<version>
```
Where `<version>` is the version of JupyterHub you are upgrading to.
If you used `conda` to install `jupyterhub`, you should upgrade it
with:
```bash
conda install -c conda-forge jupyterhub==<version>
```
You should also check for new releases of the authenticator & spawner you
are using. You might wish to upgrade those packages, too, along with JupyterHub
or upgrade them separately.
## Upgrade JupyterHub database
Once new packages are installed, you need to upgrade the JupyterHub
database. From the hub environment, in the same directory as your
`jupyterhub_config.py` file, you should run:
```bash
jupyterhub upgrade-db
```
This should find the location of your database, and run the necessary upgrades
for it.
### SQLite database disadvantages
SQLite has some disadvantages when it comes to upgrading JupyterHub. These
are:
- `upgrade-db` may not work, and you may need to delete your database
and start with a fresh one.
- `downgrade-db` **will not** work if you want to rollback to an
earlier version, so backup the `jupyterhub.sqlite` file before
upgrading.
### What happens if I delete my database?
Losing the Hub database is often not a big deal. Information that
resides only in the Hub database includes:
- active login tokens (user cookies, service tokens)
- users added via JupyterHub UI, instead of config files
- info about running servers
If the following conditions are true, you should be fine clearing the
Hub database and starting over:
- users specified in the config file, or login using an external
authentication provider (Google, GitHub, LDAP, etc)
- user servers are stopped during the upgrade
- don't mind causing users to log in again after the upgrade
## Start JupyterHub
Once the database upgrade is completed, start the `jupyterhub`
process again.
1. Log in and start the server to make sure things work as
expected.
2. Check the logs for any errors or deprecation warnings. You
might have to update your `jupyterhub_config.py` file to
deal with any deprecated options.
Congratulations, your JupyterHub has been upgraded!

155
docs/source/admin/upgrading.rst
View File

@@ -1,155 +0,0 @@
====================
Upgrading JupyterHub
====================
JupyterHub offers easy upgrade pathways between minor versions. This
document describes how to do these upgrades.
If you are using :ref:`a JupyterHub distribution <index/distributions>`, you
should consult the distribution's documentation on how to upgrade. This documentation is
for those who have set up their JupyterHub without using a distribution.
This documentation is lengthy because it is quite detailed. Most likely, upgrading
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.
Read the Changelog
==================
The `changelog <../changelog.md>`_ contains information on what has
changed with the new JupyterHub release and any deprecation warnings.
Read these notes to familiarize yourself with the coming changes. There
might be new releases of the authenticators & spawners you use, so
read the changelogs for those too!
Notify your users
=================
If you use the default configuration where ``configurable-http-proxy``
is managed by JupyterHub, your users will see service disruption during
the upgrade process. You should notify them, and pick a time to do the
upgrade where they will be least disrupted.
If you use a different proxy or run ``configurable-http-proxy``
independent of JupyterHub, your users will be able to continue using notebook
servers they had already launched, but will not be able to launch new servers or sign in.
Backup database & config
========================
Before doing an upgrade, it is critical to back up:
#. Your JupyterHub database (SQLite by default, or MySQL / Postgres if you used those).
If you use SQLite (the default), you should backup the ``jupyterhub.sqlite`` file.
#. Your ``jupyterhub_config.py`` file.
#. Your users' home directories. This is unlikely to be affected directly by
a JupyterHub upgrade, but we recommend a backup since user data is critical.
Shut down JupyterHub
====================
Shut down the JupyterHub process. This would vary depending on how you
have set up JupyterHub to run. It is most likely using a process
supervisor of some sort (``systemd`` or ``supervisord`` or even ``docker``).
Use the supervisor-specific command to stop the JupyterHub process.
Upgrade JupyterHub packages
===========================
There are two environments where the ``jupyterhub`` package is installed:
#. The *hub environment*: where the JupyterHub server process
runs. This is started with the ``jupyterhub`` command, and is what
people generally think of as JupyterHub.
#. The *notebook user environments*: where the user notebook
servers are launched from, and is probably custom to your own
installation. This could be just one environment (different from the
hub environment) that is shared by all users, one environment
per user, or the same environment as the hub environment. The hub
launched the ``jupyterhub-singleuser`` command in this environment,
which in turn starts the notebook server.
You need to make sure the version of the ``jupyterhub`` package matches
in both these environments. If you installed ``jupyterhub`` with pip,
you can upgrade it with:
.. code-block:: bash
python3 -m pip install --upgrade jupyterhub==<version>
Where ``<version>`` is the version of JupyterHub you are upgrading to.
If you used ``conda`` to install ``jupyterhub``, you should upgrade it
with:
.. code-block:: bash
conda install -c conda-forge jupyterhub==<version>
You should also check for new releases of the authenticator & spawner you
are using. You might wish to upgrade those packages, too, along with JupyterHub
or upgrade them separately.
Upgrade JupyterHub database
===========================
Once new packages are installed, you need to upgrade the JupyterHub
database. From the hub environment, in the same directory as your
``jupyterhub_config.py`` file, you should run:
.. code-block:: bash
jupyterhub upgrade-db
This should find the location of your database, and run the necessary upgrades
for it.
SQLite database disadvantages
-----------------------------
SQLite has some disadvantages when it comes to upgrading JupyterHub. These
are:
- ``upgrade-db`` may not work, and you may need to delete your database
and start with a fresh one.
- ``downgrade-db`` **will not** work if you want to rollback to an
earlier version, so backup the ``jupyterhub.sqlite`` file before
upgrading.
What happens if I delete my database?
-------------------------------------
Losing the Hub database is often not a big deal. Information that
resides only in the Hub database includes:
- active login tokens (user cookies, service tokens)
- users added via JupyterHub UI, instead of config files
- info about running servers
If the following conditions are true, you should be fine clearing the
Hub database and starting over:
- users specified in the config file, or login using an external
authentication provider (Google, GitHub, LDAP, etc)
- user servers are stopped during the upgrade
- don't mind causing users to log in again after the upgrade
Start JupyterHub
================
Once the database upgrade is completed, start the ``jupyterhub``
process again.
#. Log in and start the server to make sure things work as
expected.
#. Check the logs for any errors or deprecation warnings. You
might have to update your ``jupyterhub_config.py`` file to
deal with any deprecated options.
Congratulations, your JupyterHub has been upgraded!

17
docs/source/api/app.md Normal file
View File

@@ -0,0 +1,17 @@
# Application configuration
## Module: {mod}`jupyterhub.app`
```{eval-rst}
.. automodule:: jupyterhub.app
```
```{eval-rst}
.. currentmodule:: jupyterhub.app
```
### {class}`JupyterHub`
```{eval-rst}
.. autoconfigurable:: JupyterHub
```

15
docs/source/api/app.rst
View File

@@ -1,15 +0,0 @@
=========================
Application configuration
=========================
Module: :mod:`jupyterhub.app`
=============================
.. automodule:: jupyterhub.app
.. currentmodule:: jupyterhub.app
:class:`JupyterHub`
-------------------
.. autoconfigurable:: JupyterHub

37
docs/source/api/auth.md Normal file
View File

@@ -0,0 +1,37 @@
# Authenticators
## Module: {mod}`jupyterhub.auth`
```{eval-rst}
.. automodule:: jupyterhub.auth
```
```{eval-rst}
.. currentmodule:: jupyterhub.auth
```
### {class}`Authenticator`
```{eval-rst}
.. autoconfigurable:: Authenticator
:members:
```
### {class}`LocalAuthenticator`
```{eval-rst}
.. autoconfigurable:: LocalAuthenticator
:members:
```
### {class}`PAMAuthenticator`
```{eval-rst}
.. autoconfigurable:: PAMAuthenticator
```
### {class}`DummyAuthenticator`
```{eval-rst}
.. autoconfigurable:: DummyAuthenticator
```

32
docs/source/api/auth.rst
View File

@@ -1,32 +0,0 @@
==============
Authenticators
==============
Module: :mod:`jupyterhub.auth`
==============================
.. automodule:: jupyterhub.auth
.. currentmodule:: jupyterhub.auth
:class:`Authenticator`
----------------------
.. autoconfigurable:: Authenticator
:members:
:class:`LocalAuthenticator`
---------------------------
.. autoconfigurable:: LocalAuthenticator
:members:
:class:`PAMAuthenticator`
-------------------------
.. autoconfigurable:: PAMAuthenticator
:class:`DummyAuthenticator`
---------------------------
.. autoconfigurable:: DummyAuthenticator

35
docs/source/api/index.rst → docs/source/api/index.md
View File

@@ -1,14 +1,14 @@
.. _api-index: ---
Date: "{{ today }}"
Release: "{{ release }}"
---
############## (api-index)=
JupyterHub API
##############
:Release: |release| # JupyterHub API
:Date: |today|
JupyterHub also provides a REST API for administration of the Hub and users. JupyterHub also provides a REST API for administration of the Hub and users.
The documentation on `Using JupyterHub's REST API <../reference/rest.html>`_ provides The documentation on [Using JupyterHub's REST API](../reference/rest.html) provides
information on: information on:
- what you can do with the API - what you can do with the API
@@ -19,15 +19,14 @@ information on:
JupyterHub API Reference: JupyterHub API Reference:
.. toctree:: ```{toctree}
app
auth
spawner
proxy
user
service
services.auth
```
app [openapi initiative]: https://www.openapis.org/
auth
spawner
proxy
user
service
services.auth
.. _OpenAPI Initiative: https://www.openapis.org/

21
docs/source/api/proxy.rst → docs/source/api/proxy.md
View File

@@ -1,22 +1,25 @@
======= # Proxies
Proxies
=======
Module: :mod:`jupyterhub.proxy` ## Module: {mod}`jupyterhub.proxy`
===============================
```{eval-rst}
.. automodule:: jupyterhub.proxy .. automodule:: jupyterhub.proxy
```
```{eval-rst}
.. currentmodule:: jupyterhub.proxy .. currentmodule:: jupyterhub.proxy
```
:class:`Proxy` ### {class}`Proxy`
--------------
```{eval-rst}
.. autoconfigurable:: Proxy .. autoconfigurable:: Proxy
:members: :members:
```
:class:`ConfigurableHTTPProxy` ### {class}`ConfigurableHTTPProxy`
------------------------------
```{eval-rst}
.. autoconfigurable:: ConfigurableHTTPProxy .. autoconfigurable:: ConfigurableHTTPProxy
:members: debug, auth_token, check_running_interval, api_url, command :members: debug, auth_token, check_running_interval, api_url, command
```

16
docs/source/api/service.rst → docs/source/api/service.md
View File

@@ -1,16 +1,18 @@
======== # Services
Services
========
Module: :mod:`jupyterhub.services.service` ## Module: {mod}`jupyterhub.services.service`
==========================================
```{eval-rst}
.. automodule:: jupyterhub.services.service .. automodule:: jupyterhub.services.service
```
```{eval-rst}
.. currentmodule:: jupyterhub.services.service .. currentmodule:: jupyterhub.services.service
```
:class:`Service` ### {class}`Service`
----------------
```{eval-rst}
.. autoconfigurable:: Service .. autoconfigurable:: Service
:members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec
```

46
docs/source/api/services.auth.md Normal file
View File

@@ -0,0 +1,46 @@
# Services Authentication
## Module: {mod}`jupyterhub.services.auth`
```{eval-rst}
.. automodule:: jupyterhub.services.auth
```
```{eval-rst}
.. currentmodule:: jupyterhub.services.auth
```
### {class}`HubAuth`
```{eval-rst}
.. autoconfigurable:: HubAuth
:members:
```
### {class}`HubOAuth`
```{eval-rst}
.. autoconfigurable:: HubOAuth
:members:
```
### {class}`HubAuthenticated`
```{eval-rst}
.. autoclass:: HubAuthenticated
:members:
```
### {class}`HubOAuthenticated`
```{eval-rst}
.. autoclass:: HubOAuthenticated
```
### {class}`HubOAuthCallbackHandler`
```{eval-rst}
.. autoclass:: HubOAuthCallbackHandler
```

40
docs/source/api/services.auth.rst
View File

@@ -1,40 +0,0 @@
=======================
Services Authentication
=======================
Module: :mod:`jupyterhub.services.auth`
=======================================
.. automodule:: jupyterhub.services.auth
.. currentmodule:: jupyterhub.services.auth
:class:`HubAuth`
----------------
.. autoconfigurable:: HubAuth
:members:
:class:`HubOAuth`
-----------------
.. autoconfigurable:: HubOAuth
:members:
:class:`HubAuthenticated`
-------------------------
.. autoclass:: HubAuthenticated
:members:
:class:`HubOAuthenticated`
--------------------------
.. autoclass:: HubOAuthenticated
:class:`HubOAuthCallbackHandler`
--------------------------------
.. autoclass:: HubOAuthCallbackHandler

21
docs/source/api/spawner.rst → docs/source/api/spawner.md
View File

@@ -1,21 +1,24 @@
======== # Spawners
Spawners
========
Module: :mod:`jupyterhub.spawner` ## Module: {mod}`jupyterhub.spawner`
=================================
```{eval-rst}
.. automodule:: jupyterhub.spawner .. automodule:: jupyterhub.spawner
```
```{eval-rst}
.. currentmodule:: jupyterhub.spawner .. currentmodule:: jupyterhub.spawner
```
:class:`Spawner` ### {class}`Spawner`
----------------
```{eval-rst}
.. autoconfigurable:: Spawner .. 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, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
```
:class:`LocalProcessSpawner` ### {class}`LocalProcessSpawner`
----------------------------
```{eval-rst}
.. autoconfigurable:: LocalProcessSpawner .. autoconfigurable:: LocalProcessSpawner
```

31
docs/source/api/user.rst → docs/source/api/user.md
View File

@@ -1,36 +1,39 @@
===== # Users
Users
=====
Module: :mod:`jupyterhub.user` ## Module: {mod}`jupyterhub.user`
==============================
```{eval-rst}
.. automodule:: jupyterhub.user .. automodule:: jupyterhub.user
```
```{eval-rst}
.. currentmodule:: jupyterhub.user .. currentmodule:: jupyterhub.user
```
:class:`UserDict` ### {class}`UserDict`
-----------------
```{eval-rst}
.. autoclass:: UserDict .. autoclass:: UserDict
:members: :members:
```
:class:`User` ### {class}`User`
-------------
```{eval-rst}
.. autoclass:: User .. autoclass:: User
:members: escaped_name :members: escaped_name
.. attribute:: name .. attribute:: name
The user's name The user's name
.. attribute:: server .. attribute:: server
The user's Server data object if running, None otherwise. The user's Server data object if running, None otherwise.
Has ``ip``, ``port`` attributes. Has ``ip``, ``port`` attributes.
.. attribute:: spawner .. attribute:: spawner
The user's :class:`~.Spawner` instance. The user's :class:`~.Spawner` instance.
```

2
docs/source/conf.py
View File

@@ -39,7 +39,7 @@ extensions = [
"myst_parser", "myst_parser",
] ]
root_doc = "index" root_doc = "index"
source_suffix = [".md", ".rst"] source_suffix = [".md"]
# default_role let's use use `foo` instead of ``foo`` in rST # default_role let's use use `foo` instead of ``foo`` in rST
default_role = "literal" default_role = "literal"

76
docs/source/contributing/docs.md Normal file
View File

@@ -0,0 +1,76 @@
(contributing-docs)=
# Contributing Documentation
Documentation is often more important than code. This page helps
you get set up on how to contribute to JupyterHub's documentation.
## Building documentation locally
We use [sphinx](http://sphinx-doc.org) to build our documentation. It takes
our documentation source files (written in [markdown](https://daringfireball.net/projects/markdown/) or [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) &
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`.
2. Install the packages required to build the docs.
```bash
python3 -m pip install -r docs/requirements.txt
```
3. Build the html version of the docs. This is the most commonly used
output format, so verifying it renders correctly is usually good
enough.
```bash
cd docs
make html
```
This step will display any syntax or formatting errors in the documentation,
along with the filename / line number in which they occurred. Fix them,
and re-run the `make html` command to re-render the documentation.
4. View the rendered documentation by opening `build/html/index.html` in
a web browser.
:::{tip}
**On Windows**, you can open a file from the terminal with `start <path-to-file>`.
**On macOS**, you can do the same with `open <path-to-file>`.
**On Linux**, you can do the same with `xdg-open <path-to-file>`.
After opening index.html in your browser you can just refresh the page whenever
you rebuild the docs via `make html`
:::
(contributing-docs-conventions)=
## Documentation conventions
This section lists various conventions we use in our documentation. This is a
living document that grows over time, so feel free to add to it / change it!
Our entire documentation does not yet fully conform to these conventions yet,
so help in making it so would be appreciated!
### `pip` invocation
There are many ways to invoke a `pip` command, we recommend the following
approach:
```bash
python3 -m pip
```
This invokes pip explicitly using the python3 binary that you are
currently using. This is the **recommended way** to invoke pip
in our documentation, since it is least likely to cause problems
with python3 and pip being from different environments.
For more information on how to invoke `pip` commands, see
[the pip documentation](https://pip.pypa.io/en/stable/).

84
docs/source/contributing/docs.rst
View File

@@ -1,84 +0,0 @@
.. _contributing/docs:
==========================
Contributing Documentation
==========================
Documentation is often more important than code. This page helps
you get set up on how to contribute to JupyterHub's documentation.
Building documentation locally
==============================
We use `sphinx <http://sphinx-doc.org>`_ to build our documentation. It takes
our documentation source files (written in `markdown
<https://daringfireball.net/projects/markdown/>`_ or `reStructuredText
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ &
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.
#. Make sure you have successfully completed :ref:`contributing/setup`.
#. Install the packages required to build the docs.
.. code-block:: bash
python3 -m pip install -r docs/requirements.txt
#. Build the html version of the docs. This is the most commonly used
output format, so verifying it renders correctly is usually good
enough.
.. code-block:: bash
cd docs
make html
This step will display any syntax or formatting errors in the documentation,
along with the filename / line number in which they occurred. Fix them,
and re-run the ``make html`` command to re-render the documentation.
#. View the rendered documentation by opening ``build/html/index.html`` in
a web browser.
.. tip::
**On Windows**, you can open a file from the terminal with ``start <path-to-file>``.
**On macOS**, you can do the same with ``open <path-to-file>``.
**On Linux**, you can do the same with ``xdg-open <path-to-file>``.
After opening index.html in your browser you can just refresh the page whenever
you rebuild the docs via ``make html``
.. _contributing/docs/conventions:
Documentation conventions
=========================
This section lists various conventions we use in our documentation. This is a
living document that grows over time, so feel free to add to it / change it!
Our entire documentation does not yet fully conform to these conventions yet,
so help in making it so would be appreciated!
``pip`` invocation
------------------
There are many ways to invoke a ``pip`` command, we recommend the following
approach:
.. code-block:: bash
python3 -m pip
This invokes pip explicitly using the python3 binary that you are
currently using. This is the **recommended way** to invoke pip
in our documentation, since it is least likely to cause problems
with python3 and pip being from different environments.
For more information on how to invoke ``pip`` commands, see
`the pip documentation <https://pip.pypa.io/en/stable/>`_.

20
docs/source/contributing/index.md Normal file
View File

@@ -0,0 +1,20 @@
# Contributing
We want you to contribute to JupyterHub in ways that are most exciting
& useful to you. We value documentation, testing, bug reporting & code equally,
and are glad to have your contributions in whatever form you wish :)
Our [Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md)
([reporting guidelines](https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md))
helps keep our community welcoming to as many people as possible.
```{toctree}
:maxdepth: 2
community
setup
docs
tests
roadmap
security
```

21
docs/source/contributing/index.rst
View File

@@ -1,21 +0,0 @@
============
Contributing
============
We want you to contribute to JupyterHub in ways that are most exciting
& useful to you. We value documentation, testing, bug reporting & code equally,
and are glad to have your contributions in whatever form you wish :)
Our `Code of Conduct <https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md>`_
(`reporting guidelines <https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md>`_)
helps keep our community welcoming to as many people as possible.
.. toctree::
:maxdepth: 2
community
setup
docs
tests
roadmap
security

9
docs/source/contributing/security.md Normal file
View File

@@ -0,0 +1,9 @@
# 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 {doc}`../reference/websecurity`
or a failure in implementation,
please report it to <mailto:security@ipython.org>.
If you prefer to encrypt your security reports,
you can use {download}`this PGP public key </ipython_security.asc>`.

10
docs/source/contributing/security.rst
View File

@@ -1,10 +0,0 @@
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 :doc:`../reference/websecurity`
or a failure in implementation,
please report it to security@ipython.org.
If you prefer to encrypt your security reports,
you can use :download:`this PGP public key </ipython_security.asc>`.

176
docs/source/contributing/setup.md Normal file
View File

@@ -0,0 +1,176 @@
(contributing-setup)=
# Setting up a development install
## System requirements
JupyterHub can only run on macOS or Linux operating systems. If you are
using Windows, we recommend using [VirtualBox](https://virtualbox.org)
or a similar system to run [Ubuntu Linux](https://ubuntu.com) for
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
installed Python before, the recommended way to install it is to use
[Miniconda](https://conda.io/miniconda.html). Remember to get the ‘Python 3’ version,
and **not** the ‘Python 2’ version!
### Install nodejs
[NodeJS 12+](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
managing node dependencies.
### Install git
JupyterHub uses [Git](https://git-scm.com) & [GitHub](https://github.com)
for development & collaboration. You need to [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to work on
JupyterHub. We also recommend getting a free account on GitHub.com.
## Setting up a development install
When developing JupyterHub, you would need to make changes and be able to instantly view the results of the changes. To achieve that, a developer install is required.
:::{note}
This guide does not attempt to dictate _how_ development
environments should be isolated since that is a personal preference and can
be achieved in many ways, for example, `tox`, `conda`, `docker`, etc. See this
[forum thread](https://discourse.jupyter.org/t/thoughts-on-using-tox/3497) for
a more detailed discussion.
:::
1. Clone the [JupyterHub git repository](https://github.com/jupyterhub/jupyterhub)
to your computer.
```bash
git clone https://github.com/jupyterhub/jupyterhub
cd jupyterhub
```
2. Make sure the `python` you installed and the `npm` you installed
are available to you on the command line.
```bash
python -V
```
This should return a version number greater than or equal to 3.6.
```bash
npm -v
```
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):
```bash
npm install -g configurable-http-proxy yarn
```
If you get an error that says `Error: EACCES: permission denied`, you might need to prefix the command with `sudo`.
`sudo` may be required to perform a system-wide install.
If you do not have access to sudo, you may instead run the following commands:
```bash
npm install configurable-http-proxy yarn
export PATH=$PATH:$(pwd)/node_modules/.bin
```
The second line needs to be run every time you open a new terminal.
If you are using conda you can instead run:
```bash
conda install configurable-http-proxy yarn
```
4. Install an editable version of JupyterHub and its requirements for
development and testing. This lets you edit JupyterHub code in a text editor
& restart the JupyterHub process to see your code changes immediately.
```bash
python3 -m pip install --editable ".[test]"
```
5. Set up a database.
The default database engine is `sqlite` so if you are just trying
to get up and running quickly for local development that should be
available via [Python](https://docs.python.org/3.5/library/sqlite3.html).
See {doc}`/reference/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
`http://localhost:8000` now.
Happy developing!
## Using DummyAuthenticator & SimpleLocalProcessSpawner
To simplify testing of JupyterHub, it is helpful to use
{class}`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub
authenticator and SimpleLocalProcessSpawner instead of the default spawner.
There is a sample configuration file that does this in
`testing/jupyterhub_config.py`. To launch JupyterHub with this
configuration:
```bash
jupyterhub -f testing/jupyterhub_config.py
```
The default JupyterHub [authenticator](https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#the-default-pam-authenticator)
& [spawner](https://jupyterhub.readthedocs.io/en/stable/api/spawner.html#localprocessspawner)
require your system to have user accounts for each user you want to log in to
JupyterHub as.
DummyAuthenticator allows you to log in with any username & password,
while SimpleLocalProcessSpawner allows you to start servers without having to
create a Unix user for each JupyterHub user. Together, these make it
much easier to test JupyterHub.
Tip: If you are working on parts of JupyterHub that are common to all
authenticators & spawners, we recommend using both DummyAuthenticator &
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.
## Troubleshooting
This section lists common ways setting up your development environment may
fail, and how to fix them. Please add to the list if you encounter yet
another way it can fail!
### `lessc` not found
If the `python3 -m pip install --editable .` command fails and complains about
`lessc` being unavailable, you may need to explicitly install some
additional JavaScript dependencies:
```bash
npm install
```
This will fetch client-side JavaScript dependencies necessary to compile
CSS.
You may also need to manually update JavaScript and CSS after some
development updates, with:
```bash
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
```

187
docs/source/contributing/setup.rst
View File

@@ -1,187 +0,0 @@
.. _contributing/setup:
================================
Setting up a development install
================================
System requirements
===================
JupyterHub can only run on macOS or Linux operating systems. If you are
using Windows, we recommend using `VirtualBox <https://virtualbox.org>`_
or a similar system to run `Ubuntu Linux <https://ubuntu.com>`_ for
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
installed Python before, the recommended way to install it is to use
`Miniconda <https://conda.io/miniconda.html>`_. Remember to get the ‘Python 3’ version,
and **not** the ‘Python 2’ version!
Install nodejs
--------------
`NodeJS 12+ <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
managing node dependencies.
Install git
-----------
JupyterHub uses `Git <https://git-scm.com>`_ & `GitHub <https://github.com>`_
for development & collaboration. You need to `install git
<https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_ to work on
JupyterHub. We also recommend getting a free account on GitHub.com.
Setting up a development install
================================
When developing JupyterHub, you would need to make changes and be able to instantly view the results of the changes. To achieve that, a developer install is required.
.. note:: This guide does not attempt to dictate *how* development
environments should be isolated since that is a personal preference and can
be achieved in many ways, for example, `tox`, `conda`, `docker`, etc. See this
`forum thread <https://discourse.jupyter.org/t/thoughts-on-using-tox/3497>`_ for
a more detailed discussion.
1. Clone the `JupyterHub git repository <https://github.com/jupyterhub/jupyterhub>`_
to your computer.
.. code:: bash
git clone https://github.com/jupyterhub/jupyterhub
cd jupyterhub
2. Make sure the ``python`` you installed and the ``npm`` you installed
are available to you on the command line.
.. code:: bash
python -V
This should return a version number greater than or equal to 3.6.
.. code:: bash
npm -v
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):
.. code:: bash
npm install -g configurable-http-proxy yarn
If you get an error that says ``Error: EACCES: permission denied``, you might need to prefix the command with ``sudo``.
``sudo`` may be required to perform a system-wide install.
If you do not have access to sudo, you may instead run the following commands:
.. code:: bash
npm install configurable-http-proxy yarn
export PATH=$PATH:$(pwd)/node_modules/.bin
The second line needs to be run every time you open a new terminal.
If you are using conda you can instead run:
.. code:: bash
conda install configurable-http-proxy yarn
4. Install an editable version of JupyterHub and its requirements for
development and testing. This lets you edit JupyterHub code in a text editor
& restart the JupyterHub process to see your code changes immediately.
.. code:: bash
python3 -m pip install --editable ".[test]"
5. Set up a database.
The default database engine is ``sqlite`` so if you are just trying
to get up and running quickly for local development that should be
available via `Python <https://docs.python.org/3.5/library/sqlite3.html>`__.
See :doc:`/reference/database` for details on other supported databases.
6. You are now ready to start JupyterHub!
.. code:: bash
jupyterhub
7. You can access JupyterHub from your browser at
``http://localhost:8000`` now.
Happy developing!
Using DummyAuthenticator & SimpleLocalProcessSpawner
====================================================
To simplify testing of JupyterHub, it is helpful to use
:class:`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub
authenticator and SimpleLocalProcessSpawner instead of the default spawner.
There is a sample configuration file that does this in
``testing/jupyterhub_config.py``. To launch JupyterHub with this
configuration:
.. code:: bash
jupyterhub -f testing/jupyterhub_config.py
The default JupyterHub `authenticator
<https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#the-default-pam-authenticator>`_
& `spawner
<https://jupyterhub.readthedocs.io/en/stable/api/spawner.html#localprocessspawner>`_
require your system to have user accounts for each user you want to log in to
JupyterHub as.
DummyAuthenticator allows you to log in with any username & password,
while SimpleLocalProcessSpawner allows you to start servers without having to
create a Unix user for each JupyterHub user. Together, these make it
much easier to test JupyterHub.
Tip: If you are working on parts of JupyterHub that are common to all
authenticators & spawners, we recommend using both DummyAuthenticator &
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.
Troubleshooting
===============
This section lists common ways setting up your development environment may
fail, and how to fix them. Please add to the list if you encounter yet
another way it can fail!
``lessc`` not found
-------------------
If the ``python3 -m pip install --editable .`` command fails and complains about
``lessc`` being unavailable, you may need to explicitly install some
additional JavaScript dependencies:
.. code:: bash
npm install
This will fetch client-side JavaScript dependencies necessary to compile
CSS.
You may also need to manually update JavaScript and CSS after some
development updates, with:
.. code:: bash
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

130
docs/source/contributing/tests.md Normal file
View File

@@ -0,0 +1,130 @@
(contributing-tests)=
# Testing JupyterHub and linting code
Unit testing helps to validate that JupyterHub works the way we think it does,
and continues to do so when changes occur. They also help communicate
precisely what we expect our code to do.
JupyterHub uses [pytest](https://pytest.org) for all the tests. You
can find them under the [jupyterhub/tests](https://github.com/jupyterhub/jupyterhub/tree/main/jupyterhub/tests) directory in the git repository.
## Running the tests
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.
2. You can run all tests in JupyterHub
```bash
pytest -v jupyterhub/tests
```
This should display progress as it runs all the tests, printing
information about any test failures as they occur.
If you wish to confirm test coverage the run tests with the `--cov` flag:
```bash
pytest -v --cov=jupyterhub jupyterhub/tests
```
3. You can also run tests in just a specific file:
```bash
pytest -v jupyterhub/tests/<test-file-name>
```
4. To run a specific test only, you can do:
```bash
pytest -v jupyterhub/tests/<test-file-name>::<test-name>
```
This runs the test with function name `<test-name>` defined in
`<test-file-name>`. This is very useful when you are iteratively
developing a single test.
For example, to run the test `test_shutdown` in the file `test_api.py`,
you would run:
```bash
pytest -v jupyterhub/tests/test_api.py::test_shutdown
```
For more details, refer to the [pytest usage documentation](https://pytest.readthedocs.io/en/latest/usage.html).
## Test organisation
The tests live in `jupyterhub/tests` and are organized roughly into:
1. `test_api.py` tests the REST API
2. `test_pages.py` tests loading the HTML pages
and other collections of tests for different components.
When writing a new test, there should usually be a test of
similar functionality already written and related tests should
be added nearby.
The fixtures live in `jupyterhub/tests/conftest.py`. There are
fixtures that can be used for JupyterHub components, such as:
- `app`: an instance of JupyterHub with mocked parts
- `auth_state_enabled`: enables persisting auth_state (like authentication tokens)
- `db`: a sqlite in-memory DB session
- `` io_loop` ``: a Tornado event loop
- `event_loop`: a new asyncio event loop
- `user`: creates a new temporary user
- `admin_user`: creates a new temporary admin user
- single user servers
\- `cleanup_after`: allows cleanup of single user servers between tests
- mocked service
\- `MockServiceSpawner`: a spawner that mocks services for testing with a short poll interval
\- `` mockservice` ``: mocked service with no external service url
\- `mockservice_url`: mocked service with a url to test external services
And fixtures to add functionality or spawning behavior:
- `admin_access`: grants admin access
- `` no_patience` ``: sets slow-spawning timeouts to zero
- `slow_spawn`: enables the SlowSpawner (a spawner that takes a few seconds to start)
- `never_spawn`: enables the NeverSpawner (a spawner that will never start)
- `bad_spawn`: enables the BadSpawner (a spawner that fails immediately)
- `slow_bad_spawn`: enables the SlowBadSpawner (a spawner that fails after a short delay)
Refer to the [pytest fixtures documentation](https://pytest.readthedocs.io/en/latest/fixture.html) to learn how to use fixtures that exists already and to create new ones.
## Troubleshooting Test Failures
### 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.
## Code formatting and linting
JupyterHub automatically enforces code formatting. This means that pull requests
with changes breaking this formatting will receive a commit from pre-commit.ci
automatically.
To automatically format code locally, you can install pre-commit and register a
_git hook_ to automatically check with pre-commit before you make a commit if
the formatting is okay.
```bash
pip install pre-commit
pre-commit install --install-hooks
```
To run pre-commit manually you would do:
```bash
# check for changes to code not yet committed
pre-commit run
# check for changes also in already committed code
pre-commit run --all-files
```
You may also install [black integration](https://github.com/psf/black#editor-integration)
into your text editor to format code automatically.

138
docs/source/contributing/tests.rst
View File

@@ -1,138 +0,0 @@
.. _contributing/tests:
===================================
Testing JupyterHub and linting code
===================================
Unit testing helps to validate that JupyterHub works the way we think it does,
and continues to do so when changes occur. They also help communicate
precisely what we expect our code to do.
JupyterHub uses `pytest <https://pytest.org>`_ for all the tests. You
can find them under the `jupyterhub/tests <https://github.com/jupyterhub/jupyterhub/tree/main/jupyterhub/tests>`_ directory in the git repository.
Running the tests
==================
#. 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.
#. You can run all tests in JupyterHub
.. code-block:: bash
pytest -v jupyterhub/tests
This should display progress as it runs all the tests, printing
information about any test failures as they occur.
If you wish to confirm test coverage the run tests with the `--cov` flag:
.. code-block:: bash
pytest -v --cov=jupyterhub jupyterhub/tests
#. You can also run tests in just a specific file:
.. code-block:: bash
pytest -v jupyterhub/tests/<test-file-name>
#. To run a specific test only, you can do:
.. code-block:: bash
pytest -v jupyterhub/tests/<test-file-name>::<test-name>
This runs the test with function name ``<test-name>`` defined in
``<test-file-name>``. This is very useful when you are iteratively
developing a single test.
For example, to run the test ``test_shutdown`` in the file ``test_api.py``,
you would run:
.. code-block:: bash
pytest -v jupyterhub/tests/test_api.py::test_shutdown
For more details, refer to the `pytest usage documentation <https://pytest.readthedocs.io/en/latest/usage.html>`_.
Test organisation
=================
The tests live in ``jupyterhub/tests`` and are organized roughly into:
#. ``test_api.py`` tests the REST API
#. ``test_pages.py`` tests loading the HTML pages
and other collections of tests for different components.
When writing a new test, there should usually be a test of
similar functionality already written and related tests should
be added nearby.
The fixtures live in ``jupyterhub/tests/conftest.py``. There are
fixtures that can be used for JupyterHub components, such as:
- ``app``: an instance of JupyterHub with mocked parts
- ``auth_state_enabled``: enables persisting auth_state (like authentication tokens)
- ``db``: a sqlite in-memory DB session
- ``io_loop```: a Tornado event loop
- ``event_loop``: a new asyncio event loop
- ``user``: creates a new temporary user
- ``admin_user``: creates a new temporary admin user
- single user servers
- ``cleanup_after``: allows cleanup of single user servers between tests
- mocked service
- ``MockServiceSpawner``: a spawner that mocks services for testing with a short poll interval
- ``mockservice```: mocked service with no external service url
- ``mockservice_url``: mocked service with a url to test external services
And fixtures to add functionality or spawning behavior:
- ``admin_access``: grants admin access
- ``no_patience```: sets slow-spawning timeouts to zero
- ``slow_spawn``: enables the SlowSpawner (a spawner that takes a few seconds to start)
- ``never_spawn``: enables the NeverSpawner (a spawner that will never start)
- ``bad_spawn``: enables the BadSpawner (a spawner that fails immediately)
- ``slow_bad_spawn``: enables the SlowBadSpawner (a spawner that fails after a short delay)
Refer to the `pytest fixtures documentation <https://pytest.readthedocs.io/en/latest/fixture.html>`_ to learn how to use fixtures that exists already and to create new ones.
Troubleshooting Test Failures
=============================
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.
Code formatting and linting
===========================
JupyterHub automatically enforces code formatting. This means that pull requests
with changes breaking this formatting will receive a commit from pre-commit.ci
automatically.
To automatically format code locally, you can install pre-commit and register a
*git hook* to automatically check with pre-commit before you make a commit if
the formatting is okay.
.. code:: bash
pip install pre-commit
pre-commit install --install-hooks
To run pre-commit manually you would do:
.. code:: bash
# check for changes to code not yet committed
pre-commit run
# check for changes also in already committed code
pre-commit run --all-files
You may also install `black integration <https://github.com/psf/black#editor-integration>`_
into your text editor to format code automatically.

42
docs/source/events/index.md Normal file
View File

@@ -0,0 +1,42 @@
# 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].
## 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.
To begin recording events, you'll need to set two configurations:
> 1. `handlers`: tells the EventLog _where_ to route your events. This trait is a list of Python logging handlers that route events to the event log file.
> 2. `allows_schemas`: tells the EventLog _which_ events should be recorded. No events are emitted by default; all recorded events must be listed here.
Here's a basic example:
```
import logging
c.EventLog.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.
(page)=
## Event schemas
```{toctree}
:maxdepth: 2
server-actions.rst
```
[json schemas]: https://json-schema.org/
[logging]: https://docs.python.org/3/library/logging.html
[telemetry system]: https://github.com/jupyter/telemetry

46
docs/source/events/index.rst
View File

@@ -1,46 +0,0 @@
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_.
.. _logging: https://docs.python.org/3/library/logging.html
.. _`Telemetry System`: https://github.com/jupyter/telemetry
.. _`JSON schemas`: https://json-schema.org/
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.
To begin recording events, you'll need to set two configurations:
1. ``handlers``: tells the EventLog *where* to route your events. This trait is a list of Python logging handlers that route events to the event log file.
2. ``allows_schemas``: tells the EventLog *which* events should be recorded. No events are emitted by default; all recorded events must be listed here.
Here's a basic example:
.. code-block::
import logging
c.EventLog.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.
.. _page:
Event schemas
-------------
.. toctree::
:maxdepth: 2
server-actions.rst

2
docs/source/events/server-actions.rst → docs/source/events/server-actions.md
View File

@@ -1 +1,3 @@
```{eval-rst}
.. jsonschema:: ../../../jupyterhub/event-schemas/server-actions/v1.yaml .. jsonschema:: ../../../jupyterhub/event-schemas/server-actions/v1.yaml
```

24
docs/source/getting-started/index.rst → docs/source/getting-started/index.md
View File

@@ -1,19 +1,19 @@
Get Started # Get Started
===========
This section covers how to configure and customize JupyterHub for your This section covers how to configure and customize JupyterHub for your
needs. It contains information about authentication, networking, security, and needs. It contains information about authentication, networking, security, and
other topics that are relevant to individuals or organizations deploying their other topics that are relevant to individuals or organizations deploying their
own JupyterHub. own JupyterHub.
.. toctree:: ```{toctree}
:maxdepth: 2 :maxdepth: 2
config-basics config-basics
networking-basics networking-basics
security-basics security-basics
authenticators-users-basics authenticators-users-basics
spawners-basics spawners-basics
services-basics services-basics
faq faq
institutional-faq institutional-faq
```

234
docs/source/getting-started/security-basics.md Normal file
View File

@@ -0,0 +1,234 @@
# Security settings
:::{important}
You should not run JupyterHub without SSL encryption on a public network.
:::
Security is the most important aspect of configuring Jupyter.
Three (3) configuration settings are the main aspects of security configuration:
1. {ref}`SSL encryption <ssl-encryption>` (to enable HTTPS)
2. {ref}`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
3. Proxy {ref}`authentication token <authentication-token>` (used for the Hub and
other services to authenticate to the Proxy)
The Hub hashes all secrets (e.g. auth tokens) before storing them in its
database. A loss of control over read-access to the database should have
minimal impact on your deployment. If your database has been compromised, it
is still a good idea to revoke existing tokens.
(ssl-encryption)=
## Enabling SSL encryption
Since JupyterHub includes authentication and allows arbitrary code execution,
you should not run it without SSL (HTTPS).
### Using an SSL certificate
This will require you to obtain an official, trusted SSL certificate or create a
self-signed certificate. Once you have obtained and installed a key and
certificate, you need to specify their locations in the `jupyterhub_config.py`
configuration file as follows:
```python
c.JupyterHub.ssl_key = '/path/to/my.key'
c.JupyterHub.ssl_cert = '/path/to/my.cert'
```
Some cert files also contain the key, in which case only the cert is needed. It
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.html).
### Using letsencrypt
It is also possible to use [letsencrypt](https://letsencrypt.org/) to obtain
a free, trusted SSL certificate. If you run letsencrypt using the default
options, the needed configuration is (replace `mydomain.tld` by your fully
qualified domain name):
```python
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/{mydomain.tld}/fullchain.pem'
```
If the fully qualified domain name (FQDN) is `example.com`, the following
would be the needed configuration:
```python
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
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/),
it is reasonable to run the hub without SSL.
To achieve this, remove `c.JupyterHub.ssl_key` and `c.JupyterHub.ssl_cert`
from your configuration (setting them to `None` or an empty string does not
have the same effect, and will result in an error).
(authentication-token)=
## Proxy authentication token
The Hub authenticates its requests to the Proxy using a secret token that
the Hub and Proxy agree upon. Note that this applies to the default
`ConfigurableHTTPProxy` implementation. Not all proxy implementations
use an auth token.
The value of this token should be a random string (for example, generated by
`openssl rand -hex 32`). You can store it in the configuration file or an
environment variable.
### Generating and storing token in the configuration file
You can set the value in the configuration file, `jupyterhub_config.py`:
```python
c.ConfigurableHTTPProxy.api_token = 'abc123...' # any random string
```
### Generating and storing as an environment variable
You can pass this value of the proxy authentication token to the Hub and Proxy
using the `CONFIGPROXY_AUTH_TOKEN` environment variable:
```bash
export CONFIGPROXY_AUTH_TOKEN=$(openssl rand -hex 32)
```
This environment variable needs to be visible to the Hub and Proxy.
### Default if token is not set
If you do not set the Proxy authentication token, the Hub will generate a random
key itself. This means that any time you restart the Hub, you **must also
restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen
automatically (this is the default configuration).
(cookie-secret)=
## Cookie secret
The cookie secret is an encryption key, used to encrypt the browser cookies,
which are used for authentication. Three common methods are described for
generating and configuring the cookie secret.
### Generating and storing as a cookie secret file
The cookie secret should be 32 random bytes, encoded as hex, and is typically
stored in a `jupyterhub_cookie_secret` file. Below, is an example command to generate the
`jupyterhub_cookie_secret` file:
```bash
openssl rand -hex 32 > /srv/jupyterhub/jupyterhub_cookie_secret
```
In most deployments of JupyterHub, you should point this to a secure location on
the file system, such as `/srv/jupyterhub/jupyterhub_cookie_secret`.
The location of the `jupyterhub_cookie_secret` file can be specified in the
`jupyterhub_config.py` file as follows:
```python
c.JupyterHub.cookie_secret_file = '/srv/jupyterhub/jupyterhub_cookie_secret'
```
If the cookie secret file doesn't exist when the Hub starts, a new cookie
secret is generated and stored in the file. The file must not be readable by
`group` or `other`, otherwise the server won't start. The recommended permissions
for the cookie secret file are `600` (owner-only rw).
### Generating and storing as an environment variable
If you would like to avoid the need for files, the value can be loaded in the
Hub process from the `JPY_COOKIE_SECRET` environment variable, which is a
hex-encoded string. You can set it this way:
```bash
export JPY_COOKIE_SECRET=$(openssl rand -hex 32)
```
For security reasons, this environment variable should only be visible to the
Hub. If you set it dynamically as above, all users will be logged out each time
the Hub starts.
### Generating and storing as a binary string
You can also set the cookie secret, as a binary string,
in the configuration file (`jupyterhub_config.py`) itself:
```python
c.JupyterHub.cookie_secret = bytes.fromhex('64 CHAR HEX STRING')
```
(cookies)=
## Cookies used by JupyterHub authentication
The following cookies are used by the Hub for handling user authentication.
This section was created based on this [post] from Discourse.
### jupyterhub-hub-login
This is the login token used when visiting Hub-served pages that are
protected by authentication, such as the main home, the spawn form, etc.
If this cookie is set, then the user is logged in.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path `/hub/`.
### jupyterhub-user-\<username>
This is the cookie used for authenticating with a single-user server.
It is set by the single-user server, after OAuth with the Hub.
Effectively the same as `jupyterhub-hub-login`, but for the
single-user server instead of the Hub. It contains an OAuth access token,
which is checked with the Hub to authenticate the browser.
Each OAuth access token is associated with a session id (see `jupyterhub-session-id` section
below).
To avoid hitting the Hub on every request, the authentication response is cached.
The cache key is comprised of both the token and session id, to avoid a stale cache.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path `/user/<username>`,
to ensure that only the user’s server receives it.
### jupyterhub-session-id
This is a random string, meaningless in itself, and the only cookie
shared by the Hub and single-user servers.
Its sole purpose is to coordinate the logout of the multiple OAuth cookies.
This cookie is set to `/` so all endpoints can receive it, clear it, etc.
### jupyterhub-user-\<username>-oauth-state
A short-lived cookie, used solely to store and validate OAuth state.
It is only set while OAuth between the single-user server and the Hub
is processing.
If you use your browser development tools, you should see this cookie
for a very brief moment before you are logged in,
with an expiration date shorter than `jupyterhub-hub-login` or
`jupyterhub-user-<username>`.
This cookie should not exist after you have successfully logged in.
This cookie is restricted to the path `/user/<username>`, so that only
the user’s server receives it.
[post]: https://discourse.jupyter.org/t/how-to-force-re-login-for-users/1998/6

254
docs/source/getting-started/security-basics.rst
View File

@@ -1,254 +0,0 @@
Security settings
=================
.. important::
You should not run JupyterHub without SSL encryption on a public network.
Security is the most important aspect of configuring Jupyter.
Three (3) configuration settings are the main aspects of security configuration:
1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
3. Proxy :ref:`authentication token <authentication-token>` (used for the Hub and
other services to authenticate to the Proxy)
The Hub hashes all secrets (e.g. auth tokens) before storing them in its
database. A loss of control over read-access to the database should have
minimal impact on your deployment. If your database has been compromised, it
is still a good idea to revoke existing tokens.
.. _ssl-encryption:
Enabling SSL encryption
-----------------------
Since JupyterHub includes authentication and allows arbitrary code execution,
you should not run it without SSL (HTTPS).
Using an SSL certificate
~~~~~~~~~~~~~~~~~~~~~~~~
This will require you to obtain an official, trusted SSL certificate or create a
self-signed certificate. Once you have obtained and installed a key and
certificate, you need to specify their locations in the ``jupyterhub_config.py``
configuration file as follows:
.. code-block:: python
c.JupyterHub.ssl_key = '/path/to/my.key'
c.JupyterHub.ssl_cert = '/path/to/my.cert'
Some cert files also contain the key, in which case only the cert is needed. It
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.html>`_.
Using letsencrypt
~~~~~~~~~~~~~~~~~
It is also possible to use `letsencrypt <https://letsencrypt.org/>`_ to obtain
a free, trusted SSL certificate. If you run letsencrypt using the default
options, the needed configuration is (replace ``mydomain.tld`` by your fully
qualified domain name):
.. code-block:: python
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/{mydomain.tld}/fullchain.pem'
If the fully qualified domain name (FQDN) is ``example.com``, the following
would be the needed configuration:
.. code-block:: python
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
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/>`_,
it is reasonable to run the hub without SSL.
To achieve this, remove ``c.JupyterHub.ssl_key`` and ``c.JupyterHub.ssl_cert``
from your configuration (setting them to ``None`` or an empty string does not
have the same effect, and will result in an error).
.. _authentication-token:
Proxy authentication token
--------------------------
The Hub authenticates its requests to the Proxy using a secret token that
the Hub and Proxy agree upon. Note that this applies to the default
``ConfigurableHTTPProxy`` implementation. Not all proxy implementations
use an auth token.
The value of this token should be a random string (for example, generated by
``openssl rand -hex 32``). You can store it in the configuration file or an
environment variable.
Generating and storing token in the configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can set the value in the configuration file, ``jupyterhub_config.py``:
.. code-block:: python
c.ConfigurableHTTPProxy.api_token = 'abc123...' # any random string
Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can pass this value of the proxy authentication token to the Hub and Proxy
using the ``CONFIGPROXY_AUTH_TOKEN`` environment variable:
.. code-block:: bash
export CONFIGPROXY_AUTH_TOKEN=$(openssl rand -hex 32)
This environment variable needs to be visible to the Hub and Proxy.
Default if token is not set
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you do not set the Proxy authentication token, the Hub will generate a random
key itself. This means that any time you restart the Hub, you **must also
restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen
automatically (this is the default configuration).
.. _cookie-secret:
Cookie secret
-------------
The cookie secret is an encryption key, used to encrypt the browser cookies,
which are used for authentication. Three common methods are described for
generating and configuring the cookie secret.
Generating and storing as a cookie secret file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The cookie secret should be 32 random bytes, encoded as hex, and is typically
stored in a ``jupyterhub_cookie_secret`` file. Below, is an example command to generate the
``jupyterhub_cookie_secret`` file:
.. code-block:: bash
openssl rand -hex 32 > /srv/jupyterhub/jupyterhub_cookie_secret
In most deployments of JupyterHub, you should point this to a secure location on
the file system, such as ``/srv/jupyterhub/jupyterhub_cookie_secret``.
The location of the ``jupyterhub_cookie_secret`` file can be specified in the
``jupyterhub_config.py`` file as follows:
.. code-block:: python
c.JupyterHub.cookie_secret_file = '/srv/jupyterhub/jupyterhub_cookie_secret'
If the cookie secret file doesn't exist when the Hub starts, a new cookie
secret is generated and stored in the file. The file must not be readable by
``group`` or ``other``, otherwise the server won't start. The recommended permissions
for the cookie secret file are ``600`` (owner-only rw).
Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you would like to avoid the need for files, the value can be loaded in the
Hub process from the ``JPY_COOKIE_SECRET`` environment variable, which is a
hex-encoded string. You can set it this way:
.. code-block:: bash
export JPY_COOKIE_SECRET=$(openssl rand -hex 32)
For security reasons, this environment variable should only be visible to the
Hub. If you set it dynamically as above, all users will be logged out each time
the Hub starts.
Generating and storing as a binary string
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also set the cookie secret, as a binary string,
in the configuration file (``jupyterhub_config.py``) itself:
.. code-block:: python
c.JupyterHub.cookie_secret = bytes.fromhex('64 CHAR HEX STRING')
.. _cookies:
Cookies used by JupyterHub authentication
-----------------------------------------
The following cookies are used by the Hub for handling user authentication.
This section was created based on this post_ from Discourse.
.. _post: https://discourse.jupyter.org/t/how-to-force-re-login-for-users/1998/6
jupyterhub-hub-login
~~~~~~~~~~~~~~~~~~~~
This is the login token used when visiting Hub-served pages that are
protected by authentication, such as the main home, the spawn form, etc.
If this cookie is set, then the user is logged in.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path ``/hub/``.
jupyterhub-user-<username>
~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the cookie used for authenticating with a single-user server.
It is set by the single-user server, after OAuth with the Hub.
Effectively the same as ``jupyterhub-hub-login``, but for the
single-user server instead of the Hub. It contains an OAuth access token,
which is checked with the Hub to authenticate the browser.
Each OAuth access token is associated with a session id (see ``jupyterhub-session-id`` section
below).
To avoid hitting the Hub on every request, the authentication response is cached.
The cache key is comprised of both the token and session id, to avoid a stale cache.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path ``/user/<username>``,
to ensure that only the user’s server receives it.
jupyterhub-session-id
~~~~~~~~~~~~~~~~~~~~~
This is a random string, meaningless in itself, and the only cookie
shared by the Hub and single-user servers.
Its sole purpose is to coordinate the logout of the multiple OAuth cookies.
This cookie is set to ``/`` so all endpoints can receive it, clear it, etc.
jupyterhub-user-<username>-oauth-state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A short-lived cookie, used solely to store and validate OAuth state.
It is only set while OAuth between the single-user server and the Hub
is processing.
If you use your browser development tools, you should see this cookie
for a very brief moment before you are logged in,
with an expiration date shorter than ``jupyterhub-hub-login`` or
``jupyterhub-user-<username>``.
This cookie should not exist after you have successfully logged in.
This cookie is restricted to the path ``/user/<username>``, so that only
the user’s server receives it.

17
docs/source/index-about.rst → docs/source/index-about.md
View File

@@ -1,15 +1,14 @@
===== # About
About
=====
JupyterHub is an open source project and community. It is a part of the JupyterHub is an open source project and community. It is a part of the
`Jupyter Project <https://jupyter.org>`_. JupyterHub is an open and inclusive [Jupyter Project](https://jupyter.org). JupyterHub is an open and inclusive
community, and invites contributions from anyone. This section covers information community, and invites contributions from anyone. This section covers information
about our community, as well as ways that you can connect and get involved. about our community, as well as ways that you can connect and get involved.
.. toctree:: ```{toctree}
:maxdepth: 1 :maxdepth: 1
contributor-list contributor-list
changelog changelog
gallery-jhub-deployments gallery-jhub-deployments
```

14
docs/source/index-admin.md Normal file
View File

@@ -0,0 +1,14 @@
# Administrator's Guide
This guide covers best-practices, tips, common questions and operations, as
well as other information relevant to running your own JupyterHub over time.
```{toctree}
:maxdepth: 2
troubleshooting
admin/capacity-planning
admin/upgrading
admin/log-messages
changelog
```

15
docs/source/index-admin.rst
View File

@@ -1,15 +0,0 @@
=====================
Administrator's Guide
=====================
This guide covers best-practices, tips, common questions and operations, as
well as other information relevant to running your own JupyterHub over time.
.. toctree::
:maxdepth: 2
troubleshooting
admin/capacity-planning
admin/upgrading
admin/log-messages
changelog

155
docs/source/index.md Normal file
View File

@@ -0,0 +1,155 @@
# JupyterHub
[JupyterHub] is the best way to serve [Jupyter notebook] for multiple users.
Because JupyterHub manages a separate Jupyter environment for each user,
it can be used in a class of students, a corporate data science group, or a scientific
research group. It is a multi-user **Hub** that spawns, manages, and proxies multiple
instances of the single-user [Jupyter notebook] server.
JupyterHub offers distributions for different use cases. As of now, you can find two main cases:
1. [The Littlest JupyterHub](https://github.com/jupyterhub/the-littlest-jupyterhub) distribution is suitable if you need a small number of users (1-100) and a single server with a simple environment.
2. [Zero to JupyterHub with Kubernetes](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) allows you to deploy dynamic servers on the cloud if you need even more users.
JupyterHub can be used in a collaborative environment by both both small (0-100 users) and
large teams (more than 100 users) such as a class of students, corporate data science group
or scientific research group. It has distributions which are developed to serve the needs of
each of these teams respectively.
JupyterHub is made up of four subsystems:
- a **Hub** (tornado process) that is the heart of JupyterHub
- a **configurable http proxy** (node-http-proxy) that receives the requests from the client's browser
- multiple **single-user Jupyter notebook servers** (Python/IPython/tornado) that are monitored by Spawners
- an **authentication class** that manages how users can access the system
Additionally, optional configurations can be added through a `config.py` file and manage users
kernels on an admin panel. A simplification of the whole system is displayed in the figure below:
```{image} images/jhub-fluxogram.jpeg
:align: center
:alt: JupyterHub subsystems
:width: 80%
```
JupyterHub performs the following functions:
- The Hub launches a proxy
- The proxy forwards all requests to the Hub by default
- The Hub handles user login and spawns single-user servers on demand
- The Hub configures the proxy to forward URL prefixes to the single-user
notebook servers
For convenient administration of the Hub, its users, and services,
JupyterHub also provides a {doc}`REST API <reference/rest-api>`.
The JupyterHub team and Project Jupyter value our community, and JupyterHub
follows the Jupyter [Community Guides](https://jupyter.readthedocs.io/en/latest/community/content-community.html).
## Contents
(index-distributions)=
### Distributions
A JupyterHub **distribution** is tailored
towards a particular set of use cases. These are generally easier
to set up than setting up JupyterHub from scratch, assuming they fit your use case.
Today, you can find two main use cases:
1. If you need a simple case for a small amount of users (0-100) and single server
take a look at
[The Littlest JupyterHub](https://github.com/jupyterhub/the-littlest-jupyterhub) distribution.
2. If you need to allow for a larger number of machines and users,
a dynamic amount of servers can be used on a cloud,
take a look at the [Zero to JupyterHub with Kubernetes](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) distribution.
This distribution runs JupyterHub on top of [Kubernetes](https://k8s.io).
_It is important to evaluate these distributions before you can continue with the
configuration of JupyterHub_.
### Installation Guide
```{toctree}
:maxdepth: 2
installation-guide
```
### Getting Started
```{toctree}
:maxdepth: 2
getting-started/index
```
### Technical Reference
```{toctree}
:maxdepth: 2
reference/index
```
### Administrators guide
```{toctree}
:maxdepth: 2
index-admin
```
### API Reference
```{toctree}
:maxdepth: 2
api/index
```
### RBAC Reference
```{toctree}
:maxdepth: 2
rbac/index
```
### Contributing
We welcome you to contribute to JupyterHub in ways that are most exciting
& useful to you. We value documentation, testing, bug reporting & code equally
and are glad to have your contributions in whatever form you wish :)
Our [Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md) and [reporting guidelines](https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md)
help keep our community welcoming to as many people as possible.
```{toctree}
:maxdepth: 2
contributing/index
```
### About JupyterHub
```{toctree}
:maxdepth: 2
index-about
```
## Indices and tables
- {ref}`genindex`
- {ref}`modindex`
## Questions? Suggestions?
All questions and suggestions are welcome. Please feel free to use our [Jupyter Discourse Forum](https://discourse.jupyter.org/) to contact our team.
Looking forward to hearing from you!
[jupyter notebook]: https://jupyter-notebook.readthedocs.io/en/latest/
[jupyterhub]: https://github.com/jupyterhub/jupyterhub

161
docs/source/index.rst
View File

@@ -1,161 +0,0 @@
==========
JupyterHub
==========
`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users.
Because JupyterHub manages a separate Jupyter environment for each user,
it can be used in a class of students, a corporate data science group, or a scientific
research group. It is a multi-user **Hub** that spawns, manages, and proxies multiple
instances of the single-user `Jupyter notebook`_ server.
JupyterHub offers distributions for different use cases. As of now, you can find two main cases:
1. `The Littlest JupyterHub <https://github.com/jupyterhub/the-littlest-jupyterhub>`__ distribution is suitable if you need a small number of users (1-100) and a single server with a simple environment.
2. `Zero to JupyterHub with Kubernetes <https://github.com/jupyterhub/zero-to-jupyterhub-k8s>`__ allows you to deploy dynamic servers on the cloud if you need even more users.
JupyterHub can be used in a collaborative environment by both both small (0-100 users) and
large teams (more than 100 users) such as a class of students, corporate data science group
or scientific research group. It has distributions which are developed to serve the needs of
each of these teams respectively.
JupyterHub is made up of four subsystems:
* a **Hub** (tornado process) that is the heart of JupyterHub
* a **configurable http proxy** (node-http-proxy) that receives the requests from the client's browser
* multiple **single-user Jupyter notebook servers** (Python/IPython/tornado) that are monitored by Spawners
* an **authentication class** that manages how users can access the system
Additionally, optional configurations can be added through a `config.py` file and manage users
kernels on an admin panel. A simplification of the whole system is displayed in the figure below:
.. image:: images/jhub-fluxogram.jpeg
:alt: JupyterHub subsystems
:width: 80%
:align: center
JupyterHub performs the following functions:
- The Hub launches a proxy
- The proxy forwards all requests to the Hub by default
- The Hub handles user login and spawns single-user servers on demand
- The Hub configures the proxy to forward URL prefixes to the single-user
notebook servers
For convenient administration of the Hub, its users, and services,
JupyterHub also provides a :doc:`REST API <reference/rest-api>`.
The JupyterHub team and Project Jupyter value our community, and JupyterHub
follows the Jupyter `Community Guides <https://jupyter.readthedocs.io/en/latest/community/content-community.html>`_.
Contents
========
.. _index/distributions:
Distributions
-------------
A JupyterHub **distribution** is tailored
towards a particular set of use cases. These are generally easier
to set up than setting up JupyterHub from scratch, assuming they fit your use case.
Today, you can find two main use cases:
1. If you need a simple case for a small amount of users (0-100) and single server
take a look at
`The Littlest JupyterHub <https://github.com/jupyterhub/the-littlest-jupyterhub>`__ distribution.
2. If you need to allow for a larger number of machines and users,
a dynamic amount of servers can be used on a cloud,
take a look at the `Zero to JupyterHub with Kubernetes <https://github.com/jupyterhub/zero-to-jupyterhub-k8s>`__ distribution.
This distribution runs JupyterHub on top of `Kubernetes <https://k8s.io>`_.
*It is important to evaluate these distributions before you can continue with the
configuration of JupyterHub*.
Installation Guide
------------------
.. toctree::
:maxdepth: 2
installation-guide
Getting Started
---------------
.. toctree::
:maxdepth: 2
getting-started/index
Technical Reference
-------------------
.. toctree::
:maxdepth: 2
reference/index
Administrators guide
--------------------
.. toctree::
:maxdepth: 2
index-admin
API Reference
-------------
.. toctree::
:maxdepth: 2
api/index
RBAC Reference
--------------
.. toctree::
:maxdepth: 2
rbac/index
Contributing
------------
We welcome you to contribute to JupyterHub in ways that are most exciting
& useful to you. We value documentation, testing, bug reporting & code equally
and are glad to have your contributions in whatever form you wish :)
Our `Code of Conduct <https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md>`_ and `reporting guidelines <https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md>`_
help keep our community welcoming to as many people as possible.
.. toctree::
:maxdepth: 2
contributing/index
About JupyterHub
----------------
.. toctree::
:maxdepth: 2
index-about
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
Questions? Suggestions?
=======================
All questions and suggestions are welcome. Please feel free to use our `Jupyter Discourse Forum <https://discourse.jupyter.org/>`_ to contact our team.
Looking forward to hearing from you!
.. _JupyterHub: https://github.com/jupyterhub/jupyterhub
.. _Jupyter notebook: https://jupyter-notebook.readthedocs.io/en/latest/

7
docs/source/installation-guide-hard.md Normal file
View File

@@ -0,0 +1,7 @@
---
orphan: true
---
# JupyterHub the hard way
This guide has moved to <https://github.com/jupyterhub/jupyterhub-the-hard-way/blob/HEAD/docs/installation-guide-hard.md>

6
docs/source/installation-guide-hard.rst
View File

@@ -1,6 +0,0 @@
:orphan:
JupyterHub the hard way
=======================
This guide has moved to https://github.com/jupyterhub/jupyterhub-the-hard-way/blob/HEAD/docs/installation-guide-hard.md

14
docs/source/installation-guide.rst → docs/source/installation-guide.md
View File

@@ -1,13 +1,13 @@
Installation # Installation
============
These sections cover how to get up-and-running with JupyterHub. They cover These sections cover how to get up-and-running with JupyterHub. They cover
some basics of the tools needed to deploy JupyterHub as well as how to get it some basics of the tools needed to deploy JupyterHub as well as how to get it
running on your own infrastructure. running on your own infrastructure.
.. toctree:: ```{toctree}
:maxdepth: 3 :maxdepth: 3
quickstart quickstart
quickstart-docker quickstart-docker
installation-basics installation-basics
```

65
docs/source/quickstart-docker.md Normal file
View File

@@ -0,0 +1,65 @@
# 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.
:::{note}
This `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
not, [JupyterLab](https://jupyterlab.readthedocs.io/) or Jupyter Notebook must be installed.
:::
:::{important}
We strongly recommend that you follow the [Zero to JupyterHub] tutorial to
install JupyterHub.
:::
## Prerequisites
You should have [Docker] installed on a Linux/Unix based system.
## Run the Docker Image
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
```
This command exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console.
You can stop and resume the container by running `docker stop` and `docker start` respectively.
```
# find the container id
docker ps
# stop the running container
docker stop <container-id>
# resume the paused container
docker start <container-id>
```
If you want to run docker on a computer that has a public IP then you should
(as in MUST) **secure it with ssl** by adding ssl options to your docker
configuration or using an ssl enabled proxy.
[Mounting volumes](https://docs.docker.com/engine/admin/volumes/volumes/)
enables you to persist and store the data generated by the docker container, even when you stop the container.
The persistent data can be stored on the host system, outside the container.
## Create System Users
Spawn a root shell in your docker container by running this command in the terminal.:
```
docker exec -it jupyterhub bash
```
The created accounts will be used for authentication in JupyterHub's default
configuration.
[docker]: https://www.docker.com/
[zero to jupyterhub]: https://zero-to-jupyterhub.readthedocs.io/en/latest/

69
docs/source/quickstart-docker.rst
View File

@@ -1,69 +0,0 @@
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.
.. note::
This ``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
not, `JupyterLab <https://jupyterlab.readthedocs.io/>`_ or Jupyter Notebook must be installed.
.. important::
We strongly recommend that you follow the `Zero to JupyterHub`_ tutorial to
install JupyterHub.
Prerequisites
-------------
You should have `Docker`_ installed on a Linux/Unix based system.
Run the Docker Image
--------------------
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
This command exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console.
You can stop and resume the container by running `docker stop` and `docker start` respectively.
::
# find the container id
docker ps
# stop the running container
docker stop <container-id>
# resume the paused container
docker start <container-id>
If you want to run docker on a computer that has a public IP then you should
(as in MUST) **secure it with ssl** by adding ssl options to your docker
configuration or using an ssl enabled proxy.
`Mounting volumes <https://docs.docker.com/engine/admin/volumes/volumes/>`_
enables you to persist and store the data generated by the docker container, even when you stop the container.
The persistent data can be stored on the host system, outside the container.
Create System Users
-------------------
Spawn a root shell in your docker container by running this command in the terminal.::
docker exec -it jupyterhub bash
The created accounts will be used for authentication in JupyterHub's default
configuration.
.. _Zero to JupyterHub: https://zero-to-jupyterhub.readthedocs.io/en/latest/
.. _Docker: https://www.docker.com/

29
docs/source/reference/config-reference.md Normal file
View File

@@ -0,0 +1,29 @@
# Configuration Reference
:::{important}
Make sure the version of JupyterHub for this documentation matches your
installation version, as the output of this command may change between versions.
:::
## JupyterHub configuration
As explained in the [Configuration Basics](../getting-started/config-basics.html#generate-a-default-config-file)
section, the `jupyterhub_config.py` can be automatically generated via
> ```bash
> jupyterhub --generate-config
> ```
The following contains the output of that command for reference.
```{eval-rst}
.. jupyterhub-generate-config::
```
## JupyterHub help command output
This section contains the output of the command `jupyterhub --help-all`.
```{eval-rst}
.. jupyterhub-help-all::
```

30
docs/source/reference/config-reference.rst
View File

@@ -1,30 +0,0 @@
==============================
Configuration Reference
==============================
.. important::
Make sure the version of JupyterHub for this documentation matches your
installation version, as the output of this command may change between versions.
JupyterHub configuration
------------------------
As explained in the `Configuration Basics <../getting-started/config-basics.html#generate-a-default-config-file>`_
section, the ``jupyterhub_config.py`` can be automatically generated via
.. code-block:: bash
jupyterhub --generate-config
The following contains the output of that command for reference.
.. jupyterhub-generate-config::
JupyterHub help command output
------------------------------
This section contains the output of the command ``jupyterhub --help-all``.
.. jupyterhub-help-all::

32
docs/source/reference/index.md Normal file
View File

@@ -0,0 +1,32 @@
# Technical Reference
This section covers more of the details of the JupyterHub architecture, as well as
what happens under-the-hood when you deploy and configure your JupyterHub.
```{toctree}
:maxdepth: 2
technical-overview
urls
websecurity
authenticators
spawners
services
proxy
separate-proxy
rest
rest-api
server-api
monitoring
database
templates
api-only
../events/index
config-user-env
config-examples
config-ghoauth
config-proxy
config-sudo
config-reference
oauth
```

32
docs/source/reference/index.rst
View File

@@ -1,32 +0,0 @@
Technical Reference
===================
This section covers more of the details of the JupyterHub architecture, as well as
what happens under-the-hood when you deploy and configure your JupyterHub.
.. toctree::
:maxdepth: 2
technical-overview
urls
websecurity
authenticators
spawners
services
proxy
separate-proxy
rest
rest-api
server-api
monitoring
database
templates
api-only
../events/index
config-user-env
config-examples
config-ghoauth
config-proxy
config-sudo
config-reference
oauth

20
docs/source/reference/monitoring.md Normal file
View File

@@ -0,0 +1,20 @@
# Monitoring
This section covers details on monitoring the state of your JupyterHub installation.
JupyterHub expose the `/metrics` endpoint that returns text describing its current
operational state formatted in a way [Prometheus](https://prometheus.io/docs/introduction/overview/) understands.
Prometheus is a separate open source tool that can be configured to repeatedly poll
JupyterHub's `/metrics` endpoint to parse and save its current state.
By doing so, Prometheus can describe JupyterHub's evolving state over time.
This evolving state can then be accessed through Prometheus that expose its underlying
storage to those allowed to access it, and be presented with dashboards by a
tool like [Grafana](https://grafana.com/docs/grafana/latest/getting-started/what-is-grafana/).
```{toctree}
:maxdepth: 2
metrics
```

20
docs/source/reference/monitoring.rst
View File

@@ -1,20 +0,0 @@
Monitoring
==========
This section covers details on monitoring the state of your JupyterHub installation.
JupyterHub expose the ``/metrics`` endpoint that returns text describing its current
operational state formatted in a way `Prometheus <https://prometheus.io/docs/introduction/overview/>`_ understands.
Prometheus is a separate open source tool that can be configured to repeatedly poll
JupyterHub's ``/metrics`` endpoint to parse and save its current state.
By doing so, Prometheus can describe JupyterHub's evolving state over time.
This evolving state can then be accessed through Prometheus that expose its underlying
storage to those allowed to access it, and be presented with dashboards by a
tool like `Grafana <https://grafana.com/docs/grafana/latest/getting-started/what-is-grafana/>`_.
.. toctree::
:maxdepth: 2
metrics