diff --git a/docs/source/admin/upgrading.md b/docs/source/admin/upgrading.md new file mode 100644 index 00000000..6c44ea72 --- /dev/null +++ b/docs/source/admin/upgrading.md @@ -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 `, 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== +``` + +Where `` 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== +``` + +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! diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst deleted file mode 100644 index d9d2c0eb..00000000 --- a/docs/source/admin/upgrading.rst +++ /dev/null @@ -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 `, 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== - -Where ```` 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== - -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! diff --git a/docs/source/api/app.md b/docs/source/api/app.md new file mode 100644 index 00000000..804a7922 --- /dev/null +++ b/docs/source/api/app.md @@ -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 +``` diff --git a/docs/source/api/app.rst b/docs/source/api/app.rst deleted file mode 100644 index 7045c51a..00000000 --- a/docs/source/api/app.rst +++ /dev/null @@ -1,15 +0,0 @@ -========================= -Application configuration -========================= - -Module: :mod:`jupyterhub.app` -============================= - -.. automodule:: jupyterhub.app - -.. currentmodule:: jupyterhub.app - -:class:`JupyterHub` -------------------- - -.. autoconfigurable:: JupyterHub diff --git a/docs/source/api/auth.md b/docs/source/api/auth.md new file mode 100644 index 00000000..6b740da0 --- /dev/null +++ b/docs/source/api/auth.md @@ -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 +``` diff --git a/docs/source/api/auth.rst b/docs/source/api/auth.rst deleted file mode 100644 index 69c714bd..00000000 --- a/docs/source/api/auth.rst +++ /dev/null @@ -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 diff --git a/docs/source/api/index.rst b/docs/source/api/index.md similarity index 50% rename from docs/source/api/index.rst rename to docs/source/api/index.md index 38f1328a..d17fa21c 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.md @@ -1,14 +1,14 @@ -.. _api-index: +--- +Date: "{{ today }}" +Release: "{{ release }}" +--- -############## -JupyterHub API -############## +(api-index)= -:Release: |release| -:Date: |today| +# JupyterHub API 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: - what you can do with the API @@ -19,15 +19,14 @@ information on: JupyterHub API Reference: -.. toctree:: +```{toctree} +app +auth +spawner +proxy +user +service +services.auth +``` - app - auth - spawner - proxy - user - service - services.auth - - -.. _OpenAPI Initiative: https://www.openapis.org/ +[openapi initiative]: https://www.openapis.org/ diff --git a/docs/source/api/proxy.rst b/docs/source/api/proxy.md similarity index 56% rename from docs/source/api/proxy.rst rename to docs/source/api/proxy.md index 93fd3dd7..1c8261a2 100644 --- a/docs/source/api/proxy.rst +++ b/docs/source/api/proxy.md @@ -1,22 +1,25 @@ -======= -Proxies -======= +# Proxies -Module: :mod:`jupyterhub.proxy` -=============================== +## Module: {mod}`jupyterhub.proxy` +```{eval-rst} .. automodule:: jupyterhub.proxy +``` +```{eval-rst} .. currentmodule:: jupyterhub.proxy +``` -:class:`Proxy` --------------- +### {class}`Proxy` +```{eval-rst} .. autoconfigurable:: Proxy :members: +``` -:class:`ConfigurableHTTPProxy` ------------------------------- +### {class}`ConfigurableHTTPProxy` +```{eval-rst} .. autoconfigurable:: ConfigurableHTTPProxy :members: debug, auth_token, check_running_interval, api_url, command +``` diff --git a/docs/source/api/service.rst b/docs/source/api/service.md similarity index 63% rename from docs/source/api/service.rst rename to docs/source/api/service.md index 1f11baed..898d5950 100644 --- a/docs/source/api/service.rst +++ b/docs/source/api/service.md @@ -1,16 +1,18 @@ -======== -Services -======== +# Services -Module: :mod:`jupyterhub.services.service` -========================================== +## Module: {mod}`jupyterhub.services.service` +```{eval-rst} .. automodule:: jupyterhub.services.service +``` +```{eval-rst} .. currentmodule:: jupyterhub.services.service +``` -:class:`Service` ----------------- +### {class}`Service` +```{eval-rst} .. autoconfigurable:: Service :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec +``` diff --git a/docs/source/api/services.auth.md b/docs/source/api/services.auth.md new file mode 100644 index 00000000..6b624215 --- /dev/null +++ b/docs/source/api/services.auth.md @@ -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 +``` diff --git a/docs/source/api/services.auth.rst b/docs/source/api/services.auth.rst deleted file mode 100644 index 1195afc9..00000000 --- a/docs/source/api/services.auth.rst +++ /dev/null @@ -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 diff --git a/docs/source/api/spawner.rst b/docs/source/api/spawner.md similarity index 61% rename from docs/source/api/spawner.rst rename to docs/source/api/spawner.md index 77ff34e0..1c6c1207 100644 --- a/docs/source/api/spawner.rst +++ b/docs/source/api/spawner.md @@ -1,21 +1,24 @@ -======== -Spawners -======== +# Spawners -Module: :mod:`jupyterhub.spawner` -================================= +## Module: {mod}`jupyterhub.spawner` +```{eval-rst} .. automodule:: jupyterhub.spawner +``` +```{eval-rst} .. currentmodule:: jupyterhub.spawner +``` -:class:`Spawner` ----------------- +### {class}`Spawner` +```{eval-rst} .. autoconfigurable:: Spawner :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs +``` -:class:`LocalProcessSpawner` ----------------------------- +### {class}`LocalProcessSpawner` +```{eval-rst} .. autoconfigurable:: LocalProcessSpawner +``` diff --git a/docs/source/api/user.rst b/docs/source/api/user.md similarity index 71% rename from docs/source/api/user.rst rename to docs/source/api/user.md index a61aec0d..e3cdd7df 100644 --- a/docs/source/api/user.rst +++ b/docs/source/api/user.md @@ -1,36 +1,39 @@ -===== -Users -===== +# Users -Module: :mod:`jupyterhub.user` -============================== +## Module: {mod}`jupyterhub.user` +```{eval-rst} .. automodule:: jupyterhub.user +``` +```{eval-rst} .. currentmodule:: jupyterhub.user +``` -:class:`UserDict` ------------------ +### {class}`UserDict` +```{eval-rst} .. autoclass:: UserDict :members: +``` -:class:`User` -------------- +### {class}`User` +```{eval-rst} .. autoclass:: User :members: escaped_name - + .. attribute:: name - + The user's name - + .. attribute:: server - + The user's Server data object if running, None otherwise. Has ``ip``, ``port`` attributes. .. attribute:: spawner - + The user's :class:`~.Spawner` instance. +``` diff --git a/docs/source/conf.py b/docs/source/conf.py index 736a0acb..362089b5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,7 +39,7 @@ extensions = [ "myst_parser", ] root_doc = "index" -source_suffix = [".md", ".rst"] +source_suffix = [".md"] # default_role let's use use `foo` instead of ``foo`` in rST default_role = "literal" diff --git a/docs/source/contributing/docs.md b/docs/source/contributing/docs.md new file mode 100644 index 00000000..f7652582 --- /dev/null +++ b/docs/source/contributing/docs.md @@ -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 `. + + **On macOS**, you can do the same with `open `. + + **On Linux**, you can do the same with `xdg-open `. + + 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/). diff --git a/docs/source/contributing/docs.rst b/docs/source/contributing/docs.rst deleted file mode 100644 index 33b39ae3..00000000 --- a/docs/source/contributing/docs.rst +++ /dev/null @@ -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 `_ to build our documentation. It takes -our documentation source files (written in `markdown -`_ or `reStructuredText -`_ & -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 ``. - - **On macOS**, you can do the same with ``open ``. - - **On Linux**, you can do the same with ``xdg-open ``. - - 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 `_. diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md new file mode 100644 index 00000000..02a8289b --- /dev/null +++ b/docs/source/contributing/index.md @@ -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 +``` diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst deleted file mode 100644 index 8eec5bd0..00000000 --- a/docs/source/contributing/index.rst +++ /dev/null @@ -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 `_ -(`reporting guidelines `_) -helps keep our community welcoming to as many people as possible. - -.. toctree:: - :maxdepth: 2 - - community - setup - docs - tests - roadmap - security diff --git a/docs/source/contributing/security.md b/docs/source/contributing/security.md new file mode 100644 index 00000000..0589c65d --- /dev/null +++ b/docs/source/contributing/security.md @@ -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 . + +If you prefer to encrypt your security reports, +you can use {download}`this PGP public key `. diff --git a/docs/source/contributing/security.rst b/docs/source/contributing/security.rst deleted file mode 100644 index 1ae4beb3..00000000 --- a/docs/source/contributing/security.rst +++ /dev/null @@ -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 `. diff --git a/docs/source/contributing/setup.md b/docs/source/contributing/setup.md new file mode 100644 index 00000000..6916ff67 --- /dev/null +++ b/docs/source/contributing/setup.md @@ -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`\]() 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 +``` diff --git a/docs/source/contributing/setup.rst b/docs/source/contributing/setup.rst deleted file mode 100644 index bb463f23..00000000 --- a/docs/source/contributing/setup.rst +++ /dev/null @@ -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 `_ -or a similar system to run `Ubuntu Linux `_ for -development. - -Install Python --------------- - -JupyterHub is written in the `Python `_ 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 `_. Remember to get the ‘Python 3’ version, -and **not** the ‘Python 2’ version! - -Install nodejs --------------- - -`NodeJS 12+ `_ 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 `_ & `GitHub `_ -for development & collaboration. You need to `install 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 `_ for - a more detailed discussion. - -1. Clone the `JupyterHub git repository `_ - 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 `__. - 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 -`_ -& `spawner -`_ -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 diff --git a/docs/source/contributing/tests.md b/docs/source/contributing/tests.md new file mode 100644 index 00000000..c0780e91 --- /dev/null +++ b/docs/source/contributing/tests.md @@ -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/ + ``` + +4. To run a specific test only, you can do: + + ```bash + pytest -v jupyterhub/tests/:: + ``` + + This runs the test with function name `` defined in + ``. 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 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. diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst deleted file mode 100644 index e0acbe50..00000000 --- a/docs/source/contributing/tests.rst +++ /dev/null @@ -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 `_ for all the tests. You -can find them under the `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/ - -#. To run a specific test only, you can do: - - .. code-block:: bash - - pytest -v jupyterhub/tests/:: - - This runs the test with function name ```` defined in - ````. 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 `_. - -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 `_ 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 `_ -into your text editor to format code automatically. diff --git a/docs/source/events/index.md b/docs/source/events/index.md new file mode 100644 index 00000000..459280d7 --- /dev/null +++ b/docs/source/events/index.md @@ -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 diff --git a/docs/source/events/index.rst b/docs/source/events/index.rst deleted file mode 100644 index bbbf680f..00000000 --- a/docs/source/events/index.rst +++ /dev/null @@ -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 diff --git a/docs/source/events/server-actions.rst b/docs/source/events/server-actions.md similarity index 80% rename from docs/source/events/server-actions.rst rename to docs/source/events/server-actions.md index 12018713..c5bd86d3 100644 --- a/docs/source/events/server-actions.rst +++ b/docs/source/events/server-actions.md @@ -1 +1,3 @@ +```{eval-rst} .. jsonschema:: ../../../jupyterhub/event-schemas/server-actions/v1.yaml +``` diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.md similarity index 54% rename from docs/source/getting-started/index.rst rename to docs/source/getting-started/index.md index bae95f8f..c16635d4 100644 --- a/docs/source/getting-started/index.rst +++ b/docs/source/getting-started/index.md @@ -1,19 +1,19 @@ -Get Started -=========== +# Get Started This section covers how to configure and customize JupyterHub for your needs. It contains information about authentication, networking, security, and other topics that are relevant to individuals or organizations deploying their own JupyterHub. -.. toctree:: - :maxdepth: 2 +```{toctree} +:maxdepth: 2 - config-basics - networking-basics - security-basics - authenticators-users-basics - spawners-basics - services-basics - faq - institutional-faq +config-basics +networking-basics +security-basics +authenticators-users-basics +spawners-basics +services-basics +faq +institutional-faq +``` diff --git a/docs/source/getting-started/security-basics.md b/docs/source/getting-started/security-basics.md new file mode 100644 index 00000000..bbbe5dfb --- /dev/null +++ b/docs/source/getting-started/security-basics.md @@ -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 ` (to enable HTTPS) +2. {ref}`Cookie secret ` (a key for encrypting browser cookies) +3. Proxy {ref}`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-\ + +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/`, +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-\-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-`. + +This cookie should not exist after you have successfully logged in. + +This cookie is restricted to the path `/user/`, so that only +the user’s server receives it. + +[post]: https://discourse.jupyter.org/t/how-to-force-re-login-for-users/1998/6 diff --git a/docs/source/getting-started/security-basics.rst b/docs/source/getting-started/security-basics.rst deleted file mode 100644 index 8c06959a..00000000 --- a/docs/source/getting-started/security-basics.rst +++ /dev/null @@ -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 ` (to enable HTTPS) -2. :ref:`Cookie secret ` (a key for encrypting browser cookies) -3. Proxy :ref:`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 `_ 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 `_, -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- -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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/``, -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--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-``. - -This cookie should not exist after you have successfully logged in. - -This cookie is restricted to the path ``/user/``, so that only -the user’s server receives it. diff --git a/docs/source/index-about.rst b/docs/source/index-about.md similarity index 55% rename from docs/source/index-about.rst rename to docs/source/index-about.md index f0771c60..9372c4e7 100644 --- a/docs/source/index-about.rst +++ b/docs/source/index-about.md @@ -1,15 +1,14 @@ -===== -About -===== +# About JupyterHub is an open source project and community. It is a part of the -`Jupyter Project `_. 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 about our community, as well as ways that you can connect and get involved. -.. toctree:: - :maxdepth: 1 +```{toctree} +:maxdepth: 1 - contributor-list - changelog - gallery-jhub-deployments +contributor-list +changelog +gallery-jhub-deployments +``` diff --git a/docs/source/index-admin.md b/docs/source/index-admin.md new file mode 100644 index 00000000..e85550d6 --- /dev/null +++ b/docs/source/index-admin.md @@ -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 +``` diff --git a/docs/source/index-admin.rst b/docs/source/index-admin.rst deleted file mode 100644 index 53679b88..00000000 --- a/docs/source/index-admin.rst +++ /dev/null @@ -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 diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..45c77efa --- /dev/null +++ b/docs/source/index.md @@ -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 `. + +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 diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 1624f090..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -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 `__ 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 `__ 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 `. - -The JupyterHub team and Project Jupyter value our community, and JupyterHub -follows the Jupyter `Community Guides `_. - -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 `__ 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 `__ distribution. - This distribution runs JupyterHub on top of `Kubernetes `_. - -*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 `_ and `reporting guidelines `_ -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 `_ 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/ diff --git a/docs/source/installation-guide-hard.md b/docs/source/installation-guide-hard.md new file mode 100644 index 00000000..99f1272b --- /dev/null +++ b/docs/source/installation-guide-hard.md @@ -0,0 +1,7 @@ +--- +orphan: true +--- + +# JupyterHub the hard way + +This guide has moved to diff --git a/docs/source/installation-guide-hard.rst b/docs/source/installation-guide-hard.rst deleted file mode 100644 index b24cea08..00000000 --- a/docs/source/installation-guide-hard.rst +++ /dev/null @@ -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 diff --git a/docs/source/installation-guide.rst b/docs/source/installation-guide.md similarity index 62% rename from docs/source/installation-guide.rst rename to docs/source/installation-guide.md index b2415fcc..011a796c 100644 --- a/docs/source/installation-guide.rst +++ b/docs/source/installation-guide.md @@ -1,13 +1,13 @@ -Installation -============ +# Installation 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 running on your own infrastructure. -.. toctree:: - :maxdepth: 3 +```{toctree} +:maxdepth: 3 - quickstart - quickstart-docker - installation-basics +quickstart +quickstart-docker +installation-basics +``` diff --git a/docs/source/quickstart-docker.md b/docs/source/quickstart-docker.md new file mode 100644 index 00000000..7f356f28 --- /dev/null +++ b/docs/source/quickstart-docker.md @@ -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 + +# resume the paused container +docker start +``` + +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/ diff --git a/docs/source/quickstart-docker.rst b/docs/source/quickstart-docker.rst deleted file mode 100644 index e298f21a..00000000 --- a/docs/source/quickstart-docker.rst +++ /dev/null @@ -1,69 +0,0 @@ -Install JupyterHub with Docker -============================== - - -The JupyterHub `docker image `_ 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 `_ 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 - - # resume the paused container - docker start - - -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 `_ -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/ diff --git a/docs/source/reference/config-reference.md b/docs/source/reference/config-reference.md new file mode 100644 index 00000000..1ee23ae9 --- /dev/null +++ b/docs/source/reference/config-reference.md @@ -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:: +``` diff --git a/docs/source/reference/config-reference.rst b/docs/source/reference/config-reference.rst deleted file mode 100644 index 22ee25cb..00000000 --- a/docs/source/reference/config-reference.rst +++ /dev/null @@ -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:: diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md new file mode 100644 index 00000000..fa61f7e4 --- /dev/null +++ b/docs/source/reference/index.md @@ -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 +``` diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst deleted file mode 100644 index 98e2be50..00000000 --- a/docs/source/reference/index.rst +++ /dev/null @@ -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 diff --git a/docs/source/reference/monitoring.md b/docs/source/reference/monitoring.md new file mode 100644 index 00000000..20873d11 --- /dev/null +++ b/docs/source/reference/monitoring.md @@ -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 +``` diff --git a/docs/source/reference/monitoring.rst b/docs/source/reference/monitoring.rst deleted file mode 100644 index 774656ec..00000000 --- a/docs/source/reference/monitoring.rst +++ /dev/null @@ -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 `_ 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 `_. - -.. toctree:: - :maxdepth: 2 - - metrics