From f0c825cc1ebb81d6b1713ead5b337479277550fc Mon Sep 17 00:00:00 2001 From: Shloka Date: Sat, 8 Oct 2022 22:40:22 +0530 Subject: [PATCH 01/91] Modification in community channels --- docs/source/contributing/community.rst | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/source/contributing/community.rst b/docs/source/contributing/community.rst index 359d2472..638b3667 100644 --- a/docs/source/contributing/community.rst +++ b/docs/source/contributing/community.rst @@ -4,27 +4,19 @@ Community communication channels ================================ -We use `Discourse ` for online discussion. -Everyone in the Jupyter community is welcome to bring ideas and questions there. -In addition, we use `Gitter `_ for online, real-time text chat, -a place for more ephemeral discussions. -The primary Gitter channel for JupyterHub is `jupyterhub/jupyterhub `_. -Gitter isn't archived or searchable, so we recommend going to discourse first -to make sure that discussions are most useful and accessible to the community. -Remember that our community is distributed across the world in various -timezones, so be patient if you do not get an answer immediately! +There is a place for everyone in the Jupyter community to share thoughts and ask questions. We use `Discourse `_ , `Gitter `_ , and GitHub issues for online discussion. -GitHub issues are used for most long-form project discussions, bug reports -and feature requests. Issues related to a specific authenticator or -spawner should be directed to the appropriate repository for the -authenticator or spawner. If you are using a specific JupyterHub +JupyterHub's main Gitter channel is `jupyterhub/jupyterhub `_. +However, to ensure that discussions are the most useful and accessible to the community, we advise using Discourse first as Gitter doesn't have an archive or search function +Please be patient if you do not recieve a response right away; keep in mind that our comunity is spread out over the globe in different timezones. + +Most lengthy project conversations, bug reports, and feature requests take place via GitHub issues. If you have an issue with a certain authenticator or spawner, you should report them to the relevant repository. If you are using a specific JupyterHub distribution (such as `Zero to JupyterHub on Kubernetes `_ or `The Littlest JupyterHub `_), -you should open issues directly in their repository. If you can not +you should open issues directly in the respective repository. If you can not find a repository to open your issue in, do not worry! Create it in the `main JupyterHub repository `_ and our community will help you figure it out. -A `mailing list `_ for all -of Project Jupyter exists, along with one for `teaching with Jupyter -`_. +There is a `mailing list `_ for `teaching with Jupyter +`_ as well as one for the entire of Project Jupyter. \ No newline at end of file From 204bfaf8f4521a8ac3fd1f08ce59e0364bd40788 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 8 Oct 2022 17:13:40 +0000 Subject: [PATCH 02/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/contributing/community.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/community.rst b/docs/source/contributing/community.rst index 638b3667..87a615bb 100644 --- a/docs/source/contributing/community.rst +++ b/docs/source/contributing/community.rst @@ -19,4 +19,4 @@ JupyterHub repository `_ and our community will help you figure it out. There is a `mailing list `_ for `teaching with Jupyter -`_ as well as one for the entire of Project Jupyter. \ No newline at end of file +`_ as well as one for the entire of Project Jupyter. From 395b1a56812d0eb4e5b53be4815ba3687fc849f5 Mon Sep 17 00:00:00 2001 From: Shloka Date: Sun, 9 Oct 2022 19:07:20 +0530 Subject: [PATCH 03/91] Modifications is testing docs --- docs/source/contributing/tests.rst | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index 044aa7ca..8fbf17aa 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -4,19 +4,16 @@ Testing JupyterHub and linting code =================================== -Unit test help 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. +Unit tests help confirming that JupyterHub works as intended and does so even when modifications are made. Additionally, they help in clarifying our expectations for our code. -JupyterHub uses `pytest `_ for all our tests. You -can find them under ``jupyterhub/tests`` directory in the git repository. +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`. You should be able - to start ``jupyterhub`` from the commandline & access it from your - web browser. This ensures that the dev environment is properly set +#. Make sure you have completed :ref:`contributing/setup`. Once completed, you should be able + to start ``jupyterhub`` through a web browser as well as the command line. By doing this, it is ensured that the dev environment is properly set up for tests to run. #. You can run all tests in JupyterHub @@ -57,7 +54,7 @@ Running the tests pytest -v jupyterhub/tests/test_api.py::test_shutdown - See the `pytest usage documentation `_ for more details. + For more information, refer to `pytest usage documentation `_. Test organisation ================= @@ -98,8 +95,7 @@ And fixtures to add functionality or spawning behavior: - ``bad_spawn``: enables the BadSpawner (a spawner that fails immediately) - ``slow_bad_spawn``: enables the SlowBadSpawner (a spawner that fails after a short delay) -See the `pytest fixtures documentation `_ -for how to use the existing fixtures, and how to create new ones. +For information on using the existing fixtures and creating new ones, refer to `pytest fixtures documentation `_ Troubleshooting Test Failures @@ -109,7 +105,7 @@ All the tests are failing ------------------------- Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and -can launch ``jupyterhub`` from the terminal. +can launch ``jupyterhub`` from the terminal as well as the web browser. Code formatting and linting @@ -117,13 +113,13 @@ Code formatting and linting JupyterHub has adopted automatic code formatting and linting. As long as your code is valid, the pre-commit hook should take care of how it should look. -You can invoke the pre-commit hook by hand at any time with: +You can invoke the pre-commit hook manually at any time with: .. code:: bash pre-commit run -which should run any autoformatting on your code and tell you about any errors it couldn't fix automatically. +This should run any auto formatting on your code and tell you about any errors it couldn't fix automatically. You may also install `black integration `_ into your text editor to format code automatically. From 3425269cb2a67d59eaf9fd8ae9e1abb4cdce5feb Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Mon, 10 Oct 2022 12:34:09 +0500 Subject: [PATCH 04/91] Update index.rst --- docs/source/index.rst | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index a7b2c0c8..23b93a54 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,20 +2,17 @@ JupyterHub ========== -`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. +`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. Because of it's distributed nature, It can be used in a class of students, a corporate data science group or scientific research group. It is a multi-user **Hub** that spawns, manages, and proxies multiple instances of the single-user `Jupyter notebook`_ server. -To make life easier, JupyterHub has distributions. Be sure to +JupyterHub offers distributions for different use cases. Be sure to take a look at them before continuing with the configuration of the broad -original system of `JupyterHub`_. Today, you can find two main cases: +original system of `JupyterHub`_. As of now, you can find two main 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 even more users, a dynamic amount of servers can be used on a cloud, - take a look at the `Zero to JupyterHub with Kubernetes `__ . +1. `The Littlest JupyterHub `__ distribution is suitable if you need small amount of users (0-100) and single server with a simple environment. +2. `Zero to JupyterHub with Kubernetes `__ allows you to deploy dynamic servers on cloud if you need even more users. Four subsystems make up JupyterHub: @@ -26,7 +23,7 @@ Four subsystems make up JupyterHub: * an **authentication class** that manages how users can access the system -Besides these central pieces, you can add optional configurations through a `config.py` file and manage users kernels on an admin panel. A simplification of the whole system can be seen in the figure below: +Besides these central pieces, you can add optional configurations through a `config.py` file and manage users' kernels through admin panel. A simplification of the whole system can be seen in the figure below: .. image:: images/jhub-fluxogram.jpeg :alt: JupyterHub subsystems From 915fab2d26094d15ad679ecf4c3a891fc4d1d109 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Mon, 10 Oct 2022 12:55:16 +0500 Subject: [PATCH 05/91] Update index.rst --- docs/source/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 23b93a54..9b8c56b2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,7 +3,7 @@ JupyterHub ========== `JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. Because of it's distributed nature, -It can be used in a class of students, a corporate data science group or scientific +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. @@ -11,14 +11,14 @@ JupyterHub offers distributions for different use cases. Be sure to take a look at them before continuing with the configuration of the broad original system of `JupyterHub`_. As of now, you can find two main cases: -1. `The Littlest JupyterHub `__ distribution is suitable if you need small amount of users (0-100) and single server with a simple environment. -2. `Zero to JupyterHub with Kubernetes `__ allows you to deploy dynamic servers on cloud if you need even more users. +1. `The Littlest JupyterHub `__ distribution is suitable if you need a small number of users (0-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. Four subsystems make up JupyterHub: * 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 +* 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 From aa101a7aff888bffe52778e95aca29345bbd7c68 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Mon, 10 Oct 2022 15:36:10 +0500 Subject: [PATCH 06/91] Update index.rst --- docs/source/index.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 9b8c56b2..96b56485 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,8 +2,8 @@ JupyterHub ========== -`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. Because of it's distributed nature, -it can be used in a class of students, a corporate data science group, or a scientific +`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. The distributed Jupyter Notebook environment allows +it to 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. @@ -11,7 +11,7 @@ JupyterHub offers distributions for different use cases. Be sure to take a look at them before continuing with the configuration of the broad original system of `JupyterHub`_. As of now, you can find two main cases: -1. `The Littlest JupyterHub `__ distribution is suitable if you need a small number of users (0-100) and a single server with a simple environment. +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. @@ -23,7 +23,7 @@ Four subsystems make up JupyterHub: * an **authentication class** that manages how users can access the system -Besides these central pieces, you can add optional configurations through a `config.py` file and manage users' kernels through admin panel. A simplification of the whole system can be seen in the figure below: +Besides these central pieces, you can add optional configurations through a `config.py` file and manage users' environments through an admin panel. A simplification of the whole system can be seen in the figure below: .. image:: images/jhub-fluxogram.jpeg :alt: JupyterHub subsystems @@ -53,17 +53,17 @@ Contents Distributions ------------- -A JupyterHub **distribution** is tailored towards a particular set of +Each JupyterHub **distribution** is tailored toward 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. The two popular ones are: -* `Zero to JupyterHub on Kubernetes `_, for - running JupyterHub on top of `Kubernetes `_. This - can scale to large number of machines & users. * `The Littlest JupyterHub `_, for an easy to set up & run JupyterHub supporting 1-100 users on a single machine. +* `Zero to JupyterHub on Kubernetes `_, for + running JupyterHub on top of `Kubernetes `_. This + can scale to a large number of machines & users. Installation Guide ------------------ @@ -116,8 +116,8 @@ RBAC Reference 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, +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 `_ From b87b8c52d35a43d3852673106b8c6278a112d991 Mon Sep 17 00:00:00 2001 From: Arafat Abdussalam Date: Tue, 11 Oct 2022 07:21:19 +0100 Subject: [PATCH 07/91] updated websecirity.md I have the grammatical errors written on the page such as improving the abbreviated words with apostrophes and other typos --- docs/source/reference/websecurity.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/reference/websecurity.md b/docs/source/reference/websecurity.md index 8473c3e9..d9a9a397 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/reference/websecurity.md @@ -5,18 +5,18 @@ The **Security Overview** section helps you learn about: - the design of JupyterHub with respect to web security - the semi-trusted user - the available mitigations to protect untrusted users from each other -- the value of periodic security audits. +- the value of periodic security audits This overview also helps you obtain a deeper understanding of how JupyterHub works. -## Semi-trusted and untrusted users +## Semi-trusted and Untrusted Users JupyterHub is designed to be a _simple multi-user server for modestly sized groups_ of **semi-trusted** users. While the design reflects serving semi-trusted users, JupyterHub is not necessarily unsuitable for serving **untrusted** users. -Using JupyterHub with **untrusted** users does mean more work by the +Using JupyterHub with **untrusted** users entails more work by the administrator. Much care is required to secure a Hub, with extra caution on protecting users from each other as the Hub is serving untrusted users. @@ -32,7 +32,7 @@ servers) as a single website (i.e. single domain). To protect users from each other, a user must **never** be able to write arbitrary HTML and serve it to another user on the Hub's domain. JupyterHub's -authentication setup prevents a user writing arbitrary HTML and serving it to +authentication setup prevents a user from writing arbitrary HTML and serving it to another user because only the owner of a given single-user notebook server is allowed to view user-authored pages served by the given single-user notebook server. @@ -41,7 +41,7 @@ To protect all users from each other, JupyterHub administrators must ensure that: - A user **does not have permission** to modify their single-user notebook server, - including: + as well as: - A user **may not** install new packages in the Python environment that runs their single-user server. - If the `PATH` is used to resolve the single-user executable (instead of @@ -101,8 +101,8 @@ pose additional risk to the web application's security. ### Encrypt internal connections with SSL/TLS -By default, all communication on the server, between the proxy, hub, and single --user notebooks is performed unencrypted. Setting the `internal_ssl` flag in +By default, all communications on the server, between the proxy, hub, and single +-user notebooks are performed unencrypted. Setting the `internal_ssl` flag in `jupyterhub_config.py` secures the aforementioned routes. Turning this feature on does require that the enabled `Spawner` can use the certificates generated by the `Hub` (the default `LocalProcessSpawner` can, for instance). @@ -118,7 +118,7 @@ extend to securing the `tcp` sockets as well. ## Security audits -We recommend that you do periodic reviews of your deployment's security. It's +We recommend that you do periodic reviews of your deployment's security. It is good practice to keep JupyterHub, configurable-http-proxy, and nodejs versions up to date. @@ -129,7 +129,7 @@ A handy website for testing your deployment is ## Vulnerability reporting -If you believe you’ve found a security vulnerability in JupyterHub, or any +If you believe you have found a security vulnerability in JupyterHub, or any Jupyter project, please report it to [security@ipython.org](mailto:security@ipython.org). If you prefer to encrypt your security reports, you can use [this PGP public From f2059c0d039f571480b2974c6d17e32b5800389a Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Tue, 11 Oct 2022 09:37:54 +0100 Subject: [PATCH 08/91] Update troubleshooting.md This PR improves the troubleshooting doc and is part of [issue 41](https://github.com/jupyterhub/outreachy/issues/41) --- docs/source/troubleshooting.md | 171 +++++++++++++++++---------------- 1 file changed, 88 insertions(+), 83 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 0cecb6d9..b3ac424c 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -1,32 +1,37 @@ # Troubleshooting When troubleshooting, you may see unexpected behaviors or receive an error -message. This section provide links for identifying the cause of the +message. This section provides links for identifying the cause of the problem and how to resolve it. [_Behavior_](#behavior) -- JupyterHub proxy fails to start -- sudospawner fails to run -- What is the default behavior when none of the lists (admin, allowed, - allowed groups) are set? -- JupyterHub Docker container not accessible at localhost +- [JupyterHub proxy fails to start](#jupyterhub-proxy-fails-to-start) +- [sudospawner fails to run](#sudospawner-fails-to-run) +- [What is the default behavior when none of the lists (admin, allowed, + allowed groups) are set?](#what-is-the-default-behavior-when-none-of-the-lists-admin-allowed-allowed-groups-are-set) +- [JupyterHub Docker container not accessible at localhost](#jupyterhub-docker-container-not-accessible-at-localhost) +- [How can I kill ports from JupyterHub-managed services that have been orphaned?](#how-can-i-kill-ports-from-jupyterhub-managed-services-that-have-been-orphaned) +- [Why am I getting a Spawn failed error message?](#why-am-i-getting-a-spawn-failed-error-message) +- [How can I run JupyterHub with sudo but use my current env vars and virtualenv location?](#how-can-i-run-jupyterhub-with-sudo-but-use-my-current-env-vars-and-virtualenv-location) [_Errors_](#errors) -- 500 error after spawning my single-user server +- [Error 500 after spawning my single-user server](#error-500-after-spawning-my-single-user-server) +- [Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error](#launching-jupyter-notebooks-to-run-as-an-externally-managed-jupyterhub-service-with-the-jupyterhub-singleuser-command-returns-a-jupyterhub-api-token-error) [_How do I...?_](#how-do-i) -- Use a chained SSL certificate -- Install JupyterHub without a network connection -- I want access to the whole filesystem, but still default users to their home directory -- How do I increase the number of pySpark executors on YARN? -- How do I use JupyterLab's prerelease version with JupyterHub? -- How do I set up JupyterHub for a workshop (when users are not known ahead of time)? -- How do I set up rotating daily logs? -- Toree integration with HDFS rack awareness script -- Where do I find Docker images and Dockerfiles related to JupyterHub? +- [Use a chained SSL certificate](#use-a-chained-ssl-certificate) +- [Install JupyterHub without a network connection](#install-jupyterhub-without-a-network-connection) +- [I want access to the whole filesystem and still default users to their home directory](#i-want-access-to-the-whole-filesystem-and-still-default-users-to-their-home-directory) +- [How do I increase the number of pySpark executors on YARN?](#how-do-i-increase-the-number-of-pyspark-executors-on-yarn) +- [How do I use JupyterLab's prerelease version with JupyterHub?](#how-do-i-use-jupyterlab-s-prerelease-version-with-jupyterhub) +- [How do I set up JupyterHub for a workshop (when users are not known ahead of time)?](#how-do-i-set-up-jupyterhub-for-a-workshop-when-users-are-not-known-ahead-of-time) +- [How do I set up rotating daily logs?](#how-do-i-set-up-rotating-daily-logs) +- [Toree integration with HDFS rack awareness script](#toree-integration-with-hdfs-rack-awareness-script) +- [Where do I find Docker images and Dockerfiles related to JupyterHub?](#where-do-i-find-docker-images-and-dockerfiles-related-to-jupyterhub) +- [How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner?](#how-can-i-view-the-logs-for-jupyterhub-or-the-user-s-notebook-servers-when-using-the-dockerspawner) [_Troubleshooting commands_](#troubleshooting-commands) @@ -40,9 +45,9 @@ If you have tried to start the JupyterHub proxy and it fails to start: `c.JupyterHub.ip = '*'`; if it is, try `c.JupyterHub.ip = ''` - Try starting with `jupyterhub --ip=0.0.0.0` -**Note**: If this occurs on Ubuntu/Debian, check that the you are using a -recent version of node. Some versions of Ubuntu/Debian come with a version -of node that is very old, and it is necessary to update node. +**Note**: If this occurs on Ubuntu/Debian, check that you are using a +recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with a version +of Node that is very old, and it is necessary to update Node. ### sudospawner fails to run @@ -61,24 +66,24 @@ to the config file, `jupyterhub_config.py`. ### What is the default behavior when none of the lists (admin, allowed, allowed groups) are set? When nothing is given for these lists, there will be no admins, and all users -who can authenticate on the system (i.e. all the unix users on the server with +who can authenticate on the system (i.e. all the Unix users on the server with a password) will be allowed to start a server. The allowed username set lets you limit this to a particular set of users, and admin_users lets you specify who among them may use the admin interface (not necessary, unless you need to do -things like inspect other users' servers, or modify the user list at runtime). +things like inspect other users' servers or modify the user list at runtime). ### JupyterHub Docker container not accessible at localhost Even though the command to start your Docker container exposes port 8000 (`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`), -it is possible that the IP address itself is not accessible/visible. As a result +it is possible that the IP address itself is not accessible/visible. As a result, when you try http://localhost:8000 in your browser, you are unable to connect even though the container is running properly. One workaround is to explicitly tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this command: `docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000` -### How can I kill ports from JupyterHub managed services that have been orphaned? +### How can I kill ports from JupyterHub-managed services that have been orphaned? I started JupyterHub + nbgrader on the same host without containers. When I try to restart JupyterHub + nbgrader with this configuration, errors appear that the service accounts cannot start because the ports are being used. @@ -92,7 +97,7 @@ Where `` is the port used by the nbgrader course service. This con ### Why am I getting a Spawn failed error message? -After successfully logging in to JupyterHub with a compatible authenticators, I get a 'Spawn failed' error message in the browser. The JupyterHub logs have `jupyterhub KeyError: "getpwnam(): name not found: `. +After successfully logging in to JupyterHub with a compatible authenticator, I get a 'Spawn failed' error message in the browser. The JupyterHub logs have `jupyterhub KeyError: "getpwnam(): name not found: `. This issue occurs when the authenticator requires a local system user to exist. In these cases, you need to use a spawner that does not require an existing system user account, such as `DockerSpawner` or `KubeSpawner`. @@ -109,23 +114,9 @@ sudo MY_ENV=abc123 \ /srv/jupyterhub/jupyterhub ``` -### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner? - -Use `docker logs ` where `` is the container name defined within `docker-compose.yml`. For example, to view the logs of the JupyterHub container use: - - docker logs hub - -By default, the user's notebook server is named `jupyter-` where `username` is the user's username within JupyterHub's db. So if you wanted to see the logs for user `foo` you would use: - - docker logs jupyter-foo - -You can also tail logs to view them in real time using the `-f` option: - - docker logs -f hub - ## Errors -### 500 error after spawning my single-user server +### Error 500 after spawning my single-user server You receive a 500 error when accessing the URL `/user//...`. This is often seen when your single-user server cannot verify your user cookie @@ -185,10 +176,10 @@ If you receive a 403 error, the API token for the single-user server is likely invalid. Commonly, the 403 error is caused by resetting the JupyterHub database (either removing jupyterhub.sqlite or some other action) while leaving single-user servers running. This happens most frequently when using -DockerSpawner, because Docker's default behavior is to stop/start containers -which resets the JupyterHub database, rather than destroying and recreating +DockerSpawner because Docker's default behavior is to stop/start containers +that reset the JupyterHub database, rather than destroying and recreating the container every time. This means that the same API token is used by the -server for its whole life, until the container is rebuilt. +server for its whole life until the container is rebuilt. The fix for this Docker case is to remove any Docker containers seeing this issue (typically all containers created before a certain point in time): @@ -201,14 +192,14 @@ your server again. ##### Proxy settings (403 GET) -When your whole JupyterHub sits behind a organization proxy (_not_ a reverse proxy like NGINX as part of your setup and _not_ the configurable-http-proxy) the environment variables `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy` and `https_proxy` might be set. This confuses the jupyterhub-singleuser servers: When connecting to the Hub for authorization they connect via the proxy instead of directly connecting to the Hub on localhost. The proxy might deny the request (403 GET). This results in the singleuser server thinking it has a wrong auth token. To circumvent this you should add `,,localhost,127.0.0.1` to the environment variables `NO_PROXY` and `no_proxy`. +When your whole JupyterHub sits behind an organization proxy (_not_ a reverse proxy like NGINX as part of your setup and _not_ the configurable-http-proxy) the environment variables `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, and `https_proxy` might be set. This confuses the Jupyterhub single-user servers: When connecting to the Hub for authorization they connect via the proxy instead of directly connecting to the Hub on localhost. The proxy might deny the request (403 GET). This results in the single-user server thinking it has the wrong auth token. To circumvent this you should add `,,localhost,127.0.0.1` to the environment variables `NO_PROXY` and `no_proxy`. ### Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error [JupyterHub services](https://jupyterhub.readthedocs.io/en/stable/reference/services.html) allow processes to interact with JupyterHub's REST API. Example use-cases include: - **Secure Testing**: provide a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems. -- **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such grading assignments. +- **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such as grading assignments. - **Private Dashboards**: share dashboards with certain group members. If possible, try to run the Jupyter Notebook as an externally managed service with one of the provided [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks). @@ -222,7 +213,7 @@ If you launch a Jupyter Notebook with the `jupyterhub-singleuser` command direct Did you launch it manually? ``` -If you plan on testing `jupyterhub-singleuser` independently from JupyterHub, then you can set the api token environment variable. For example, if were to run the single-user Jupyter Notebook on the host, then: +If you plan on testing `jupyterhub-singleuser` independently from JupyterHub, then you can set the API token environment variable. For example, if you were to run the single-user Jupyter Notebook on the host, then: export JUPYTERHUB_API_TOKEN=my_secret_token jupyterhub-singleuser @@ -256,7 +247,7 @@ You would then set in your `jupyterhub_config.py` file the `ssl_key` and #### Example Your certificate provider gives you the following files: `example_host.crt`, -`Entrust_L1Kroot.txt` and `Entrust_Root.txt`. +`Entrust_L1Kroot.txt`, and `Entrust_Root.txt`. Concatenate the files appending the chain cert and root cert to your host cert: @@ -289,7 +280,7 @@ with npmbox: python3 -m pip wheel jupyterhub npmbox configurable-http-proxy -### I want access to the whole filesystem, but still default users to their home directory +### I want access to the whole filesystem and still default users to their home directory Setting the following in `jupyterhub_config.py` will configure access to the entire filesystem and set the default to the user's home directory. @@ -321,7 +312,7 @@ For instance: python3 -m pip install jupyterlab jupyter serverextension enable --py jupyterlab --sys-prefix -The important thing is that jupyterlab is installed and enabled in the +The important thing is that Jupyterlab is installed and enabled in the single-user notebook server environment. For system users, this means system-wide, as indicated above. For Docker containers, it means inside the single-user docker image, etc. @@ -334,14 +325,14 @@ notebook servers to default to JupyterLab: ### How do I set up JupyterHub for a workshop (when users are not known ahead of time)? 1. Set up JupyterHub using OAuthenticator for GitHub authentication -2. Configure admin list to have workshop leaders be listed with administrator privileges. +2. Configure the admin list to have workshop leaders be listed with administrator privileges. -Users will need a GitHub account to login and be authenticated by the Hub. +Users will need a GitHub account to log in and be authenticated by the Hub. ### How do I set up rotating daily logs? You can do this with [logrotate](https://linux.die.net/man/8/logrotate), -or pipe to `logger` to use syslog instead of directly to a file. +or pipe to `logger` to use Syslog instead of directly to a file. For example, with this logrotate config file: @@ -361,6 +352,52 @@ logrotate /path/to/above-config Or use syslog: jupyterhub | logger -t jupyterhub + +### Toree integration with HDFS rack awareness script + +The Apache Toree kernel will have an issue when running with JupyterHub if the standard HDFS +rack awareness script is used. This will materialize in the logs as a repeated WARN: + +```bash +16/11/29 16:24:20 WARN ScriptBasedMapping: Exception running /etc/hadoop/conf/topology_script.py some.ip.address +ExitCodeException exitCode=1: File "/etc/hadoop/conf/topology_script.py", line 63 + print rack + ^ +SyntaxError: Missing parentheses in call to 'print' + + at `org.apache.hadoop.util.Shell.runCommand(Shell.java:576)` +``` + +In order to resolve this issue, there are two potential options. + +1. Update HDFS core-site.xml, so the parameter "net.topology.script.file.name" points to a custom + script (e.g. /etc/hadoop/conf/custom_topology_script.py). Copy the original script and change the first line point + to a python two installation (e.g. /usr/bin/python). +2. In spark-env.sh add a Python 2 installation to your path (e.g. export PATH=/opt/anaconda2/bin:$PATH). + +### Where do I find Docker images and Dockerfiles related to JupyterHub? + +Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/). +The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/) +provides an example single-user notebook server for use with DockerSpawner. + +Additional single-user notebook server images can be found at the [Jupyter +organization on DockerHub](https://hub.docker.com/r/jupyter/) and information +about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks). + +### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner? + +Use `docker logs ` where `` is the container name defined within `docker-compose.yml`. For example, to view the logs of the JupyterHub container use: + + docker logs hub + +By default, the user's notebook server is named `jupyter-` where `username` is the user's username within JupyterHub's db. So if you wanted to see the logs for user `foo` you would use: + + docker logs jupyter-foo + +You can also tail logs to view them in real-time using the `-f` option: + + docker logs -f hub ## Troubleshooting commands @@ -385,35 +422,3 @@ jupyter kernelspec list ```bash jupyterhub --debug ``` - -### Toree integration with HDFS rack awareness script - -The Apache Toree kernel will an issue, when running with JupyterHub, if the standard HDFS -rack awareness script is used. This will materialize in the logs as a repeated WARN: - -```bash -16/11/29 16:24:20 WARN ScriptBasedMapping: Exception running /etc/hadoop/conf/topology_script.py some.ip.address -ExitCodeException exitCode=1: File "/etc/hadoop/conf/topology_script.py", line 63 - print rack - ^ -SyntaxError: Missing parentheses in call to 'print' - - at `org.apache.hadoop.util.Shell.runCommand(Shell.java:576)` -``` - -In order to resolve this issue, there are two potential options. - -1. Update HDFS core-site.xml, so the parameter "net.topology.script.file.name" points to a custom - script (e.g. /etc/hadoop/conf/custom_topology_script.py). Copy the original script and change the first line point - to a python two installation (e.g. /usr/bin/python). -2. In spark-env.sh add a Python 2 installation to your path (e.g. export PATH=/opt/anaconda2/bin:$PATH). - -### Where do I find Docker images and Dockerfiles related to JupyterHub? - -Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/). -The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/) -provides an example single user notebook server for use with DockerSpawner. - -Additional single user notebook server images can be found at the [Jupyter -organization on DockerHub](https://hub.docker.com/r/jupyter/) and information -about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks). From 5d5a424aeac8e99c07e601d6f02c629743c20337 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 11 Oct 2022 08:40:39 +0000 Subject: [PATCH 09/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index b3ac424c..5c9bcbcc 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -76,7 +76,7 @@ things like inspect other users' servers or modify the user list at runtime). Even though the command to start your Docker container exposes port 8000 (`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`), -it is possible that the IP address itself is not accessible/visible. As a result, +it is possible that the IP address itself is not accessible/visible. As a result, when you try http://localhost:8000 in your browser, you are unable to connect even though the container is running properly. One workaround is to explicitly tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this @@ -352,7 +352,7 @@ logrotate /path/to/above-config Or use syslog: jupyterhub | logger -t jupyterhub - + ### Toree integration with HDFS rack awareness script The Apache Toree kernel will have an issue when running with JupyterHub if the standard HDFS @@ -384,7 +384,7 @@ provides an example single-user notebook server for use with DockerSpawner. Additional single-user notebook server images can be found at the [Jupyter organization on DockerHub](https://hub.docker.com/r/jupyter/) and information about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks). - + ### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner? Use `docker logs ` where `` is the container name defined within `docker-compose.yml`. For example, to view the logs of the JupyterHub container use: From 941e8c928aead3f37234199ebca248a0268eb8e1 Mon Sep 17 00:00:00 2001 From: Arafat Abdussalam Date: Tue, 11 Oct 2022 10:14:03 +0100 Subject: [PATCH 10/91] Updated log messages I improved the log message subsection of the documentation by making the page more user friendly --- docs/source/admin/log-messages.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/source/admin/log-messages.md b/docs/source/admin/log-messages.md index fd672c6a..31edb683 100644 --- a/docs/source/admin/log-messages.md +++ b/docs/source/admin/log-messages.md @@ -1,22 +1,20 @@ # Interpreting common log messages -When debugging errors and outages, looking at the logs emitted by -JupyterHub is very helpful. This document tries to document some common -log messages, and what they mean. +In this subsection of the documentation, you will get to understand the meaning of common log messages and how to resolve them. When debugging errors and outages, it is very helpful to look at the logs emitted by JupyterHub. ## Failing suspected API request to not-running server ### Example -Your logs might be littered with lines that might look slightly scary +When your screen displays the log message as shown below, you need not to get scared. ``` [W 2022-03-10 17:25:19.774 JupyterHub base:1349] Failing suspected API request to not-running server: /hub/user//api/metrics/v1 ``` -### Most likely cause +### Cause -This likely means is that the user's server has stopped running but they +This likely cause is that the user's server has stopped running but they still have a browser tab open. For example, you might have 3 tabs open, and shut your server down via one. Or you closed your laptop, your server was culled for inactivity, and then you reopen your laptop again! The From 3ee21cc967d8ef91ffbeffd3fc717705aa9e53e8 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 11 Oct 2022 09:17:45 +0000 Subject: [PATCH 11/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/admin/log-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/admin/log-messages.md b/docs/source/admin/log-messages.md index 31edb683..c2974260 100644 --- a/docs/source/admin/log-messages.md +++ b/docs/source/admin/log-messages.md @@ -1,6 +1,6 @@ # Interpreting common log messages -In this subsection of the documentation, you will get to understand the meaning of common log messages and how to resolve them. When debugging errors and outages, it is very helpful to look at the logs emitted by JupyterHub. +In this subsection of the documentation, you will get to understand the meaning of common log messages and how to resolve them. When debugging errors and outages, it is very helpful to look at the logs emitted by JupyterHub. ## Failing suspected API request to not-running server From 15cf30156d7f63408f771854934f6ab1b9d56931 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 11 Oct 2022 19:12:03 +0500 Subject: [PATCH 12/91] update upgrading.rst --- docs/source/admin/upgrading.rst | 65 ++++++++++++++++----------------- 1 file changed, 32 insertions(+), 33 deletions(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index efe98c27..96aee1c8 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -5,20 +5,20 @@ 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 +If you are using [distributions](index/distributions), you should consult the distribution's documentation on how to upgrade. This -document is if you have set up your own JupyterHub without using a +document is useful if you have set up your own JupyterHub without using a distribution. -It is long because is pretty detailed! Most likely, upgrading -JupyterHub is painless, quick and with minimal user interruption. +The steps are discussed in detail. Most likely, +upgrading JupyterHub is painless, quick and with minimal user interruption. Read the Changelog ================== -The `changelog <../changelog.html>`_ 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 +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 upcoming changes. There might be new releases of authenticators & spawners you are using, so read the changelogs for those too! @@ -27,13 +27,13 @@ Notify your users If you are using 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 +the upgrade process. You will need notify them, and pick a time to do the upgrade where they will be least disrupted. -If you are using a different proxy, or running ``configurable-http-proxy`` -independent of JupyterHub, your users will be able to continue using notebook +If you are using a different proxy or running ``configurable-http-proxy`` +independent of JupyterHub, your users will be able to continue using a notebook servers they had already launched, but will not be able to launch new servers -nor sign in. +or sign in. Backup database & config @@ -41,22 +41,21 @@ 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 are using sqlite (the default), you - should backup the ``jupyterhub.sqlite`` file. +#. Your JupyterHub database (SQLite by default, or MySQL / Postgres + if you used those). If you are using SQLite (the default), you + should back up the ``jupyterhub.sqlite`` file. #. Your ``jupyterhub_config.py`` file. -#. Your user's home directories. This is unlikely to be affected directly by - a JupyterHub upgrade, but we recommend a backup since user data is very - critical. +#. 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. -Shutdown JupyterHub +Shut down JupyterHub =================== -Shutdown the JupyterHub process. This would vary depending on how you +Shut down the JupyterHub process. This would vary depending on how you have set up JupyterHub to run. Most likely, it is using a process supervisor of some sort (``systemd`` or ``supervisord`` or even ``docker``). -Use the supervisor specific command to stop the JupyterHub process. +Use the supervisor-specific command to stop the JupyterHub process. Upgrade JupyterHub packages =========================== @@ -64,14 +63,14 @@ Upgrade JupyterHub packages There are two environments where the ``jupyterhub`` package is installed: #. The *hub environment*, which is where the JupyterHub server process - runs. This is started with the ``jupyterhub`` command, and is what - people generally think of as JupyterHub. + runs. This is started with the ``jupyterhub`` command and is what + people generally think of it as JupyterHub. -#. The *notebook user environments*. This is where the user notebook - servers are launched from, and is probably custom to your own +#. The *notebook user environments*. This is where the user's notebook + servers are launched from and are 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 same environment as the hub environment. The hub + 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. @@ -95,7 +94,7 @@ with: Where ```` is the version of JupyterHub you are upgrading to. 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, +are using. You might wish to upgrade those packages too along with JupyterHub or upgrade them separately. Upgrade JupyterHub database @@ -109,7 +108,7 @@ database. From the hub environment, in the same directory as your jupyterhub upgrade-db -This should find the location of your database, and run necessary upgrades +This should find the location of your database, and run the necessary upgrades for it. SQLite database disadvantages @@ -118,11 +117,11 @@ SQLite database disadvantages SQLite has some disadvantages when it comes to upgrading JupyterHub. These are: -- ``upgrade-db`` may not work, and you may need delete your database +- ``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 + upgrading. What happens if I delete my database? ------------------------------------- @@ -137,10 +136,10 @@ resides only in the Hub database includes: If the following conditions are true, you should be fine clearing the Hub database and starting over: -- users specified in config file, or login using an external +- users specified in the config file, or login using an external authentication provider (Google, GitHub, LDAP, etc) -- user servers are stopped during upgrade -- don't mind causing users to login again after upgrade +- user servers are stopped during the upgrade +- don't mind causing users to log in again after the upgrade Start JupyterHub ================ @@ -148,7 +147,7 @@ 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 +#. 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 From 6b4c5e4bcea032b1ffcbe32e9d423b00df350e4f Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 11 Oct 2022 19:36:04 +0500 Subject: [PATCH 13/91] update upgrading.rst --- docs/source/admin/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index 96aee1c8..e5d77634 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -5,7 +5,7 @@ Upgrading JupyterHub JupyterHub offers easy upgrade pathways between minor versions. This document describes how to do these upgrades. -If you are using [distributions](index/distributions), you +If you are using [distributions](../index.rst#distributions), you should consult the distribution's documentation on how to upgrade. This document is useful if you have set up your own JupyterHub without using a distribution. From d5790ce386b0383f0734e6479eff9eb3746594ab Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 11 Oct 2022 19:38:36 +0500 Subject: [PATCH 14/91] update upgrading.rst --- docs/source/admin/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index e5d77634..35b8c47e 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -5,7 +5,7 @@ Upgrading JupyterHub JupyterHub offers easy upgrade pathways between minor versions. This document describes how to do these upgrades. -If you are using [distributions](../index.rst#distributions), you +If you are using [distributions](https://github.com/ToobaJamal/jupyterhub/blob/main/docs/source/index.rst#distributions), you should consult the distribution's documentation on how to upgrade. This document is useful if you have set up your own JupyterHub without using a distribution. From 8f30f4afd96d1627bd0ad70f7a79a3b11f156c66 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 11 Oct 2022 19:40:15 +0500 Subject: [PATCH 15/91] update upgrading.rst --- docs/source/admin/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index 35b8c47e..5cc9430f 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -5,7 +5,7 @@ Upgrading JupyterHub JupyterHub offers easy upgrade pathways between minor versions. This document describes how to do these upgrades. -If you are using [distributions](https://github.com/ToobaJamal/jupyterhub/blob/main/docs/source/index.rst#distributions), you +If you are using `distributions `__, you should consult the distribution's documentation on how to upgrade. This document is useful if you have set up your own JupyterHub without using a distribution. From 916a83a9549ed85358f9c3d443f2091ec2dff33b Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Tue, 11 Oct 2022 19:03:21 +0100 Subject: [PATCH 16/91] Update tech-implementation.md Fix typos and grammatical errors. Improve sentence structure. Use appropriate technical terms. --- docs/source/rbac/tech-implementation.md | 35 ++++++++++++------------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/source/rbac/tech-implementation.md b/docs/source/rbac/tech-implementation.md index 3156dbf1..b3084ed5 100644 --- a/docs/source/rbac/tech-implementation.md +++ b/docs/source/rbac/tech-implementation.md @@ -1,8 +1,8 @@ # Technical Implementation -Roles are stored in the database, where they are associated with users, services, etc., and can be added or modified as explained in {ref}`define-role-target` section. Users, services, groups, and tokens can gain, change, and lose roles. This is currently achieved via `jupyterhub_config.py` (see {ref}`define-role-target`) and will be made available via API in future. The latter will allow for changing a token's role, and thereby its permissions, without the need to issue a new token. +[Roles](https://jupyterhub.readthedocs.io/en/stable/rbac/roles.html#roles) are stored in the database, where they are associated with users, services, groups and tokens. Roles can be added or modified as explained in the {ref}`define-role-target` section. Users, services, groups, and tokens can gain, change, and lose roles. This is currently achieved via `jupyterhub_config.py` (see {ref}`define-role-target`) and will be made available via API in the future. The latter will allow for changing a token's role, and thereby its permissions, without the need to issue a new token. -Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. Scope variables take on five different formats which is reflected throughout the utilities via specific nomenclature: +Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. Scope variables take on five different formats that are reflected throughout the utilities via specific nomenclature: ```{admonition} **Scope variable nomenclature** :class: tip @@ -11,22 +11,22 @@ Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. S - _expanded scopes_ \ Set of fully expanded scopes without abbreviations (i.e., resolved metascopes, filters, and subscopes). E.g., `{"users:activity!user=charlie", "read:users:activity!user=charlie"}`. - _parsed scopes_ \ - Dictionary represenation of expanded scopes. E.g., `{"users:activity": {"user": ["charlie"]}, "read:users:activity": {"users": ["charlie"]}}`. + Dictionary representation of expanded scopes. E.g., `{"users:activity": {"user": ["charlie"]}, "read:users:activity": {"users": ["charlie"]}}`. - _intersection_ \ Set of expanded scopes as intersection of 2 expanded scope sets. - _identify scopes_ \ - Set of expanded scopes needed for identify (whoami) endpoints. + Set of expanded scopes needed for identity (whoami) endpoints. ``` (resolving-roles-scopes-target)= ## Resolving roles and scopes -**Resolving roles** refers to determining which roles a user, service, or group has, extracting the list of scopes from each role and combining them into a single set of scopes. +**Resolving roles** involves determining which roles a user, service, or group has, extracting the list of scopes from each role and combining them into a single set of scopes. -**Resolving scopes** involves expanding scopes into all their possible subscopes (_expanded scopes_), parsing them into format used for access evaluation (_parsed scopes_) and, if applicable, comparing two sets of scopes (_intersection_). All procedures take into account the scope hierarchy, {ref}`vertical ` and {ref}`horizontal filtering `, limiting or elevated permissions (`read:` or `admin:`, respectively), and metascopes. +**Resolving scopes** involves expanding scopes into all their possible subscopes (_expanded scopes_), parsing them into the format used for access evaluation (_parsed scopes_) and, if applicable, comparing two sets of scopes (_intersection_). All procedures take into account the scope hierarchy, {ref}`vertical ` and {ref}`horizontal filtering `, limiting or elevated permissions (`read:` or `admin:`, respectively), and metascopes. -Roles and scopes are resolved on several occasions, for example when requesting an API token with specific scopes or making an API request. The following sections provide more details. +Roles and scopes are resolved on several occasions, for example when requesting an API token with specific scopes or when making an API request. The following sections provide more details. (requesting-api-token-target)= @@ -43,26 +43,25 @@ Prior to 3.0, tokens stored _roles_, which meant their scopes were resolved on each request. ::: -API tokens grant access to JupyterHub's APIs. The RBAC framework allows for requesting tokens with specific permissions. +API tokens grant access to JupyterHub's APIs. The Role Based Access Control (RBAC) framework allows for the requesting of tokens with specific permissions. RBAC is involved in several stages of the OAuth token flow. When requesting a token via the tokens API (`/users/:name/tokens`), or the token page (`/hub/token`), if no scopes are requested, the token is issued with the permissions stored on the default `token` role -(providing the requester is allowed to create the token). +(provided the requester is allowed to create the token). OAuth tokens are also requested via OAuth flow If the token is requested with any scopes, the permissions of requesting entity are checked against the requested permissions to ensure the token would not grant its owner additional privileges. -If, due to modifications of permissions of the token or token owner, -at API request time a token has any scopes that its owner does not, -those scopes are removed. +If a token has any scopes that its owner does not possess +at the time of making the API request, those scopes are removed. The API request is resolved without additional errors using the scope _intersection_; the Hub logs a warning in this case (see {ref}`Figure 2 `). -Resolving a token's scope (yellow box in {ref}`Figure 1 `) corresponds to resolving all the token's owner roles (including the roles associated with their groups) and the token's own scopes into a set of scopes. The two sets are compared (Resolve the scopes box in orange in {ref}`Figure 1 `), taking into account the scope hierarchy. -If the token's scopes are a subset of the token owner's scopes, the token is issued with the requested scopes; if not, JupyterHub will raise an error. +Resolving a token's scope (yellow box in {ref}`Figure 1 `) corresponds to resolving all the roles of the token's owner (including the roles associated with their groups) and the token's own scopes into a set of scopes. The two sets are compared (Resolve the scopes box in orange in {ref}`Figure 1 `), taking into account the scope hierarchy. +If the token's scopes are a subset of the token owner's scopes, the token is issued with the requested scopes; if not, JupyterHub will throw an error. {ref}`Figure 1 ` below illustrates the steps involved. The orange rectangles highlight where in the process the roles and scopes are resolved. @@ -75,10 +74,10 @@ Figure 1. Resolving roles and scopes during API token request ### Making an API request -With the RBAC framework, each authenticated JupyterHub API request is guarded by a scope decorator that specifies which scopes are required to gain the access to the API. +With the RBAC framework, each authenticated JupyterHub API request is guarded by a scope decorator that specifies which scopes are required in order to gain the access to the API. -When an API request is performed, the requesting API token's scopes are again intersected with its owner's (yellow box in {ref}`Figure 2 `) to ensure the token does not grant more permissions than its owner has at the request time (e.g., due to changing/losing roles). -If the owner's roles do not include some scopes of the token's scopes, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being passed on. In the case of no _intersection_, an empty set of scopes will be used. +When an API request is made, the requesting API token's scopes are again intersected with its owner's (yellow box in {ref}`Figure 2 `) to ensure that the token does not grant more permissions than its owner has at the request time (e.g., due to changing/losing roles). +If the owner's roles do not include some scopes of the token, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being passed on. In the case of no _intersection_, an empty set of scopes will be used. The passed scopes are compared to the scopes required to access the API as follows: @@ -86,7 +85,7 @@ The passed scopes are compared to the scopes required to access the API as follo - if that is not the case, another check is utilized to determine if subscopes of the required API scopes can be found in the passed scope set: - - if found, the RBAC framework employs the {ref}`filtering ` procedures to refine the API response to access only resource attributes corresponding to the passed scopes. For example, providing a scope `read:users:activity!group=class-C` for the _GET /users_ API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model + - if found, the RBAC framework employs the {ref}`filtering ` procedures to refine the API response to access only resource attributes corresponding to the passed scopes. For example, providing a scope `read:users:activity!group=class-C` for the `GET /users` API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model - if not found, the access to API is denied From 6ef8120f94dbdc4bd0031f34ff09df01e96c58e3 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Wed, 12 Oct 2022 10:58:13 +0500 Subject: [PATCH 17/91] fix grammatical error --- docs/source/admin/upgrading.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index 5cc9430f..8b786143 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -27,11 +27,11 @@ Notify your users If you are using the default configuration where ``configurable-http-proxy`` is managed by JupyterHub, your users will see service disruption during -the upgrade process. You will need notify them, and pick a time to do the +the upgrade process. You will need to notify them, and pick a time to do the upgrade where they will be least disrupted. If you are using a different proxy or running ``configurable-http-proxy`` -independent of JupyterHub, your users will be able to continue using a notebook +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. From dcd4e689aa5587dd0ab6dececcd5322087491c5c Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Wed, 12 Oct 2022 12:09:57 +0500 Subject: [PATCH 18/91] update index.rst --- docs/source/events/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/events/index.rst b/docs/source/events/index.rst index bc086ba1..b53c8448 100644 --- a/docs/source/events/index.rst +++ b/docs/source/events/index.rst @@ -1,7 +1,7 @@ -Eventlogging and Telemetry +Event logging and Telemetry ========================== -JupyterHub can be configured to record structured events from a running server using Jupyter's `Telemetry System`_. The types of events that JupyterHub emits are defined by `JSON schemas`_ listed at the bottom of this page_. +JupyterHub can be configured to record structured events from a running server using Jupyter's `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 @@ -15,8 +15,8 @@ Event logging is handled by its ``Eventlog`` object. This leverages Python's sta 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 - 2. ``allows_schemas``: tells the EventLog *which* events should be recorded. No events are emitted by default; all recorded events must be listed here. + 1. ``handlers``: tells the EventLog *where* to route your events; this trait is a list of Python logging handlers that route events to the destination + 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: From 1050dadda4fe0a40221987af5bd7becbac1451ff Mon Sep 17 00:00:00 2001 From: Temidayo Date: Wed, 12 Oct 2022 12:27:57 +0100 Subject: [PATCH 19/91] modified announcement README and config.py --- examples/service-announcement/README.md | 19 ++++++++++++++++++- .../service-announcement/jupyterhub_config.py | 2 ++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/examples/service-announcement/README.md b/examples/service-announcement/README.md index 0582facc..6e31e8e5 100644 --- a/examples/service-announcement/README.md +++ b/examples/service-announcement/README.md @@ -6,12 +6,29 @@ that appear when JupyterHub renders pages. To run the service as a hub-managed service simply include in your JupyterHub configuration file something like: +:notebook:**Info**: You can run the announcement service example from the `examples` + directory, using one of the several services provided by JupyterHub. + + ```python + +import sys + +from pathlib import Path +# absolute path to announcement.py +announcement_py = str(Path(__file__).parent.joinpath("announcement.py").resolve()) + +#ensure get_config() is added to in + c = get_config() + +... +.. + c.JupyterHub.services = [ { 'name': 'announcement', 'url': 'http://127.0.0.1:8888', - 'command': [sys.executable, "-m", "announcement", "--port", "8888"], + 'command': [sys.executable, announcement_py, "--port", "8888"], } ] ``` diff --git a/examples/service-announcement/jupyterhub_config.py b/examples/service-announcement/jupyterhub_config.py index 9bca9809..07a9fe76 100644 --- a/examples/service-announcement/jupyterhub_config.py +++ b/examples/service-announcement/jupyterhub_config.py @@ -1,5 +1,7 @@ import sys +c = get_config() + # To run the announcement service managed by the hub, add this. port = 9999 From 08a125489d21983909822277cbdfd0a6aa9d925c Mon Sep 17 00:00:00 2001 From: Temidayo Date: Wed, 12 Oct 2022 12:29:07 +0100 Subject: [PATCH 20/91] fixed a typo --- examples/service-announcement/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/service-announcement/README.md b/examples/service-announcement/README.md index 6e31e8e5..f6dbb7ed 100644 --- a/examples/service-announcement/README.md +++ b/examples/service-announcement/README.md @@ -18,7 +18,7 @@ from pathlib import Path # absolute path to announcement.py announcement_py = str(Path(__file__).parent.joinpath("announcement.py").resolve()) -#ensure get_config() is added to in +#ensure get_config() is added in c = get_config() ... From 67bca186b44b6c0b79d41883275428a421ff32ba Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Wed, 12 Oct 2022 12:31:44 +0100 Subject: [PATCH 21/91] Update config-user-env.md This PR improves the 'Configuring user environments' doc and is part of [issue 41](https://github.com/jupyterhub/outreachy/issues/41) --- docs/source/reference/config-user-env.md | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 503d2661..4a2be932 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -7,8 +7,8 @@ environment in some way. Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook server, most configuration and documentation that applies to Jupyter Notebook applies to the single-user environments. Configuration of user environments -typically does not occur through JupyterHub itself, but rather through system- -wide configuration of Jupyter, which is inherited by `jupyterhub-singleuser`. +typically does not occur through JupyterHub itself, but rather through the system-wide +configuration of Jupyter, which is inherited by `jupyterhub-singleuser`. **Tip:** When searching for configuration tips for JupyterHub user environments, try removing JupyterHub from your search because there are a lot @@ -17,10 +17,10 @@ configuration is the same. This section will focus on user environments, including: -- Installing packages -- Configuring Jupyter and IPython -- Installing kernelspecs -- Using containers vs. multi-user hosts +- [Installing packages](#installing-packages) +- [Configuring Jupyter and IPython](#configuring-jupyter-and-ipython) +- [Installing kernelspecs](#installing-kernelspecs) +- [Using containers vs. multi-user hosts](#multi-user-hosts-vs-containers) ## Installing packages @@ -30,7 +30,7 @@ system-wide or in a shared environment. This installation location should always be in the same environment that `jupyterhub-singleuser` itself is installed in, and must be _readable and executable_ by your users. If you want users to be able to install additional -packages, it must also be _writable_ by your users. +packages, they must also be _writable_ by your users. If you are using a standard system Python install, you would use: @@ -109,7 +109,7 @@ they are available to all of your users. This means installing kernelspecs either system-wide (e.g. in /usr/local/) or in the `sys.prefix` of JupyterHub itself. -Jupyter kernelspec installation is system wide by default, but some kernels +Jupyter kernelspec installation is system-wide by default, but some kernels may default to installing kernelspecs in your home directory. These will need to be moved system-wide to ensure that they are accessible. @@ -143,12 +143,12 @@ depending on what Spawner you are using. The first category is a **shared system (multi-user host)** where each user has a JupyterHub account and a home directory as well as being a real system user. In this example, shared configuration and installation -must be in a 'system-wide' location, such as `/etc/` or `/usr/local` +must be in a 'system-wide' location, such as `/etc/`, or `/usr/local` or a custom prefix such as `/opt/conda`. When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or DockerSpawner), the 'system-wide' environment is really the container image -which you are using for users. +that you are using for users. In both cases, you want to _avoid putting configuration in user home directories_ because users can change those configuration settings. Also, @@ -157,7 +157,7 @@ difficult for admins to update later. ## Named servers -By default, in a JupyterHub deployment each user has exactly one server. +By default, in a JupyterHub deployment, each user has exactly one server. JupyterHub can, however, have multiple servers per user. This is most useful in deployments where users can configure the environment @@ -181,7 +181,7 @@ as well as the admin page: ![named servers on the admin page](../images/named-servers-admin.png) Named servers can be accessed, created, started, stopped, and deleted -from these pages. Activity tracking is now per-server as well. +from these pages. Activity tracking is now per server as well. The number of named servers per user can be limited by setting a constant value: @@ -207,9 +207,9 @@ If `named_server_limit_per_user` is set to `0`, no limit is enforced. (classic-notebook-ui)= -## Switching back to classic notebook +## Switching back to the classic notebook -By default the single-user server launches JupyterLab, +By default, the single-user server launches JupyterLab, which is based on [Jupyter Server][]. This is the default server when running JupyterHub ≥ 2.0. You can switch to using the legacy Jupyter Notebook server by setting the `JUPYTERHUB_SINGLEUSER_APP` environment variable @@ -223,11 +223,11 @@ export JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp' [jupyter notebook]: https://jupyter-notebook.readthedocs.io :::{versionchanged} 2.0 -JupyterLab is now the default singleuser UI, if available, +JupyterLab is now the default single-user UI, if available, which is based on the [Jupyter Server][], no longer the legacy [Jupyter Notebook][] server. JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`), -and Jupyter server could be selected by specifying +and the Jupyter server could be selected by specifying ```python # jupyterhub_config.py From af95d643b14faef952155eee90a1d653bf4e59e0 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Oct 2022 11:33:53 +0000 Subject: [PATCH 22/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/reference/config-user-env.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 4a2be932..251fee0c 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -7,7 +7,7 @@ environment in some way. Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook server, most configuration and documentation that applies to Jupyter Notebook applies to the single-user environments. Configuration of user environments -typically does not occur through JupyterHub itself, but rather through the system-wide +typically does not occur through JupyterHub itself, but rather through the system-wide configuration of Jupyter, which is inherited by `jupyterhub-singleuser`. **Tip:** When searching for configuration tips for JupyterHub user From ef7545fc758d1f081a5eb5cdd40eea5925e76615 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Oct 2022 11:34:18 +0000 Subject: [PATCH 23/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- examples/service-announcement/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/examples/service-announcement/README.md b/examples/service-announcement/README.md index f6dbb7ed..637f25f5 100644 --- a/examples/service-announcement/README.md +++ b/examples/service-announcement/README.md @@ -7,8 +7,7 @@ To run the service as a hub-managed service simply include in your JupyterHub configuration file something like: :notebook:**Info**: You can run the announcement service example from the `examples` - directory, using one of the several services provided by JupyterHub. - +directory, using one of the several services provided by JupyterHub. ```python From 71ce37b83467c8fbe8534f6c7e93ba105e7a2c04 Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Wed, 12 Oct 2022 13:02:12 +0100 Subject: [PATCH 24/91] Update troubleshooting.md Implement suggested changes. --- docs/source/troubleshooting.md | 42 +++++++++++++++++----------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 5c9bcbcc..1f051859 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -6,32 +6,32 @@ problem and how to resolve it. [_Behavior_](#behavior) -- [JupyterHub proxy fails to start](#jupyterhub-proxy-fails-to-start) -- [sudospawner fails to run](#sudospawner-fails-to-run) -- [What is the default behavior when none of the lists (admin, allowed, - allowed groups) are set?](#what-is-the-default-behavior-when-none-of-the-lists-admin-allowed-allowed-groups-are-set) -- [JupyterHub Docker container not accessible at localhost](#jupyterhub-docker-container-not-accessible-at-localhost) -- [How can I kill ports from JupyterHub-managed services that have been orphaned?](#how-can-i-kill-ports-from-jupyterhub-managed-services-that-have-been-orphaned) -- [Why am I getting a Spawn failed error message?](#why-am-i-getting-a-spawn-failed-error-message) -- [How can I run JupyterHub with sudo but use my current env vars and virtualenv location?](#how-can-i-run-jupyterhub-with-sudo-but-use-my-current-env-vars-and-virtualenv-location) +- JupyterHub proxy fails to start +- sudospawner fails to run] +- What is the default behavior when none of the lists (admin, allowed, + allowed groups) are set? +- JupyterHub Docker container not accessible at localhost +- How can I kill ports from JupyterHub-managed services that have been orphaned? +- Why am I getting a Spawn failed error message? +- How can I run JupyterHub with sudo but use my current env vars and virtualenv location? [_Errors_](#errors) -- [Error 500 after spawning my single-user server](#error-500-after-spawning-my-single-user-server) -- [Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error](#launching-jupyter-notebooks-to-run-as-an-externally-managed-jupyterhub-service-with-the-jupyterhub-singleuser-command-returns-a-jupyterhub-api-token-error) +- Error 500 after spawning my single-user server +- Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error [_How do I...?_](#how-do-i) -- [Use a chained SSL certificate](#use-a-chained-ssl-certificate) -- [Install JupyterHub without a network connection](#install-jupyterhub-without-a-network-connection) -- [I want access to the whole filesystem and still default users to their home directory](#i-want-access-to-the-whole-filesystem-and-still-default-users-to-their-home-directory) -- [How do I increase the number of pySpark executors on YARN?](#how-do-i-increase-the-number-of-pyspark-executors-on-yarn) -- [How do I use JupyterLab's prerelease version with JupyterHub?](#how-do-i-use-jupyterlab-s-prerelease-version-with-jupyterhub) -- [How do I set up JupyterHub for a workshop (when users are not known ahead of time)?](#how-do-i-set-up-jupyterhub-for-a-workshop-when-users-are-not-known-ahead-of-time) -- [How do I set up rotating daily logs?](#how-do-i-set-up-rotating-daily-logs) -- [Toree integration with HDFS rack awareness script](#toree-integration-with-hdfs-rack-awareness-script) -- [Where do I find Docker images and Dockerfiles related to JupyterHub?](#where-do-i-find-docker-images-and-dockerfiles-related-to-jupyterhub) -- [How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner?](#how-can-i-view-the-logs-for-jupyterhub-or-the-user-s-notebook-servers-when-using-the-dockerspawner) +- Use a chained SSL certificate +- Install JupyterHub without a network connection +- I want access to the whole filesystem and still default users to their home directory +- How do I increase the number of pySpark executors on YARN? +- How do I use JupyterLab's prerelease version with JupyterHub? +- How do I set up JupyterHub for a workshop (when users are not known ahead of time)? +- How do I set up rotating daily logs? +- Toree integration with HDFS rack awareness script +- Where do I find Docker images and Dockerfiles related to JupyterHub? +- How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner? [_Troubleshooting commands_](#troubleshooting-commands) @@ -312,7 +312,7 @@ For instance: python3 -m pip install jupyterlab jupyter serverextension enable --py jupyterlab --sys-prefix -The important thing is that Jupyterlab is installed and enabled in the +The important thing is that JupyterLab is installed and enabled in the single-user notebook server environment. For system users, this means system-wide, as indicated above. For Docker containers, it means inside the single-user docker image, etc. From f386da1b7ac81e29d81c31c95f20d8d9bd35de2b Mon Sep 17 00:00:00 2001 From: Ojoachele Onuh Date: Wed, 12 Oct 2022 13:12:08 +0100 Subject: [PATCH 25/91] fixed some typos and technical terms --- docs/source/rbac/tech-implementation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/rbac/tech-implementation.md b/docs/source/rbac/tech-implementation.md index 3156dbf1..eccb2d0b 100644 --- a/docs/source/rbac/tech-implementation.md +++ b/docs/source/rbac/tech-implementation.md @@ -11,7 +11,7 @@ Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. S - _expanded scopes_ \ Set of fully expanded scopes without abbreviations (i.e., resolved metascopes, filters, and subscopes). E.g., `{"users:activity!user=charlie", "read:users:activity!user=charlie"}`. - _parsed scopes_ \ - Dictionary represenation of expanded scopes. E.g., `{"users:activity": {"user": ["charlie"]}, "read:users:activity": {"users": ["charlie"]}}`. + Dictionary representation of expanded scopes. E.g., `{"users:activity": {"user": ["charlie"]}, "read:users:activity": {"users": ["charlie"]}}`. - _intersection_ \ Set of expanded scopes as intersection of 2 expanded scope sets. - _identify scopes_ \ @@ -78,15 +78,15 @@ Figure 1. Resolving roles and scopes during API token request With the RBAC framework, each authenticated JupyterHub API request is guarded by a scope decorator that specifies which scopes are required to gain the access to the API. When an API request is performed, the requesting API token's scopes are again intersected with its owner's (yellow box in {ref}`Figure 2 `) to ensure the token does not grant more permissions than its owner has at the request time (e.g., due to changing/losing roles). -If the owner's roles do not include some scopes of the token's scopes, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being passed on. In the case of no _intersection_, an empty set of scopes will be used. +If the owner's roles do not include some scopes of the token's scopes, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being parsed on. In the case of no _intersection_, an empty set of scopes will be used. -The passed scopes are compared to the scopes required to access the API as follows: +The parsed scopes are compared to the scopes required to access the API as follows: -- if the API scopes are present within the set of passed scopes, the access is granted and the API returns its "full" response +- if the API scopes are present within the set of parsed scopes, the access is granted and the API returns its "full" response -- if that is not the case, another check is utilized to determine if subscopes of the required API scopes can be found in the passed scope set: +- if that is not the case, another check is utilized to determine if subscopes of the required API scopes can be found in the parsed scope set: - - if found, the RBAC framework employs the {ref}`filtering ` procedures to refine the API response to access only resource attributes corresponding to the passed scopes. For example, providing a scope `read:users:activity!group=class-C` for the _GET /users_ API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model + - if found, the RBAC framework employs the {ref}`filtering ` procedures to refine the API response to access only resource attributes corresponding to the parsed scopes. For example, providing a scope `read:users:activity!group=class-C` for the _GET /users_ API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model - if not found, the access to API is denied From 0820f4cfa10ccb260327cf6f0a59121dc9943195 Mon Sep 17 00:00:00 2001 From: Shloka Date: Wed, 12 Oct 2022 18:52:58 +0530 Subject: [PATCH 26/91] Modifications --- docs/source/contributing/community.rst | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/source/contributing/community.rst b/docs/source/contributing/community.rst index 638b3667..9ab8a54d 100644 --- a/docs/source/contributing/community.rst +++ b/docs/source/contributing/community.rst @@ -4,13 +4,8 @@ Community communication channels ================================ -There is a place for everyone in the Jupyter community to share thoughts and ask questions. We use `Discourse `_ , `Gitter `_ , and GitHub issues for online discussion. - -JupyterHub's main Gitter channel is `jupyterhub/jupyterhub `_. -However, to ensure that discussions are the most useful and accessible to the community, we advise using Discourse first as Gitter doesn't have an archive or search function -Please be patient if you do not recieve a response right away; keep in mind that our comunity is spread out over the globe in different timezones. - -Most lengthy project conversations, bug reports, and feature requests take place via GitHub issues. If you have an issue with a certain authenticator or spawner, you should report them to the relevant repository. If you are using a specific JupyterHub +`Discourse `_ is primarily used by the Jupyter community for discussions and support. Additionally, we use JupyterHub's primary Gitter channel, `jupyterhub/jupyterhub `_, for quick discussions, and GitHub issues for detailed discussions relating to modifying a repository's content. +If you have an issue with a certain authenticator or spawner, please report them to the relevant repository. If you are using a specific JupyterHub distribution (such as `Zero to JupyterHub on Kubernetes `_ or `The Littlest JupyterHub `_), you should open issues directly in the respective repository. If you can not @@ -18,5 +13,4 @@ find a repository to open your issue in, do not worry! Create it in the `main JupyterHub repository `_ and our community will help you figure it out. -There is a `mailing list `_ for `teaching with Jupyter -`_ as well as one for the entire of Project Jupyter. \ No newline at end of file +Please be patient if you do not recieve a response right away; keep in mind that our comunity is spread out over the globe in different timezones. \ No newline at end of file From a87872e7aa87bbccb0b56039c4543f7dfed3fd60 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Oct 2022 13:27:59 +0000 Subject: [PATCH 27/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/contributing/community.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/contributing/community.rst b/docs/source/contributing/community.rst index b0dc6be2..fe88e40f 100644 --- a/docs/source/contributing/community.rst +++ b/docs/source/contributing/community.rst @@ -14,4 +14,3 @@ JupyterHub repository `_ and our community will help you figure it out. Please be patient if you do not recieve a response right away; keep in mind that our comunity is spread out over the globe in different timezones. - From 733e018bdc7550309f04b033c7d3a0944c867891 Mon Sep 17 00:00:00 2001 From: Shloka Date: Wed, 12 Oct 2022 19:07:43 +0530 Subject: [PATCH 28/91] Update docs/source/contributing/tests.rst Co-authored-by: Simon Li --- docs/source/contributing/tests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index 8fbf17aa..faca41b0 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -4,7 +4,7 @@ Testing JupyterHub and linting code =================================== -Unit tests help confirming that JupyterHub works as intended and does so even when modifications are made. Additionally, they help in clarifying our expectations for our code. +Unit tests help confirm that JupyterHub works as intended, including after modifications are made. Additionally, they help in clarifying our expectations for our code. JupyterHub uses `pytest `_ for all the tests. You can find them under the `jupyterhub/tests `_ directory in the git repository. From 7a915533a6eb51a6c14b522ab4cb5b6e8422d204 Mon Sep 17 00:00:00 2001 From: Shloka Date: Wed, 12 Oct 2022 19:07:50 +0530 Subject: [PATCH 29/91] Update docs/source/contributing/tests.rst Co-authored-by: Simon Li --- docs/source/contributing/tests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index faca41b0..2fbfa6f1 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -54,7 +54,7 @@ Running the tests pytest -v jupyterhub/tests/test_api.py::test_shutdown - For more information, refer to `pytest usage documentation `_. + For more information, refer to the `pytest usage documentation `_. Test organisation ================= From b0f90a0f4b576b5e581ed56f7adbad2eb59e617e Mon Sep 17 00:00:00 2001 From: Shloka Date: Wed, 12 Oct 2022 19:08:01 +0530 Subject: [PATCH 30/91] Update docs/source/contributing/tests.rst Co-authored-by: Simon Li --- docs/source/contributing/tests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index 2fbfa6f1..35561e37 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -95,7 +95,7 @@ And fixtures to add functionality or spawning behavior: - ``bad_spawn``: enables the BadSpawner (a spawner that fails immediately) - ``slow_bad_spawn``: enables the SlowBadSpawner (a spawner that fails after a short delay) -For information on using the existing fixtures and creating new ones, refer to `pytest fixtures documentation `_ +For information on using the existing fixtures and creating new ones, refer to the `pytest fixtures documentation `_ Troubleshooting Test Failures From da302f5206c83a292db0aefd17221aceb4387567 Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Wed, 12 Oct 2022 14:51:22 +0100 Subject: [PATCH 31/91] Update config-proxy.md This PR improves the proxy configuration doc and is part of [issue 41](https://github.com/jupyterhub/outreachy/issues/41) --- docs/source/reference/config-proxy.md | 52 +++++++++++++-------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/source/reference/config-proxy.md b/docs/source/reference/config-proxy.md index 4f05a8c7..90e56b06 100644 --- a/docs/source/reference/config-proxy.md +++ b/docs/source/reference/config-proxy.md @@ -14,7 +14,7 @@ satisfy the following: - After testing, the server in question should be able to score at least an A on the Qualys SSL Labs [SSL Server Test](https://www.ssllabs.com/ssltest/) -Let's start out with needed JupyterHub configuration in `jupyterhub_config.py`: +Let's start out with the needed JupyterHub configuration in `jupyterhub_config.py`: ```python # Force the proxy to only listen to connections to 127.0.0.1 (on port 8000) @@ -30,15 +30,15 @@ This can take a few minutes: openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096 ``` -## nginx +## Nginx This **`nginx` config file** is fairly standard fare except for the two `location` blocks within the main section for HUB.DOMAIN.tld. -To create a new site for jupyterhub in your nginx config, make a new file +To create a new site for jupyterhub in your Nginx config, make a new file in `sites.enabled`, e.g. `/etc/nginx/sites.enabled/jupyterhub.conf`: ```bash -# top-level http config for websocket headers +# Top-level HTTP config for WebSocket headers # If Upgrade is defined, Connection = upgrade # If Upgrade is empty, Connection = close map $http_upgrade $connection_upgrade { @@ -51,7 +51,7 @@ server { listen 80; server_name HUB.DOMAIN.TLD; - # Tell all requests to port 80 to be 302 redirected to HTTPS + # Send all requests to port 80 to 302 and redirect to HTTPS return 302 https://$host$request_uri; } @@ -75,7 +75,7 @@ server { ssl_stapling_verify on; add_header Strict-Transport-Security max-age=15768000; - # Managing literal requests to the JupyterHub front end + # Managing literal requests to the JupyterHub frontend location / { proxy_pass http://127.0.0.1:8000; proxy_set_header X-Real-IP $remote_addr; @@ -101,10 +101,10 @@ server { If `nginx` is not running on port 443, substitute `$http_host` for `$host` on the lines setting the `Host` header. -`nginx` will now be the front facing element of JupyterHub on `443` which means +`nginx` will now be the front-facing element of JupyterHub on `443` which means it is also free to bind other servers, like `NO_HUB.DOMAIN.TLD` to the same port on the same machine and network interface. In fact, one can simply use the same -server blocks as above for `NO_HUB` and simply add line for the root directory +server blocks as above for `NO_HUB` and simply add a line for the root directory of the site as well as the applicable location call: ```bash @@ -112,7 +112,7 @@ server { listen 80; server_name NO_HUB.DOMAIN.TLD; - # Tell all requests to port 80 to be 302 redirected to HTTPS + # Send all requests to port 80 to 302 and redirect to HTTPS return 302 https://$host$request_uri; } @@ -143,12 +143,12 @@ Now restart `nginx`, restart the JupyterHub, and enjoy accessing `https://HUB.DOMAIN.TLD` while serving other content securely on `https://NO_HUB.DOMAIN.TLD`. -### SELinux permissions for nginx +### SELinux permissions for Nginx On distributions with SELinux enabled (e.g. Fedora), one may encounter permission errors -when the nginx service is started. +when the Nginx service is started. -We need to allow nginx to perform network relay and connect to the jupyterhub port. The +We need to allow Nginx to perform network relay and connect to the JupyterHub port. The following commands do that: ```bash @@ -157,26 +157,26 @@ setsebool -P httpd_can_network_relay 1 setsebool -P httpd_can_network_connect 1 ``` -Replace 8000 with the port the jupyterhub server is running from. +Replace 8000 with the port the JupyterHub server is running from. ## Apache -As with nginx above, you can use [Apache](https://httpd.apache.org) as the reverse proxy. -First, we will need to enable the apache modules that we are going to need: +As with Nginx above, you can use [Apache](https://httpd.apache.org) as the reverse proxy. +First, we will need to enable the Apache modules that we are going to need: ```bash a2enmod ssl rewrite proxy headers proxy_http proxy_wstunnel ``` -Our Apache configuration is equivalent to the nginx configuration above: +Our Apache configuration is equivalent to the Nginx configuration above: - Redirect HTTP to HTTPS - Good SSL Configuration -- Support for websockets on any proxied URL +- Support for WebSocket on any proxied URL - JupyterHub is running locally at http://127.0.0.1:8000 ```bash -# redirect HTTP to HTTPS +# Redirect HTTP to HTTPS Listen 80 ServerName HUB.DOMAIN.TLD @@ -188,26 +188,26 @@ Listen 443 ServerName HUB.DOMAIN.TLD - # enable HTTP/2, if available + # Enable HTTP/2, if available Protocols h2 http/1.1 # HTTP Strict Transport Security (mod_headers is required) (63072000 seconds) Header always set Strict-Transport-Security "max-age=63072000" - # configure SSL + # Configure SSL SSLEngine on SSLCertificateFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem SSLOpenSSLConfCmd DHParameters /etc/ssl/certs/dhparam.pem - # intermediate configuration from ssl-config.mozilla.org (2022-03-03) - # Please note, that this configuration might be out-dated - please update it accordingly using https://ssl-config.mozilla.org/ + # Intermediate configuration from SSL-config.mozilla.org (2022-03-03) + # Please note, that this configuration might be outdated - please update it accordingly using https://ssl-config.mozilla.org/ SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1 SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 SSLHonorCipherOrder off SSLSessionTickets off - # Use RewriteEngine to handle websocket connection upgrades + # Use RewriteEngine to handle WebSocket connection upgrades RewriteEngine On RewriteCond %{HTTP:Connection} Upgrade [NC] RewriteCond %{HTTP:Upgrade} websocket [NC] @@ -224,7 +224,7 @@ Listen 443 ``` -In case of the need to run the jupyterhub under /jhub/ or other location please use the below configurations: +In case of the need to run JupyterHub under /jhub/ or another location please use the below configurations: - JupyterHub running locally at http://127.0.0.1:8000/jhub/ or other location @@ -241,7 +241,7 @@ httpd.conf amendments: jupyterhub_config.py amendments: ```bash - --The public facing URL of the whole JupyterHub application. - --This is the address on which the proxy will bind. Sets protocol, ip, base_url + --The public-facing URL of the whole JupyterHub application. + --This is the address on which the proxy will bind. Sets protocol, IP, base_url c.JupyterHub.bind_url = 'http://127.0.0.1:8000/jhub/' ``` From 0f5f0f0df9b02e75f46c906838a23b720432a898 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Wed, 12 Oct 2022 18:58:28 +0500 Subject: [PATCH 32/91] update index.rst Made the requested changes --- docs/source/index.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 96b56485..4f98070e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,7 +2,8 @@ JupyterHub ========== -`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. The distributed Jupyter Notebook environment allows +`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. +Because JupyterHub manages a separate Jupyter environment for each user, it to 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. @@ -18,9 +19,9 @@ original system of `JupyterHub`_. As of now, you can find two main cases: Four subsystems make up JupyterHub: * 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 +* 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 Besides these central pieces, you can add optional configurations through a `config.py` file and manage users' environments through an admin panel. A simplification of the whole system can be seen in the figure below: From 2e6949c6e19487aabd19413327e679dc2e50abf9 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Wed, 12 Oct 2022 14:59:31 +0100 Subject: [PATCH 33/91] add reference for github oauth config with jupyter add link to the reference documentation for github oauth configuration with jupyterhub. Fix typos --- docs/source/reference/config-ghoauth.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/reference/config-ghoauth.md b/docs/source/reference/config-ghoauth.md index f6aa5ca4..588b1f93 100644 --- a/docs/source/reference/config-ghoauth.md +++ b/docs/source/reference/config-ghoauth.md @@ -5,15 +5,15 @@ deployment with the following assumptions: - Running JupyterHub on a single cloud server - Using SSL on the standard HTTPS port 443 -- Using GitHub OAuth (using oauthenticator) for login +- Using GitHub OAuth (using OAuthenticator) for login - Using the default spawner (to configure other spawners, uncomment and edit `spawner_class` as well as follow the instructions for your desired spawner) - Users exist locally on the server - Users' notebooks to be served from `~/assignments` to allow users to browse for notebooks within other users' home directories - You want the landing page for each user to be a `Welcome.ipynb` notebook in - their assignments directory. -- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`. + their assignments directory +- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log` The `jupyterhub_config.py` file would have these settings: @@ -69,7 +69,7 @@ c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb'] ``` Using the GitHub Authenticator requires a few additional -environment variable to be set prior to launching JupyterHub: +environment variables to be set prior to launching JupyterHub: ```bash export GITHUB_CLIENT_ID=github_id @@ -79,3 +79,5 @@ export CONFIGPROXY_AUTH_TOKEN=super-secret # append log output to log file /var/log/jupyterhub.log jupyterhub -f /etc/jupyterhub/jupyterhub_config.py &>> /var/log/jupyterhub.log ``` + +Visit the [Github OAuthenticator reference](https://oauthenticator.readthedocs.io/en/latest/api/gen/oauthenticator.github.html) to see the full list of options for configuring Github OAuth with JupyterHub. From 99255b04ac3de7328c14ed117e4713c010b12963 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Wed, 12 Oct 2022 18:59:56 +0500 Subject: [PATCH 34/91] fix typo --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 4f98070e..98eaefb2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,7 @@ JupyterHub `JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. Because JupyterHub manages a separate Jupyter environment for each user, -it to be used in a class of students, a corporate data science group, or a scientific +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. From 5018c13b8194a22a818599636d7d29c3283cd582 Mon Sep 17 00:00:00 2001 From: Shloka Date: Wed, 12 Oct 2022 19:31:04 +0530 Subject: [PATCH 35/91] Fixes --- docs/source/contributing/tests.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index 35561e37..bc3fc7a5 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -13,7 +13,7 @@ Running the tests ================== #. Make sure you have completed :ref:`contributing/setup`. Once completed, you should be able - to start ``jupyterhub`` through a web browser as well as the command line. By doing this, it is ensured that the dev environment is properly set + to run ``jupyterhub`` on your command line and access JupyterHub from your browser at http://localhost:8000. By doing this, it is ensured that the dev environment is properly set up for tests to run. #. You can run all tests in JupyterHub @@ -104,8 +104,7 @@ Troubleshooting Test Failures All the tests are failing ------------------------- -Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and -can launch ``jupyterhub`` from the terminal as well as the web browser. +Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and are able to can access JupyterHub from your browser at http://localhost:8000 after starting ``jupyterhub`` in your command line. Code formatting and linting From 8060003fd6a951c19fc197999c1df976c344896e Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Wed, 12 Oct 2022 20:12:20 +0500 Subject: [PATCH 36/91] update spawners-basics.md --- docs/source/getting-started/spawners-basics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/getting-started/spawners-basics.md b/docs/source/getting-started/spawners-basics.md index 9988c2f8..92d1a895 100644 --- a/docs/source/getting-started/spawners-basics.md +++ b/docs/source/getting-started/spawners-basics.md @@ -1,12 +1,12 @@ # Spawners and single-user notebook servers -Since the single-user server is an instance of `jupyter notebook`, an entire separate -multi-process application, there are many aspects of that server that can be configured, and a lot +Since the single-user server is an instance of `jupyter notebook`, an entirely separate +multi-process application. There are many aspects of that server that can be configured and a lot of ways to express that configuration. At the JupyterHub level, you can set some values on the Spawner. The simplest of these is `Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root -notebook directory is the highest level directory users will be able to access in the notebook +notebook directory is the highest-level directory users will be able to access in the notebook dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is expanded to the user's home directory. @@ -20,7 +20,7 @@ You can also specify extra command line arguments to the notebook server with: c.Spawner.args = ['--debug', '--profile=PHYS131'] ``` -This could be used to set the users default page for the single user server: +This could be used to set the user's default page for the single-user server: ```python c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb'] @@ -30,4 +30,4 @@ Since the single-user server extends the notebook server application, it still loads configuration from the `jupyter_notebook_config.py` config file. Each user may have one of these files in `$HOME/.jupyter/`. Jupyter also supports loading system-wide config files from `/etc/jupyter/`, -which is the place to put configuration that you want to affect all of your users. +which is the place to put the configuration that you want to affect all of your users. From c2d1a21d3213da6311f4c22754419375664dc329 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Wed, 12 Oct 2022 20:18:18 +0500 Subject: [PATCH 37/91] update spawners-basics.md --- docs/source/getting-started/spawners-basics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting-started/spawners-basics.md b/docs/source/getting-started/spawners-basics.md index 92d1a895..2b3dc78e 100644 --- a/docs/source/getting-started/spawners-basics.md +++ b/docs/source/getting-started/spawners-basics.md @@ -1,7 +1,7 @@ # Spawners and single-user notebook servers Since the single-user server is an instance of `jupyter notebook`, an entirely separate -multi-process application. There are many aspects of that server that can be configured and a lot +multi-process application, there are many aspects of that server that can be configured and a lot of ways to express that configuration. At the JupyterHub level, you can set some values on the Spawner. The simplest of these is From a10879f493410531c87885a3b1b4247bcac38eeb Mon Sep 17 00:00:00 2001 From: Chidinma Udo <97461848+Mackenzie-OO7@users.noreply.github.com> Date: Wed, 12 Oct 2022 16:20:18 +0100 Subject: [PATCH 38/91] Modifications to URLs docs --- docs/source/reference/urls.md | 86 +++++++++++++++++------------------ 1 file changed, 42 insertions(+), 44 deletions(-) diff --git a/docs/source/reference/urls.md b/docs/source/reference/urls.md index d71feaf2..8e4ec0f3 100644 --- a/docs/source/reference/urls.md +++ b/docs/source/reference/urls.md @@ -2,13 +2,13 @@ This document describes how JupyterHub routes requests. -This does not include the [REST API](./rest.md) urls. +This does not include the [REST API](./rest.md) URLs. In general, all URLs can be prefixed with `c.JupyterHub.base_url` to run the whole JupyterHub application on a prefix. -All authenticated handlers redirect to `/hub/login` to login users -prior to being redirected back to the originating page. +All authenticated handlers redirect to `/hub/login` to log-in users +before being redirected back to the originating page. The returned request should preserve all query parameters. ## `/` @@ -25,12 +25,12 @@ This is an authenticated URL. This handler redirects users to the default URL of the application, which defaults to the user's default server. -That is, it redirects to `/hub/spawn` if the user's server is not running, -or the server itself (`/user/:name`) if the server is running. +That is, the handler redirects to `/hub/spawn` if the user's server is not running, +or to the server itself (`/user/:name`) if the server is running. -This default url behavior can be customized in two ways: +This default URL behavior can be customized in two ways: -To redirect users to the JupyterHub home page (`/hub/home`) +First, to redirect users to the JupyterHub home page (`/hub/home`) instead of spawning their server, set `redirect_to_server` to False: @@ -40,7 +40,7 @@ c.JupyterHub.redirect_to_server = False This might be useful if you have a Hub where you expect users to be managing multiple server configurations -and automatic spawning is not desirable. +but automatic spawning is not desirable. Second, you can customise the landing page to any page you like, such as a custom service you have deployed e.g. with course information: @@ -57,7 +57,7 @@ By default, the Hub home page has just one or two buttons for starting and stopping the user's server. If named servers are enabled, there will be some additional -tools for management of named servers. +tools for management of the named servers. _Version added: 1.0_ named server UI is new in 1.0. @@ -65,34 +65,34 @@ _Version added: 1.0_ named server UI is new in 1.0. This is the JupyterHub login page. If you have a form-based username+password login, -such as the default PAMAuthenticator, +such as the default [PAMAuthenticator](https://en.wikipedia.org/wiki/Pluggable_authentication_module), this page will render the login form. ![A login form](../images/login-form.png) If login is handled by an external service, e.g. with OAuth, this page will have a button, -declaring "Login with ..." which users can click -to login with the chosen service. +declaring "Log in with ..." which users can click +to log in with the chosen service. ![A login redirect button](../images/login-button.png) -If you want to skip the user-interaction to initiate logging in -via the button, you can set +If you want to skip the user interaction and initiate login +via the button, you can set: ```python c.Authenticator.auto_login = True ``` -This can be useful when the user is "already logged in" via some mechanism, -but a handshake via redirects is necessary to complete the authentication with JupyterHub. +This can be useful when the user is "already logged in" via some mechanism. +However, a handshake via `redirects` is necessary to complete the authentication with JupyterHub. ## `/hub/logout` -Visiting `/hub/logout` clears cookies from the current browser. +Visiting `/hub/logout` clears [cookies](https://en.wikipedia.org/wiki/HTTP_cookie) from the current browser. Note that **logging out does not stop a user's server(s)** by default. -If you would like to shutdown user servers on logout, +If you would like to shut down user servers on logout, you can enable this behavior with: ```python @@ -105,8 +105,8 @@ does not mean the user is no longer actively using their server from another mac ## `/user/:username[/:servername]` If a user's server is running, this URL is handled by the user's given server, -not the Hub. -The username is the first part and, if using named servers, +not by the Hub. +The username is the first part, and if using named servers, the server name is the second part. If the user's server is _not_ running, this will be redirected to `/hub/user/:username/...` @@ -120,11 +120,11 @@ if the specified server were running). Handling this URL is the most complicated condition in JupyterHub, because there can be many states: -1. server is not active +1. the server is not active a. user matches b. user doesn't match -2. server is ready -3. server is pending, but not ready +2. the server is ready +3. the server is pending, but not ready If the server is pending spawn, the browser will be redirected to `/hub/spawn-pending/:username/:servername` @@ -140,39 +140,37 @@ Some checks are performed and a delay is added before redirecting back to `/user If something is really wrong, this can result in a redirect loop. Visiting this page will never result in triggering the spawn of servers -without additional user action (i.e. clicking the link on the page) +without additional user action (i.e. clicking the link on the page). ![Visiting a URL for a server that's not running](../images/not-running.png) _Version changed: 1.0_ -Prior to 1.0, this URL itself was responsible for spawning servers, -and served the progress page if it was pending, -redirected to running servers, and -This was useful because it made sure that requested servers were restarted after they stopped, -but could also be harmful because unused servers would continuously be restarted if e.g. -an idle JupyterLab frontend were open pointed at it, -which constantly makes polling requests. +Prior to 1.0, this URL itself was responsible for spawning servers. +If the progress page was pending, the URL redirected it to running servers. +This was useful because it made sure that the requested servers were restarted after they stopped. +However, it could also be harmful because unused servers would continuously be restarted if e.g. +an idle JupyterLab frontend that constantly makes polling requests was openly pointed at it. ### Special handling of API requests Requests to `/user/:username[/:servername]/api/...` are assumed to be from applications connected to stopped servers. -These are failed with 503 and an informative JSON error message -indicating how to spawn the server. -This is meant to help applications such as JupyterLab +These requests fail with a `503` status code and an informative JSON error message +that indicates how to spawn the server. +This is meant to help applications such as JupyterLab, that are connected to a server that has stopped. _Version changed: 1.0_ -JupyterHub 0.9 failed these API requests with status 404, -but 1.0 uses 503. +JupyterHub version 0.9 failed these API requests with status `404`, +but version 1.0 uses 503. ## `/user-redirect/...` -This URL is for sharing a URL that will redirect a user +The `/user-redirect/...` URL is for sharing a URL that will redirect a user to a path on their own default server. -This is useful when users have the same file at the same URL on their servers, +This is useful when different users have the same file at the same URL on their servers, and you want a single link to give to any user that will open that file on their server. e.g. a link to `/user-redirect/notebooks/Index.ipynb` @@ -194,7 +192,7 @@ that is intended to make it possible. ### `/hub/spawn[/:username[/:servername]]` Requesting `/hub/spawn` will spawn the default server for the current user. -If `username` and optionally `servername` are specified, +If the `username` and optionally `servername` are specified, then the specified server for the specified user will be spawned. Once spawn has been requested, the browser is redirected to `/hub/spawn-pending/...`. @@ -207,7 +205,7 @@ and a POST request will trigger the actual spawn and redirect. _Version added: 1.0_ -1.0 adds the ability to specify username and servername. +1.0 adds the ability to specify `username` and `servername`. Prior to 1.0, only `/hub/spawn` was recognized for the default server. _Version changed: 1.0_ @@ -247,7 +245,7 @@ against the [JupyterHub REST API](./rest.md). Administrators can take various administrative actions from this page: -1. add/remove users -2. grant admin privileges -3. start/stop user servers -4. shutdown JupyterHub itself +- add/remove users +- grant admin privileges +- start/stop user servers +- shutdown JupyterHub itself From 88906c2e1be6b05305d3fc418bb7505c5ae3891d Mon Sep 17 00:00:00 2001 From: Zeelyha <73789529+zeelyha@users.noreply.github.com> Date: Thu, 13 Oct 2022 15:13:30 +0100 Subject: [PATCH 39/91] Update templates.md Fixed a typo --- docs/source/reference/templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/templates.md b/docs/source/reference/templates.md index 1509e0f2..f29708b9 100644 --- a/docs/source/reference/templates.md +++ b/docs/source/reference/templates.md @@ -84,5 +84,5 @@ template (for example, `login.html`) with: ``` Extending `page.html` puts the message on all pages, but note that -extending `page.html` take precedence over an extension of a specific +extending `page.html` takes precedence over an extension of a specific page (unlike the variable-based approach above). From 9f62c76a8e7dd8032204b7eb390eae51be905063 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 13 Oct 2022 22:41:04 +0000 Subject: [PATCH 40/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/reference/config-user-env.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 814dd365..be0424bf 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -1,6 +1,5 @@ ![jupyterhub](https://jupyter.org/assets/homepage/hublogo.svg) - # Configuring user environments To deploy JupyterHub means you are providing Jupyter notebook environments for @@ -8,7 +7,7 @@ multiple users. Often, this includes a desire to configure the user environment in a custom way. Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook -server, most Jupyter notebook configuration and documentation also applies to single-user environments. +server, most Jupyter notebook configuration and documentation also applies to single-user environments. Configuration of user environments typically does not occur through JupyterHub itself, but rather through system- wide Jupyter's configuration, which is inherited by `jupyterhub-singleuser`. From 35d26e75f417f7d8bdefad4a219e5dba828b2a91 Mon Sep 17 00:00:00 2001 From: Alexander Chosen okon Date: Thu, 13 Oct 2022 23:20:10 +0000 Subject: [PATCH 41/91] Documentation reviewed, made concise & image added --- docs/source/reference/config-user-env.md | 80 ++++++++++++------------ 1 file changed, 41 insertions(+), 39 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 503d2661..814dd365 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -1,21 +1,23 @@ +![jupyterhub](https://jupyter.org/assets/homepage/hublogo.svg) + + # Configuring user environments -Deploying JupyterHub means you are providing Jupyter notebook environments for +To deploy JupyterHub means you are providing Jupyter notebook environments for multiple users. Often, this includes a desire to configure the user -environment in some way. +environment in a custom way. Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook -server, most configuration and documentation that applies to Jupyter Notebook -applies to the single-user environments. Configuration of user environments -typically does not occur through JupyterHub itself, but rather through system- -wide configuration of Jupyter, which is inherited by `jupyterhub-singleuser`. +server, most Jupyter notebook configuration and documentation also applies to single-user environments. +Configuration of user environments typically does not occur through JupyterHub itself, but rather through system- +wide Jupyter's configuration, which is inherited by `jupyterhub-singleuser`. **Tip:** When searching for configuration tips for JupyterHub user -environments, try removing JupyterHub from your search because there are a lot +environments, you might want to remove JupyterHub from your search because there are a lot more people out there configuring Jupyter than JupyterHub and the configuration is the same. -This section will focus on user environments, including: +This section will focus on user environments, which includes the following: - Installing packages - Configuring Jupyter and IPython @@ -24,26 +26,26 @@ This section will focus on user environments, including: ## Installing packages -To make packages available to users, you generally will install packages +To make packages available to users, you will typically install packages system-wide or in a shared environment. -This installation location should always be in the same environment that -`jupyterhub-singleuser` itself is installed in, and must be _readable and +This installation location should always be in the same environment where +`jupyterhub-singleuser` itself is installed, and must be _readable and executable_ by your users. If you want users to be able to install additional packages, it must also be _writable_ by your users. -If you are using a standard system Python install, you would use: +If you are using a standard Python installation on your system, use the following command: ```bash sudo python3 -m pip install numpy ``` -to install the numpy package in the default system Python 3 environment +to install the numpy package in the default Python 3 environment on your system (typically `/usr/local`). -You may also use conda to install packages. If you do, you should make sure -that the conda environment has appropriate permissions for users to be able to -run Python code in the env. +Alternatively, You may also use conda to install packages. To do this, ensure +that the conda environment has appropriate users permissions needed to +run Python code in the environment. ## Configuring Jupyter and IPython @@ -52,13 +54,13 @@ and [IPython](https://ipython.readthedocs.io/en/stable/development/config.html) have their own configuration systems. As a JupyterHub administrator, you will typically want to install and configure -environments for all JupyterHub users. For example, you wish for each student in +environments for all JupyterHub users. For example, let's say you wish for each student in a class to have the same user environment configuration. Jupyter and IPython support **"system-wide"** locations for configuration, which is the logical place to put global configuration that you want to affect all users. It's generally more efficient to configure user environments "system-wide", -and it's a good idea to avoid creating files in users' home directories. +and it's a good practice to avoid creating files in the users' home directories. The typical locations for these config files are: @@ -84,8 +86,8 @@ If you are using the classing Jupyter Notebook server, the same things should work, with the following substitutions: -- Where you see `jupyter_server_config`, use `jupyter_notebook_config` -- Where you see `NotebookApp`, use `ServerApp` +- Search for `jupyter_server_config`, and replace with `jupyter_notebook_config` +- Search for `NotebookApp`, and replace with `ServerApp` ::: @@ -113,7 +115,7 @@ Jupyter kernelspec installation is system wide by default, but some kernels may default to installing kernelspecs in your home directory. These will need to be moved system-wide to ensure that they are accessible. -You can see where your kernelspecs are with: +To see where your kernelspecs are, you can use the following command: ```bash jupyter kernelspec list @@ -121,8 +123,8 @@ jupyter kernelspec list ### Example: Installing kernels system-wide -Assuming I have a Python 2 and Python 3 environment that I want to make -sure are available, I can install their specs system-wide (in /usr/local) with: +Let's assume that I have a Python 2 and Python 3 environment that I want to make +sure are available, I can install their specs **system-wide** (in /usr/local) using the following command: ```bash /path/to/python3 -m ipykernel install --prefix=/usr/local @@ -141,31 +143,31 @@ How you configure user environments for each category can differ a bit depending on what Spawner you are using. The first category is a **shared system (multi-user host)** where -each user has a JupyterHub account and a home directory as well as being +each user has a JupyterHub account, a home directory as well as being a real system user. In this example, shared configuration and installation -must be in a 'system-wide' location, such as `/etc/` or `/usr/local` +must be in a **system-wide** location, such as `/etc/` or `/usr/local` or a custom prefix such as `/opt/conda`. When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or -DockerSpawner), the 'system-wide' environment is really the container image -which you are using for users. +DockerSpawner), the 'system-wide' environment is the container image +which is used for users. In both cases, you want to _avoid putting configuration in user home directories_ because users can change those configuration settings. Also, -home directories typically persist once they are created, so they are +home directories typically persist once they are created, thereby making it difficult for admins to update later. ## Named servers -By default, in a JupyterHub deployment each user has exactly one server. +By default, in a JupyterHub deployment, each user has only one server. JupyterHub can, however, have multiple servers per user. -This is most useful in deployments where users can configure the environment +This is mostly useful in deployments where users can configure the environment in which their server will start (e.g. resource requests on an HPC cluster), so that a given user can have multiple configurations running at the same time, -without having to stop and restart their one server. +without having to stop and restart their own server. -To allow named servers: +To allow named servers, use the following command: ```python c.JupyterHub.allow_named_servers = True @@ -183,13 +185,13 @@ as well as the admin page: Named servers can be accessed, created, started, stopped, and deleted from these pages. Activity tracking is now per-server as well. -The number of named servers per user can be limited by setting a constant value: +To limit the number of **named server** per user by setting a constant value, use the following command: ```python c.JupyterHub.named_server_limit_per_user = 5 ``` -or a callable/awaitable based on the handler object: +Alternatively, to use a callable/awaitable based on the handler object, use the following command: ```python def named_server_limit_per_user_fn(handler): @@ -209,10 +211,10 @@ If `named_server_limit_per_user` is set to `0`, no limit is enforced. ## Switching back to classic notebook -By default the single-user server launches JupyterLab, +By default, the single-user server launches JupyterLab, which is based on [Jupyter Server][]. This is the default server when running JupyterHub ≥ 2.0. -You can switch to using the legacy Jupyter Notebook server by setting the `JUPYTERHUB_SINGLEUSER_APP` environment variable +To switch to using the legacy Jupyter Notebook server, you can set the `JUPYTERHUB_SINGLEUSER_APP` environment variable (in the single-user environment) to: ```bash @@ -227,15 +229,15 @@ JupyterLab is now the default singleuser UI, if available, which is based on the [Jupyter Server][], no longer the legacy [Jupyter Notebook][] server. JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`), -and Jupyter server could be selected by specifying +and Jupyter server could be selected by specifying the following command: ```python # jupyterhub_config.py c.Spawner.cmd = ["jupyter-labhub"] ``` -or for an otherwise customized Jupyter Server app, -set the environment variable: +Alternatively, for an otherwise customized Jupyter Server app, +set the environment variable using the following command: ```bash export JUPYTERHUB_SINGLEUSER_APP='jupyter_server.serverapp.ServerApp' From 066745158456bf5fb352e32dd71079d31c5eea10 Mon Sep 17 00:00:00 2001 From: Eshy10 Date: Fri, 14 Oct 2022 02:55:27 +0100 Subject: [PATCH 42/91] chore: remove duplicate version statement and add color to environments title --- docs/source/admin/upgrading.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index efe98c27..d7651d2d 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -63,11 +63,11 @@ Upgrade JupyterHub packages There are two environments where the ``jupyterhub`` package is installed: -#. The *hub environment*, which is where the JupyterHub server process +#. The *hub environment*: which is 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*. This is where the user notebook +#. The *notebook user environments*: This is 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 @@ -92,8 +92,6 @@ with: conda install -c conda-forge jupyterhub== -Where ```` is the version of JupyterHub you are upgrading to. - 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. From e6e1e903865cc6f4de5c232b0362eeaca4be7629 Mon Sep 17 00:00:00 2001 From: Eshy10 Date: Fri, 14 Oct 2022 03:04:08 +0100 Subject: [PATCH 43/91] chore: captitalize the first letter on explation of hub environment --- docs/source/admin/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index d7651d2d..84e30cbf 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -63,7 +63,7 @@ Upgrade JupyterHub packages There are two environments where the ``jupyterhub`` package is installed: -#. The *hub environment*: which is where the JupyterHub server process +#. The *hub environment*: Which is where the JupyterHub server process runs. This is started with the ``jupyterhub`` command, and is what people generally think of as JupyterHub. From 714b5925f68ef9452154828328c54a1537624887 Mon Sep 17 00:00:00 2001 From: Arafat Abdussalam Date: Fri, 14 Oct 2022 02:51:40 -0700 Subject: [PATCH 44/91] Correction of previous commit I made a correction to my previous commit as suggested. I will def try to avoid such mistakes. --- docs/source/admin/log-messages.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/admin/log-messages.md b/docs/source/admin/log-messages.md index c2974260..057692b6 100644 --- a/docs/source/admin/log-messages.md +++ b/docs/source/admin/log-messages.md @@ -1,12 +1,12 @@ # Interpreting common log messages -In this subsection of the documentation, you will get to understand the meaning of common log messages and how to resolve them. When debugging errors and outages, it is very helpful to look at the logs emitted by JupyterHub. +When debugging errors and outages, looking at the logs emitted by JupyterHub is very helpful This page documents some common log messages and what they mean. ## Failing suspected API request to not-running server ### Example -When your screen displays the log message as shown below, you need not to get scared. +Your logs might be littered with lines that might look scary ``` [W 2022-03-10 17:25:19.774 JupyterHub base:1349] Failing suspected API request to not-running server: /hub/user//api/metrics/v1 @@ -14,7 +14,7 @@ When your screen displays the log message as shown below, you need not to get sc ### Cause -This likely cause is that the user's server has stopped running but they +This likely means that the user's server has stopped running but they still have a browser tab open. For example, you might have 3 tabs open, and shut your server down via one. Or you closed your laptop, your server was culled for inactivity, and then you reopen your laptop again! The From a785b8d38a0110e34d59e838794973c4b37570b9 Mon Sep 17 00:00:00 2001 From: Arafat Abdussalam Date: Fri, 14 Oct 2022 02:59:34 -0700 Subject: [PATCH 45/91] I made the correction to the PR I resolved my previous commit as suggested --- docs/source/reference/websecurity.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/reference/websecurity.md b/docs/source/reference/websecurity.md index d9a9a397..9de4b38b 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/reference/websecurity.md @@ -10,13 +10,13 @@ The **Security Overview** section helps you learn about: This overview also helps you obtain a deeper understanding of how JupyterHub works. -## Semi-trusted and Untrusted Users +## Semi-trusted and untrusted users JupyterHub is designed to be a _simple multi-user server for modestly sized groups_ of **semi-trusted** users. While the design reflects serving semi-trusted users, JupyterHub is not necessarily unsuitable for serving **untrusted** users. -Using JupyterHub with **untrusted** users entails more work by the +Using JupyterHub with **untrusted** users does mean more work by the administrator. Much care is required to secure a Hub, with extra caution on protecting users from each other as the Hub is serving untrusted users. @@ -41,7 +41,7 @@ To protect all users from each other, JupyterHub administrators must ensure that: - A user **does not have permission** to modify their single-user notebook server, - as well as: + including: - A user **may not** install new packages in the Python environment that runs their single-user server. - If the `PATH` is used to resolve the single-user executable (instead of From 7462cfa6fd96cbee892ef4965016b3337e215267 Mon Sep 17 00:00:00 2001 From: AdrianaHelga <58259099+AdrianaHelga@users.noreply.github.com> Date: Sun, 16 Oct 2022 11:01:21 +0300 Subject: [PATCH 46/91] Update services-basics.md --- docs/source/getting-started/services-basics.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/source/getting-started/services-basics.md b/docs/source/getting-started/services-basics.md index f32aefe2..b8c1eefb 100644 --- a/docs/source/getting-started/services-basics.md +++ b/docs/source/getting-started/services-basics.md @@ -24,7 +24,7 @@ Hub via the REST API. ## API Token basics -### Create an API token +### Step 1: Generate an API token To run such an external service, an API token must be created and provided to the service. @@ -43,12 +43,12 @@ generating an API token is available from the JupyterHub user interface: ![API TOKEN success page](../images/token-request-success.png) -### Pass environment variable with token to the Hub +### Step 2: Pass environment variable with token to the Hub In the case of `cull_idle_servers`, it is passed as the environment variable called `JUPYTERHUB_API_TOKEN`. -### Use API tokens for services and tasks that require external access +### Step 3: Use API tokens for services and tasks that require external access While API tokens are often associated with a specific user, API tokens can be used by services that require external access for activities @@ -62,7 +62,7 @@ c.JupyterHub.services = [ ] ``` -### Restart JupyterHub +### Step 4: Restart JupyterHub Upon restarting JupyterHub, you should see a message like below in the logs: @@ -78,16 +78,15 @@ single-user servers, and only cookies can be used for authentication. 0.8 supports using JupyterHub API tokens to authenticate to single-user servers. -## Configure the idle culler to run as a Hub-Managed Service +## How to configure the idle culler to run as a Hub-Managed Service -Install the idle culler: +### Step 1: Install the idle culler: ``` pip install jupyterhub-idle-culler ``` -In `jupyterhub_config.py`, add the following dictionary for the -`idle-culler` Service to the `c.JupyterHub.services` list: +### Step 2: In `jupyterhub_config.py`, add the following dictionary for the `idle-culler` Service to the `c.JupyterHub.services` list: ```python c.JupyterHub.services = [ @@ -127,7 +126,7 @@ It now needs the scopes: - `admin:servers` to start/stop servers ``` -## Run `cull-idle` manually as a standalone script +## How to run `cull-idle` manually as a standalone script Now you can run your script by providing it the API token and it will authenticate through the REST API to From bcaaaa2d35e9e0597178742bbeec92c293d8acd9 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Oct 2022 05:20:46 +0000 Subject: [PATCH 47/91] Bump docker/setup-qemu-action from 2.0.0 to 2.1.0 Bumps [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action) from 2.0.0 to 2.1.0. - [Release notes](https://github.com/docker/setup-qemu-action/releases) - [Commits](https://github.com/docker/setup-qemu-action/compare/8b122486cedac8393e77aa9734c3528886e4a1a8...e81a89b1732b9c48d79cd809d8d81d79c4647a18) --- updated-dependencies: - dependency-name: docker/setup-qemu-action dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e6e2f020..7834a43d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -108,7 +108,7 @@ jobs: # https://github.com/docker/build-push-action/tree/v2.4.0#usage # https://github.com/docker/build-push-action/blob/v2.4.0/docs/advanced/multi-platform.md - name: Set up QEMU (for docker buildx) - uses: docker/setup-qemu-action@8b122486cedac8393e77aa9734c3528886e4a1a8 # associated tag: v1.0.2 + uses: docker/setup-qemu-action@e81a89b1732b9c48d79cd809d8d81d79c4647a18 # associated tag: v1.0.2 - name: Set up Docker Buildx (for multi-arch builds) uses: docker/setup-buildx-action@dc7b9719a96d48369863986a06765841d7ea23f6 # associated tag: v1.1.2 From cf1dcd6f3a49f3b770720c25436ac1a83801863f Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Mon, 17 Oct 2022 10:59:20 +0100 Subject: [PATCH 48/91] Update config-user-env.md update --- docs/source/reference/config-user-env.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 251fee0c..134fc268 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -30,7 +30,7 @@ system-wide or in a shared environment. This installation location should always be in the same environment that `jupyterhub-singleuser` itself is installed in, and must be _readable and executable_ by your users. If you want users to be able to install additional -packages, they must also be _writable_ by your users. +packages, the installation location must also be _writable_ by your users. If you are using a standard system Python install, you would use: From c7f14eec141b895b297e19443b0b62949865b9b7 Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Mon, 17 Oct 2022 11:07:39 +0100 Subject: [PATCH 49/91] Update troubleshooting.md Removed static header items --- docs/source/troubleshooting.md | 31 ------------------------------- 1 file changed, 31 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 1f051859..fcbb345d 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -4,37 +4,6 @@ When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides links for identifying the cause of the problem and how to resolve it. -[_Behavior_](#behavior) - -- JupyterHub proxy fails to start -- sudospawner fails to run] -- What is the default behavior when none of the lists (admin, allowed, - allowed groups) are set? -- JupyterHub Docker container not accessible at localhost -- How can I kill ports from JupyterHub-managed services that have been orphaned? -- Why am I getting a Spawn failed error message? -- How can I run JupyterHub with sudo but use my current env vars and virtualenv location? - -[_Errors_](#errors) - -- Error 500 after spawning my single-user server -- Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error - -[_How do I...?_](#how-do-i) - -- Use a chained SSL certificate -- Install JupyterHub without a network connection -- I want access to the whole filesystem and still default users to their home directory -- How do I increase the number of pySpark executors on YARN? -- How do I use JupyterLab's prerelease version with JupyterHub? -- How do I set up JupyterHub for a workshop (when users are not known ahead of time)? -- How do I set up rotating daily logs? -- Toree integration with HDFS rack awareness script -- Where do I find Docker images and Dockerfiles related to JupyterHub? -- How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner? - -[_Troubleshooting commands_](#troubleshooting-commands) - ## Behavior ### JupyterHub proxy fails to start From ea88427b7f4804fc35885708e331cf5dd53fbc4d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Oct 2022 10:53:28 +0000 Subject: [PATCH 50/91] Bump docker/build-push-action from 3.1.1 to 3.2.0 Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 3.1.1 to 3.2.0. - [Release notes](https://github.com/docker/build-push-action/releases) - [Commits](https://github.com/docker/build-push-action/compare/c84f38281176d4c9cdb1626ffafcd6b3911b5d94...c56af957549030174b10d6867f20e78cfd7debc5) --- updated-dependencies: - dependency-name: docker/build-push-action dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- .github/workflows/release.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7834a43d..721d221c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -149,7 +149,7 @@ jobs: branchRegex: ^\w[\w-.]*$ - name: Build and push jupyterhub - uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94 + uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5 with: context: . platforms: linux/amd64,linux/arm64 @@ -170,7 +170,7 @@ jobs: branchRegex: ^\w[\w-.]*$ - name: Build and push jupyterhub-onbuild - uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94 + uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5 with: build-args: | BASE_IMAGE=${{ fromJson(steps.jupyterhubtags.outputs.tags)[0] }} @@ -191,7 +191,7 @@ jobs: branchRegex: ^\w[\w-.]*$ - name: Build and push jupyterhub-demo - uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94 + uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5 with: build-args: | BASE_IMAGE=${{ fromJson(steps.onbuildtags.outputs.tags)[0] }} @@ -215,7 +215,7 @@ jobs: branchRegex: ^\w[\w-.]*$ - name: Build and push jupyterhub/singleuser - uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94 + uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5 with: build-args: | JUPYTERHUB_VERSION=${{ github.ref_type == 'tag' && github.ref_name || format('git:{0}', github.sha) }} From 9d630add9a2906fbc5517daae8455ffbfbd16e4e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 17 Oct 2022 10:53:28 +0000 Subject: [PATCH 51/91] Bump docker/setup-buildx-action from 2.0.0 to 2.1.0 Bumps [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) from 2.0.0 to 2.1.0. - [Release notes](https://github.com/docker/setup-buildx-action/releases) - [Commits](https://github.com/docker/setup-buildx-action/compare/dc7b9719a96d48369863986a06765841d7ea23f6...95cb08cb2672c73d4ffd2f422e6d11953d2a9c70) --- updated-dependencies: - dependency-name: docker/setup-buildx-action dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7834a43d..b61337f1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -111,7 +111,7 @@ jobs: uses: docker/setup-qemu-action@e81a89b1732b9c48d79cd809d8d81d79c4647a18 # associated tag: v1.0.2 - name: Set up Docker Buildx (for multi-arch builds) - uses: docker/setup-buildx-action@dc7b9719a96d48369863986a06765841d7ea23f6 # associated tag: v1.1.2 + uses: docker/setup-buildx-action@95cb08cb2672c73d4ffd2f422e6d11953d2a9c70 # associated tag: v1.1.2 with: # Allows pushing to registry on localhost:5000 driver-opts: network=host From fc6d93bbe37209f796bc15a344cfb62a078400c8 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Mon, 17 Oct 2022 13:20:02 +0100 Subject: [PATCH 52/91] Update docs/source/rbac/tech-implementation.md Replace URLs with internal markdown link Co-authored-by: Min RK --- docs/source/rbac/tech-implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/rbac/tech-implementation.md b/docs/source/rbac/tech-implementation.md index b3084ed5..2a8561ca 100644 --- a/docs/source/rbac/tech-implementation.md +++ b/docs/source/rbac/tech-implementation.md @@ -1,6 +1,6 @@ # Technical Implementation -[Roles](https://jupyterhub.readthedocs.io/en/stable/rbac/roles.html#roles) are stored in the database, where they are associated with users, services, groups and tokens. Roles can be added or modified as explained in the {ref}`define-role-target` section. Users, services, groups, and tokens can gain, change, and lose roles. This is currently achieved via `jupyterhub_config.py` (see {ref}`define-role-target`) and will be made available via API in the future. The latter will allow for changing a token's role, and thereby its permissions, without the need to issue a new token. +[Roles](roles) are stored in the database, where they are associated with users, services, and groups. Roles can be added or modified as explained in the {ref}`define-role-target` section. Users, services, groups, and tokens can gain, change, and lose roles. This is currently achieved via `jupyterhub_config.py` (see {ref}`define-role-target`) and will be made available via API in the future. The latter will allow for changing a user's role, and thereby its permissions, without the need to restart JupyterHub. Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. Scope variables take on five different formats that are reflected throughout the utilities via specific nomenclature: From e7a325ed248796eab72874d0a3789bfaaa7b1aa7 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Mon, 17 Oct 2022 13:20:37 +0100 Subject: [PATCH 53/91] Update docs/source/rbac/tech-implementation.md update text Co-authored-by: Min RK --- docs/source/rbac/tech-implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/rbac/tech-implementation.md b/docs/source/rbac/tech-implementation.md index 2a8561ca..93558791 100644 --- a/docs/source/rbac/tech-implementation.md +++ b/docs/source/rbac/tech-implementation.md @@ -61,7 +61,7 @@ The API request is resolved without additional errors using the scope _intersect the Hub logs a warning in this case (see {ref}`Figure 2 `). Resolving a token's scope (yellow box in {ref}`Figure 1 `) corresponds to resolving all the roles of the token's owner (including the roles associated with their groups) and the token's own scopes into a set of scopes. The two sets are compared (Resolve the scopes box in orange in {ref}`Figure 1 `), taking into account the scope hierarchy. -If the token's scopes are a subset of the token owner's scopes, the token is issued with the requested scopes; if not, JupyterHub will throw an error. +If the token's scopes are a subset of the token owner's scopes, the token is issued with the requested scopes; if not, JupyterHub will raise an error. {ref}`Figure 1 ` below illustrates the steps involved. The orange rectangles highlight where in the process the roles and scopes are resolved. From 8d2a987c819c85b38030f6c5238d73efacc53db8 Mon Sep 17 00:00:00 2001 From: Simon Li Date: Mon, 17 Oct 2022 13:29:25 +0100 Subject: [PATCH 54/91] remove out of date commented tag version --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b61337f1..be80d54a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -111,7 +111,7 @@ jobs: uses: docker/setup-qemu-action@e81a89b1732b9c48d79cd809d8d81d79c4647a18 # associated tag: v1.0.2 - name: Set up Docker Buildx (for multi-arch builds) - uses: docker/setup-buildx-action@95cb08cb2672c73d4ffd2f422e6d11953d2a9c70 # associated tag: v1.1.2 + uses: docker/setup-buildx-action@95cb08cb2672c73d4ffd2f422e6d11953d2a9c70 with: # Allows pushing to registry on localhost:5000 driver-opts: network=host From 6ca5c1a276e661ee3eae717c2985994878c58e25 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Tue, 11 Oct 2022 01:10:11 +0100 Subject: [PATCH 55/91] Update documentation Fix structure of documentation to aid readability and flow. --- docs/source/contributing/community.md | 23 +++++++++++++++++++++++ docs/source/contributing/community.rst | 16 ---------------- 2 files changed, 23 insertions(+), 16 deletions(-) create mode 100644 docs/source/contributing/community.md delete mode 100644 docs/source/contributing/community.rst diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md new file mode 100644 index 00000000..dd1fb38e --- /dev/null +++ b/docs/source/contributing/community.md @@ -0,0 +1,23 @@ +# Community communication channels + +We use different channels of communication for different purposes. Whichever one you use will depend on what kind of communication you want to engage in. + +## Discourse +We use [Discourse](https://discourse.jupyter.org) for online discussions. Everyone in the Jupyter community is welcome to bring ideas and questions there. + +All our past and current discussions on Discourse are archived and searchable. This is why we recommend you first go to Discourse, so that discussions remain useful and accessible to the whole community. + +## Gitter +We use [our Gitter channel](https://gitter.im/jupyterhub/jupyterhub) for online, real-time text chat; a place for more ephemeral discussions. When you're not on Discourse, you can stop here to have other discussions on the fly. + +## Github Issues +Github issues are used for most long-form project discussions, bug reports and feature requests. + +Issues related to a specific authenticator or spawner should be opened in the appropriate repository for the authenticator or spawner. If you are using a specific JupyterHub distribution (such as [Zero to JupyterHub on Kubernetes](http://github.com/jupyterhub/zero-to-jupyterhub-k8s) or [The Littlest JupyterHub](http://github.com/jupyterhub/the-littlest-jupyterhub/)), you should open issues directly in their repository. + +If you cannot find a repository to open your issue in, do not worry! Open the issue in the [main JupyterHub repository](https://github.com/jupyterhub/jupyterhub/) and our community will help you figure it out. + +## Mailing List +A [mailing list](https://groups.google.com/forum/#!forum/jupyter) for all of Project Jupyter exists, along with one for [teaching with Jupyter Notebooks](https://groups.google.com/forum/#!forum/jupyter-education). + +**NOTE**: Our community is distributed across the world in various timezones, so please be patient if you do not get a response immediately! diff --git a/docs/source/contributing/community.rst b/docs/source/contributing/community.rst deleted file mode 100644 index fe88e40f..00000000 --- a/docs/source/contributing/community.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _contributing/community: - -================================ -Community communication channels -================================ - -`Discourse `_ is primarily used by the Jupyter community for discussions and support. Additionally, we use JupyterHub's primary Gitter channel, `jupyterhub/jupyterhub `_, for quick discussions, and GitHub issues for detailed discussions relating to modifying a repository's content. -If you have an issue with a certain authenticator or spawner, please report them to the relevant repository. If you are using a specific JupyterHub -distribution (such as `Zero to JupyterHub on Kubernetes `_ -or `The Littlest JupyterHub `_), -you should open issues directly in the respective repository. If you can not -find a repository to open your issue in, do not worry! Create it in the `main -JupyterHub repository `_ and our -community will help you figure it out. - -Please be patient if you do not recieve a response right away; keep in mind that our comunity is spread out over the globe in different timezones. From 838719e7aba20e6bff38e920ebb364502fd2c0ab Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 11 Oct 2022 00:18:15 +0000 Subject: [PATCH 56/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/contributing/community.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md index dd1fb38e..870e4309 100644 --- a/docs/source/contributing/community.md +++ b/docs/source/contributing/community.md @@ -3,21 +3,25 @@ We use different channels of communication for different purposes. Whichever one you use will depend on what kind of communication you want to engage in. ## Discourse + We use [Discourse](https://discourse.jupyter.org) for online discussions. Everyone in the Jupyter community is welcome to bring ideas and questions there. -All our past and current discussions on Discourse are archived and searchable. This is why we recommend you first go to Discourse, so that discussions remain useful and accessible to the whole community. +All our past and current discussions on Discourse are archived and searchable. This is why we recommend you first go to Discourse, so that discussions remain useful and accessible to the whole community. ## Gitter + We use [our Gitter channel](https://gitter.im/jupyterhub/jupyterhub) for online, real-time text chat; a place for more ephemeral discussions. When you're not on Discourse, you can stop here to have other discussions on the fly. ## Github Issues -Github issues are used for most long-form project discussions, bug reports and feature requests. + +Github issues are used for most long-form project discussions, bug reports and feature requests. Issues related to a specific authenticator or spawner should be opened in the appropriate repository for the authenticator or spawner. If you are using a specific JupyterHub distribution (such as [Zero to JupyterHub on Kubernetes](http://github.com/jupyterhub/zero-to-jupyterhub-k8s) or [The Littlest JupyterHub](http://github.com/jupyterhub/the-littlest-jupyterhub/)), you should open issues directly in their repository. If you cannot find a repository to open your issue in, do not worry! Open the issue in the [main JupyterHub repository](https://github.com/jupyterhub/jupyterhub/) and our community will help you figure it out. ## Mailing List + A [mailing list](https://groups.google.com/forum/#!forum/jupyter) for all of Project Jupyter exists, along with one for [teaching with Jupyter Notebooks](https://groups.google.com/forum/#!forum/jupyter-education). **NOTE**: Our community is distributed across the world in various timezones, so please be patient if you do not get a response immediately! From deaccdc6684e71ab41592091eb27290a852d56c8 Mon Sep 17 00:00:00 2001 From: Ojoachele Onuh Date: Mon, 17 Oct 2022 17:27:09 +0100 Subject: [PATCH 57/91] Resolved and updated corrections from previous pull request --- docs/source/rbac/tech-implementation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/rbac/tech-implementation.md b/docs/source/rbac/tech-implementation.md index eccb2d0b..1d479de6 100644 --- a/docs/source/rbac/tech-implementation.md +++ b/docs/source/rbac/tech-implementation.md @@ -78,15 +78,15 @@ Figure 1. Resolving roles and scopes during API token request With the RBAC framework, each authenticated JupyterHub API request is guarded by a scope decorator that specifies which scopes are required to gain the access to the API. When an API request is performed, the requesting API token's scopes are again intersected with its owner's (yellow box in {ref}`Figure 2 `) to ensure the token does not grant more permissions than its owner has at the request time (e.g., due to changing/losing roles). -If the owner's roles do not include some scopes of the token's scopes, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being parsed on. In the case of no _intersection_, an empty set of scopes will be used. +If the owner's roles do not include some scopes of the token's scopes, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being passed on. In the case of no _intersection_, an empty set of scopes will be used. -The parsed scopes are compared to the scopes required to access the API as follows: +The passed scopes are compared to the scopes required to access the API as follows: -- if the API scopes are present within the set of parsed scopes, the access is granted and the API returns its "full" response +- if the API scopes are present within the set of passed scopes, the access is granted and the API returns its "full" response -- if that is not the case, another check is utilized to determine if subscopes of the required API scopes can be found in the parsed scope set: +- if that is not the case, another check is utilized to determine if subscopes of the required API scopes can be found in the passed scope set: - - if found, the RBAC framework employs the {ref}`filtering ` procedures to refine the API response to access only resource attributes corresponding to the parsed scopes. For example, providing a scope `read:users:activity!group=class-C` for the _GET /users_ API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model + - if found, the RBAC framework employs the {ref}`filtering ` procedures to refine the API response to access only resource attributes corresponding to the passed scopes. For example, providing a scope `read:users:activity!group=class-C` for the _GET /users_ API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model - if not found, the access to API is denied From 79ea4038e552b362be8def8f1b5d27072dd84f82 Mon Sep 17 00:00:00 2001 From: Shloka Date: Mon, 17 Oct 2022 22:30:47 +0530 Subject: [PATCH 58/91] Update docs/source/contributing/tests.rst Co-authored-by: Min RK --- docs/source/contributing/tests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index bc3fc7a5..0dee7e9a 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -104,7 +104,7 @@ 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 can access JupyterHub from your browser at http://localhost:8000 after starting ``jupyterhub`` in your command line. +Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and are able to access JupyterHub from your browser at http://localhost:8000 after starting ``jupyterhub`` in your command line. Code formatting and linting From 15b88577283c92585bbde197363a0eabffe28cf8 Mon Sep 17 00:00:00 2001 From: Shloka Date: Mon, 17 Oct 2022 22:30:55 +0530 Subject: [PATCH 59/91] Update docs/source/contributing/tests.rst Co-authored-by: Min RK --- docs/source/contributing/tests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index 0dee7e9a..8904b8c1 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -13,7 +13,7 @@ Running the tests ================== #. Make sure you have completed :ref:`contributing/setup`. Once completed, you should be able - to run ``jupyterhub`` on your command line and access JupyterHub from your browser at http://localhost:8000. By doing this, it is ensured that the dev environment is properly set + to run ``jupyterhub`` on your command line and access JupyterHub from your browser at http://localhost:8000. Being able to run and access `jupyterhub` should mean that the dev environment is properly set up for tests to run. #. You can run all tests in JupyterHub From ae833d4a51b1133a9b3e65de62605f2443f0fe85 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Mon, 17 Oct 2022 18:09:49 +0100 Subject: [PATCH 60/91] Add link to gh oauth Co-authored-by: Georgiana --- docs/source/reference/config-ghoauth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/config-ghoauth.md b/docs/source/reference/config-ghoauth.md index 588b1f93..bd8e290b 100644 --- a/docs/source/reference/config-ghoauth.md +++ b/docs/source/reference/config-ghoauth.md @@ -5,7 +5,7 @@ deployment with the following assumptions: - Running JupyterHub on a single cloud server - Using SSL on the standard HTTPS port 443 -- Using GitHub OAuth (using OAuthenticator) for login +- Using GitHub OAuth (using [OAuthenticator](https://oauthenticator.readthedocs.io/en/latest)) for login - Using the default spawner (to configure other spawners, uncomment and edit `spawner_class` as well as follow the instructions for your desired spawner) - Users exist locally on the server From 97c72dd779af98910988b931b61717e990c0af4b Mon Sep 17 00:00:00 2001 From: PoorvajaRayas <106921794+PoorvajaRayas@users.noreply.github.com> Date: Tue, 18 Oct 2022 02:01:50 +0530 Subject: [PATCH 61/91] Update troubleshooting.md Improved the documentation to make it clearer --- docs/source/troubleshooting.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index fcbb345d..0edfac41 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -1,22 +1,23 @@ # Troubleshooting -When troubleshooting, you may see unexpected behaviors or receive an error +While troubleshooting, you may see unexpected behaviors or receive an error message. This section provides links for identifying the cause of the problem and how to resolve it. + ## Behavior ### JupyterHub proxy fails to start -If you have tried to start the JupyterHub proxy and it fails to start: +If you have tried to start the JupyterHub proxy and it fails to run: - check if the JupyterHub IP configuration setting is `c.JupyterHub.ip = '*'`; if it is, try `c.JupyterHub.ip = ''` - Try starting with `jupyterhub --ip=0.0.0.0` **Note**: If this occurs on Ubuntu/Debian, check that you are using a -recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with a version -of Node that is very old, and it is necessary to update Node. +recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with an older version +of Node and it is necessary to update Node. ### sudospawner fails to run @@ -37,11 +38,11 @@ to the config file, `jupyterhub_config.py`. When nothing is given for these lists, there will be no admins, and all users who can authenticate on the system (i.e. all the Unix users on the server with a password) will be allowed to start a server. The allowed username set lets you limit -this to a particular set of users, and admin_users lets you specify who +this to a particular set of users, and admin_users let you specify who among them may use the admin interface (not necessary, unless you need to do things like inspect other users' servers or modify the user list at runtime). -### JupyterHub Docker container not accessible at localhost +### What to do when JupyterHub Docker container is not accessible at localhost? Even though the command to start your Docker container exposes port 8000 (`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`), @@ -71,7 +72,7 @@ After successfully logging in to JupyterHub with a compatible authenticator, I g This issue occurs when the authenticator requires a local system user to exist. In these cases, you need to use a spawner that does not require an existing system user account, such as `DockerSpawner` or `KubeSpawner`. -### How can I run JupyterHub with sudo but use my current env vars and virtualenv location? +### How can I run JupyterHub with sudo but use my current environment variables and virtualenv location? When launching JupyterHub with `sudo jupyterhub` I get import errors and my environment variables don't work. @@ -87,7 +88,7 @@ sudo MY_ENV=abc123 \ ### Error 500 after spawning my single-user server -You receive a 500 error when accessing the URL `/user//...`. +You receive an Error 500 while accessing the URL `/user//...`. This is often seen when your single-user server cannot verify your user cookie with the Hub. @@ -100,7 +101,7 @@ There are two likely reasons for this: #### Symptoms The main symptom is a failure to load _any_ page served by the single-user -server, met with a 500 error. This is typically the first page at `/user/` +server, met with an Error 500. This is typically the first page at `/user/` after logging in or clicking "Start my server". When a single-user notebook server receives a request, the notebook server makes an API request to the Hub to check if the cookie corresponds to the right user. This request is logged. @@ -167,7 +168,7 @@ When your whole JupyterHub sits behind an organization proxy (_not_ a reverse pr [JupyterHub services](https://jupyterhub.readthedocs.io/en/stable/reference/services.html) allow processes to interact with JupyterHub's REST API. Example use-cases include: -- **Secure Testing**: provide a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems. +- **Secure Testing**: provides a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems. - **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such as grading assignments. - **Private Dashboards**: share dashboards with certain group members. @@ -194,7 +195,7 @@ With a docker container, pass in the environment variable with the run command: -e JUPYTERHUB_API_TOKEN=my_secret_token \ jupyter/datascience-notebook:latest -[This example](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-notebook/external) demonstrates how to combine the use of the `jupyterhub-singleuser` environment variables when launching a Notebook as an externally managed service. +[This example](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-notebook/external) demonstrates how to combine the use of the `jupyterhub-singleuser` environment variables when launching a Notebook as an externally managed service. ## How do I...? @@ -268,7 +269,7 @@ similar to this one: provides additional information. The [pySpark configuration documentation](https://spark.apache.org/docs/0.9.0/configuration.html) is also helpful for programmatic configuration examples. -### How do I use JupyterLab's prerelease version with JupyterHub? +### How do I use JupyterLab's pre-release version with JupyterHub? While JupyterLab is still under active development, we have had users ask about how to try out JupyterLab with JupyterHub. @@ -294,7 +295,7 @@ notebook servers to default to JupyterLab: ### How do I set up JupyterHub for a workshop (when users are not known ahead of time)? 1. Set up JupyterHub using OAuthenticator for GitHub authentication -2. Configure the admin list to have workshop leaders be listed with administrator privileges. +2. Configure the admin list to have workshop leaders listed with administrator privileges. Users will need a GitHub account to log in and be authenticated by the Hub. @@ -324,7 +325,7 @@ Or use syslog: ### Toree integration with HDFS rack awareness script -The Apache Toree kernel will have an issue when running with JupyterHub if the standard HDFS +The Apache Toree kernel will have an issue while running with JupyterHub if the standard HDFS rack awareness script is used. This will materialize in the logs as a repeated WARN: ```bash @@ -371,7 +372,7 @@ You can also tail logs to view them in real-time using the `-f` option: ## Troubleshooting commands The following commands provide additional detail about installed packages, -versions, and system information that may be helpful when troubleshooting +versions, and system information that may be helpful while troubleshooting a JupyterHub deployment. The commands are: - System and deployment information From b890a7486da28cce6a3a82a29b7bc2f43017c6d3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 17 Oct 2022 20:33:17 +0000 Subject: [PATCH 62/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 0edfac41..6950264a 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -4,7 +4,6 @@ While troubleshooting, you may see unexpected behaviors or receive an error message. This section provides links for identifying the cause of the problem and how to resolve it. - ## Behavior ### JupyterHub proxy fails to start @@ -195,7 +194,7 @@ With a docker container, pass in the environment variable with the run command: -e JUPYTERHUB_API_TOKEN=my_secret_token \ jupyter/datascience-notebook:latest -[This example](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-notebook/external) demonstrates how to combine the use of the `jupyterhub-singleuser` environment variables when launching a Notebook as an externally managed service. +[This example](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-notebook/external) demonstrates how to combine the use of the `jupyterhub-singleuser` environment variables when launching a Notebook as an externally managed service. ## How do I...? From 1041bc53b12bfddce396ff8369e2e200c6b85cb7 Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 18 Oct 2022 11:21:50 +0500 Subject: [PATCH 63/91] fix typo --- docs/source/admin/upgrading.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index 8b786143..65481265 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -5,12 +5,12 @@ Upgrading JupyterHub JupyterHub offers easy upgrade pathways between minor versions. This document describes how to do these upgrades. -If you are using `distributions `__, you +If you are using :ref:`a JupyterHub distribution `, you should consult the distribution's documentation on how to upgrade. This document is useful if you have set up your own JupyterHub without using a distribution. -The steps are discussed in detail. Most likely, +The steps are discussed in detail, so if you get stuck at any step you can always refer to this guide. Most likely, upgrading JupyterHub is painless, quick and with minimal user interruption. Read the Changelog @@ -27,7 +27,7 @@ Notify your users If you are using the default configuration where ``configurable-http-proxy`` is managed by JupyterHub, your users will see service disruption during -the upgrade process. You will need to notify them, and pick a time to do the +the upgrade process. You should notify them, and pick a time to do the upgrade where they will be least disrupted. If you are using a different proxy or running ``configurable-http-proxy`` @@ -50,7 +50,7 @@ Before doing an upgrade, it is critical to back up: Shut down JupyterHub -=================== +==================== Shut down the JupyterHub process. This would vary depending on how you have set up JupyterHub to run. Most likely, it is using a process @@ -64,7 +64,7 @@ There are two environments where the ``jupyterhub`` package is installed: #. The *hub environment*, which is where the JupyterHub server process runs. This is started with the ``jupyterhub`` command and is what - people generally think of it as JupyterHub. + people generally think of as JupyterHub. #. The *notebook user environments*. This is where the user's notebook servers are launched from and are probably custom to your own @@ -94,7 +94,7 @@ with: Where ```` is the version of JupyterHub you are upgrading to. 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 +are using. You might wish to upgrade those packages, too, along with JupyterHub or upgrade them separately. Upgrade JupyterHub database From d1ad045335498c6105f072ff01a1e4e96642fb3f Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 18 Oct 2022 11:55:48 +0500 Subject: [PATCH 64/91] update index.rst --- docs/source/events/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/events/index.rst b/docs/source/events/index.rst index b53c8448..f94bd9fc 100644 --- a/docs/source/events/index.rst +++ b/docs/source/events/index.rst @@ -1,7 +1,7 @@ Event logging and Telemetry -========================== +=========================== -JupyterHub can be configured to record structured events from a running server using Jupyter's `Telemetry System`_. The types of events that JupyterHub emits are defined by `JSON schemas`_ listed at the bottom of this `page `__. +JupyterHub can be configured to record structured events from a running server using Jupyter's `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 From 895d713370df32782e600a4d2178a2f36a32622d Mon Sep 17 00:00:00 2001 From: Tooba Jamal <52610124+ToobaJamal@users.noreply.github.com> Date: Tue, 18 Oct 2022 12:01:13 +0500 Subject: [PATCH 65/91] update spawners-basics.md --- docs/source/getting-started/spawners-basics.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/getting-started/spawners-basics.md b/docs/source/getting-started/spawners-basics.md index 9988c2f8..b264c043 100644 --- a/docs/source/getting-started/spawners-basics.md +++ b/docs/source/getting-started/spawners-basics.md @@ -1,12 +1,12 @@ # Spawners and single-user notebook servers -Since the single-user server is an instance of `jupyter notebook`, an entire separate -multi-process application, there are many aspects of that server that can be configured, and a lot +Since the single-user server is an instance of `jupyter notebook`, an entirely separate +multi-process application, there are many aspects of that server that can be configured and a lot of ways to express that configuration. At the JupyterHub level, you can set some values on the Spawner. The simplest of these is `Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root -notebook directory is the highest level directory users will be able to access in the notebook +notebook directory is the highest-level directory users will be able to access in the notebook dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is expanded to the user's home directory. @@ -14,13 +14,13 @@ expanded to the user's home directory. c.Spawner.notebook_dir = '~/notebooks' ``` -You can also specify extra command line arguments to the notebook server with: +You can also specify extra command line arguments to the notebook server with the following: ```python c.Spawner.args = ['--debug', '--profile=PHYS131'] ``` -This could be used to set the users default page for the single user server: +This could be used to set the user's default page for the single-user server: ```python c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb'] @@ -30,4 +30,4 @@ Since the single-user server extends the notebook server application, it still loads configuration from the `jupyter_notebook_config.py` config file. Each user may have one of these files in `$HOME/.jupyter/`. Jupyter also supports loading system-wide config files from `/etc/jupyter/`, -which is the place to put configuration that you want to affect all of your users. +which is the place to put the configuration that you want to affect all of your users. From 504ebe90127fa1a6ec0a462973d73a01462fd23f Mon Sep 17 00:00:00 2001 From: Teniola Olowookere <90247181+Teniola-theDev@users.noreply.github.com> Date: Tue, 18 Oct 2022 10:09:31 +0100 Subject: [PATCH 66/91] capitalized cli and added y to jupterhub --- docs/source/reference/spawners.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/reference/spawners.md b/docs/source/reference/spawners.md index 7c183018..afb58744 100644 --- a/docs/source/reference/spawners.md +++ b/docs/source/reference/spawners.md @@ -267,8 +267,8 @@ Spawners mainly do one thing: launch a command in an environment. The command-line is constructed from user configuration: -- Spawner.cmd (default: `['jupterhub-singleuser']`) -- Spawner.args (cli args to pass to the cmd, default: empty) +- Spawner.cmd (default: `['jupyterhub-singleuser']`) +- Spawner.args (CLI args to pass to the cmd, default: empty) where the configuration: @@ -319,12 +319,12 @@ Optional environment variables, depending on configuration: - JUPYTERHUB_ROOT_DIR - the root directory of the server (notebook directory), when Spawner.notebook_dir is defined (new in 2.0) - JUPYTERHUB_DEFAULT_URL - the default URL for the server (for redirects from /user/:name/), if Spawner.default_url is defined - (new in 2.0, previously passed via cli) + (new in 2.0, previously passed via CLI) - JUPYTERHUB_DEBUG=1 - generic debug flag, sets maximum log level when Spawner.debug is True - (new in 2.0, previously passed via cli) + (new in 2.0, previously passed via CLI) - JUPYTERHUB_DISABLE_USER_CONFIG=1 - disable loading user config, sets maximum log level when Spawner.debug is True (new in 2.0, - previously passed via cli) + previously passed via CLI) - JUPYTERHUB*[MEM|CPU]*[LIMIT_GUARANTEE] - the values of cpu and memory limits and guarantees. These are not expected to be enforced by the process, From 853f8accf5edf65e843939447eb4d274b84b8322 Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Tue, 18 Oct 2022 15:09:44 +0100 Subject: [PATCH 67/91] Update config-proxy.md update --- docs/source/reference/config-proxy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/reference/config-proxy.md b/docs/source/reference/config-proxy.md index 90e56b06..3c0e1866 100644 --- a/docs/source/reference/config-proxy.md +++ b/docs/source/reference/config-proxy.md @@ -51,7 +51,7 @@ server { listen 80; server_name HUB.DOMAIN.TLD; - # Send all requests to port 80 to 302 and redirect to HTTPS + # Send a redirect request using the $request_uri that was requested but via HTTPS return 302 https://$host$request_uri; } @@ -112,7 +112,7 @@ server { listen 80; server_name NO_HUB.DOMAIN.TLD; - # Send all requests to port 80 to 302 and redirect to HTTPS + # Send a redirect request using the $request_uri that was requested but via HTTPS return 302 https://$host$request_uri; } From 390efc1c5a203f4e5e53b06e3dbee41ea76b1b0f Mon Sep 17 00:00:00 2001 From: Alexander Chosen okon Date: Tue, 18 Oct 2022 23:24:53 +0000 Subject: [PATCH 68/91] removed the logo image and resolved some conflicts --- docs/source/reference/config-user-env.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 814dd365..facf263f 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -1,14 +1,10 @@ -![jupyterhub](https://jupyter.org/assets/homepage/hublogo.svg) - - # Configuring user environments To deploy JupyterHub means you are providing Jupyter notebook environments for multiple users. Often, this includes a desire to configure the user environment in a custom way. -Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook -server, most Jupyter notebook configuration and documentation also applies to single-user environments. +Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook server, most configuration and documentation that applies to Jupyter Notebook applies to the single-user environments. Configuration of user environments typically does not occur through JupyterHub itself, but rather through system- wide Jupyter's configuration, which is inherited by `jupyterhub-singleuser`. @@ -145,12 +141,12 @@ depending on what Spawner you are using. The first category is a **shared system (multi-user host)** where each user has a JupyterHub account, a home directory as well as being a real system user. In this example, shared configuration and installation -must be in a **system-wide** location, such as `/etc/` or `/usr/local` +must be in a 'system-wide' location, such as `/etc/` or `/usr/local` or a custom prefix such as `/opt/conda`. When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or -DockerSpawner), the 'system-wide' environment is the container image -which is used for users. +DockerSpawner), the 'system-wide' environment is really the container image +used for users. In both cases, you want to _avoid putting configuration in user home directories_ because users can change those configuration settings. Also, @@ -159,7 +155,7 @@ difficult for admins to update later. ## Named servers -By default, in a JupyterHub deployment, each user has only one server. +By default, in a JupyterHub deployment, each user has one server only. JupyterHub can, however, have multiple servers per user. This is mostly useful in deployments where users can configure the environment @@ -229,7 +225,7 @@ JupyterLab is now the default singleuser UI, if available, which is based on the [Jupyter Server][], no longer the legacy [Jupyter Notebook][] server. JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`), -and Jupyter server could be selected by specifying the following command: +and Jupyter server could be selected by specifying the following: ```python # jupyterhub_config.py From eaeef65560ab4efd52d57111700a71300e921a9b Mon Sep 17 00:00:00 2001 From: Goodness Chris-Ugari Date: Wed, 19 Oct 2022 09:34:42 +0100 Subject: [PATCH 69/91] Update config-proxy.md Update comment --- docs/source/reference/config-proxy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/reference/config-proxy.md b/docs/source/reference/config-proxy.md index 3c0e1866..09494ea0 100644 --- a/docs/source/reference/config-proxy.md +++ b/docs/source/reference/config-proxy.md @@ -51,7 +51,7 @@ server { listen 80; server_name HUB.DOMAIN.TLD; - # Send a redirect request using the $request_uri that was requested but via HTTPS + # Redirect the request to HTTPS return 302 https://$host$request_uri; } @@ -112,7 +112,7 @@ server { listen 80; server_name NO_HUB.DOMAIN.TLD; - # Send a redirect request using the $request_uri that was requested but via HTTPS + # Redirect the request to HTTPS return 302 https://$host$request_uri; } From 313623256f92eed8ae117be1d0dbae746e6b1312 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Wed, 19 Oct 2022 10:44:15 +0100 Subject: [PATCH 70/91] Update docs/source/contributing/community.md Co-authored-by: Georgiana --- docs/source/contributing/community.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md index 870e4309..1c8d79d3 100644 --- a/docs/source/contributing/community.md +++ b/docs/source/contributing/community.md @@ -2,7 +2,7 @@ We use different channels of communication for different purposes. Whichever one you use will depend on what kind of communication you want to engage in. -## Discourse +## Discourse (recommended) We use [Discourse](https://discourse.jupyter.org) for online discussions. Everyone in the Jupyter community is welcome to bring ideas and questions there. From c8aae0ea1c86076d55ebff508a0b84dc90cbd9a8 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Wed, 19 Oct 2022 10:44:41 +0100 Subject: [PATCH 71/91] Update docs/source/contributing/community.md Co-authored-by: Georgiana --- docs/source/contributing/community.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md index 1c8d79d3..13d6db19 100644 --- a/docs/source/contributing/community.md +++ b/docs/source/contributing/community.md @@ -4,7 +4,7 @@ We use different channels of communication for different purposes. Whichever one ## Discourse (recommended) -We use [Discourse](https://discourse.jupyter.org) for online discussions. Everyone in the Jupyter community is welcome to bring ideas and questions there. +We use [Discourse](https://discourse.jupyter.org) for online discussions and support questions. Everyone in the Jupyter community is welcome to bring ideas and questions there. All our past and current discussions on Discourse are archived and searchable. This is why we recommend you first go to Discourse, so that discussions remain useful and accessible to the whole community. From 84e1216dda71e0cbf6f473f913501290c6a26f51 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Wed, 19 Oct 2022 10:45:49 +0100 Subject: [PATCH 72/91] Update docs/source/contributing/community.md Co-authored-by: Georgiana --- docs/source/contributing/community.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md index 13d6db19..a1aecfa8 100644 --- a/docs/source/contributing/community.md +++ b/docs/source/contributing/community.md @@ -20,8 +20,5 @@ Issues related to a specific authenticator or spawner should be opened in the ap If you cannot find a repository to open your issue in, do not worry! Open the issue in the [main JupyterHub repository](https://github.com/jupyterhub/jupyterhub/) and our community will help you figure it out. -## Mailing List - -A [mailing list](https://groups.google.com/forum/#!forum/jupyter) for all of Project Jupyter exists, along with one for [teaching with Jupyter Notebooks](https://groups.google.com/forum/#!forum/jupyter-education). **NOTE**: Our community is distributed across the world in various timezones, so please be patient if you do not get a response immediately! From d407c96ee89aee5fce87c30ac10ad6783918e63d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 19 Oct 2022 09:47:26 +0000 Subject: [PATCH 73/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/contributing/community.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md index a1aecfa8..4687bf98 100644 --- a/docs/source/contributing/community.md +++ b/docs/source/contributing/community.md @@ -20,5 +20,4 @@ Issues related to a specific authenticator or spawner should be opened in the ap If you cannot find a repository to open your issue in, do not worry! Open the issue in the [main JupyterHub repository](https://github.com/jupyterhub/jupyterhub/) and our community will help you figure it out. - **NOTE**: Our community is distributed across the world in various timezones, so please be patient if you do not get a response immediately! From 7d73d5774ee5b7aae5917b7d11a366238a24dc49 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Wed, 19 Oct 2022 12:37:13 +0100 Subject: [PATCH 74/91] update websecurity.md - fix typos/edit text - add important links --- docs/source/reference/websecurity.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/source/reference/websecurity.md b/docs/source/reference/websecurity.md index 8473c3e9..b5ab2680 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/reference/websecurity.md @@ -16,9 +16,9 @@ JupyterHub is designed to be a _simple multi-user server for modestly sized groups_ of **semi-trusted** users. While the design reflects serving semi-trusted users, JupyterHub is not necessarily unsuitable for serving **untrusted** users. -Using JupyterHub with **untrusted** users does mean more work by the +Using JupyterHub with **untrusted** users does mean more work for the administrator. Much care is required to secure a Hub, with extra caution on -protecting users from each other as the Hub is serving untrusted users. +protecting users from each other, since the Hub serves untrusted users. One aspect of JupyterHub's _design simplicity_ for **semi-trusted** users is that the Hub and single-user servers are placed in a _single domain_, behind a @@ -47,7 +47,7 @@ ensure that: - If the `PATH` is used to resolve the single-user executable (instead of using an absolute path), a user **may not** create new files in any `PATH` directory that precedes the directory containing `jupyterhub-singleuser`. - - A user may not modify environment variables (e.g. PATH, PYTHONPATH) for + - A user may not modify environment variables (e.g. `PATH`, `PYTHONPATH`) for their single-user server. - A user **may not** modify the configuration of the notebook server (the `~/.jupyter` or `JUPYTER_CONFIG_DIR` directory). @@ -58,7 +58,7 @@ If any additional services are run on the same domain as the Hub, the services ## Mitigate security issues -Several approaches to mitigating these issues with configuration +The several approaches to mitigating security issues with configuration options provided by JupyterHub include: ### Enable subdomains @@ -76,10 +76,10 @@ resolves the cross-site issues. ### Disable user config -If subdomains are not available or not desirable, JupyterHub provides a +If subdomains are unavailable or undesirable, JupyterHub provides a configuration option `Spawner.disable_user_config`, which can be set to prevent the user-owned configuration files from being loaded. After implementing this -option, PATHs and package installation and PATHs are the other things that the +option, `PATH`s and package installation are the other things that the admin must enforce. ### Prevent spawners from evaluating shell configuration files @@ -119,14 +119,12 @@ extend to securing the `tcp` sockets as well. ## Security audits We recommend that you do periodic reviews of your deployment's security. It's -good practice to keep JupyterHub, configurable-http-proxy, and nodejs -versions up to date. +good practice to keep [JupyterHub](https://readthedocs.org/projects/jupyterhub/), [configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy), and [nodejs +versions](https://github.com/nodejs/Release) up to date. A handy website for testing your deployment is [Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html). -[configurable-http-proxy]: https://github.com/jupyterhub/configurable-http-proxy - ## Vulnerability reporting If you believe you’ve found a security vulnerability in JupyterHub, or any From 6f25abac2eab5fe4d90b87b88c16cb356bcd23a2 Mon Sep 17 00:00:00 2001 From: Alexander Chosen Okon Date: Wed, 19 Oct 2022 11:49:55 +0000 Subject: [PATCH 75/91] Update config-user-env.md I made a few changes to the spacing used. --- docs/source/reference/config-user-env.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index 0cd315be..10430c12 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -18,8 +18,7 @@ This section will focus on user environments, which includes the following: ## Installing packages -To make packages available to users, you will typically install packages -system-wide or in a shared environment. +To make packages available to users, you will typically install packages system-wide or in a shared environment. This installation location should always be in the same environment where `jupyterhub-singleuser` itself is installed, and must be _readable and executable_ by your users. If you want users to be able to install additional packages, it must also be _writable_ by your users. @@ -40,8 +39,7 @@ Alternatively, You may also use conda to install packages. To do this, ensure th and [IPython](https://ipython.readthedocs.io/en/stable/development/config.html) have their own configuration systems. -As a JupyterHub administrator, you will typically want to install and configure environments for all JupyterHub users. For example, let's say you wish for each student in -a class to have the same user environment configuration. +As a JupyterHub administrator, you will typically want to install and configure environments for all JupyterHub users. For example, let's say you wish for each student in a class to have the same user environment configuration. Jupyter and IPython support **"system-wide"** locations for configuration, which is the logical place to put global configuration that you want to affect all users. It's generally more efficient to configure user environments "system-wide",and it's a good practice to avoid creating files in the users' home directories. The typical locations for these config files are: From ecf486d678d15b0a0968a81fa58406a674a522b7 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 19 Oct 2022 11:59:09 +0000 Subject: [PATCH 76/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/reference/websecurity.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/reference/websecurity.md b/docs/source/reference/websecurity.md index 6cdf67d9..2e77f176 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/reference/websecurity.md @@ -126,7 +126,8 @@ versions](https://github.com/nodejs/Release) up to date. We recommend that you do periodic reviews of your deployment's security. It is good practice to keep JupyterHub, configurable-http-proxy, and nodejs versions up to date. ->>>>>>> main + +> > > > > > > main A handy website for testing your deployment is [Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html). From 9c044e863ac73c6d0d37eba06c931528a8ac1a23 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 19 Oct 2022 13:33:48 +0000 Subject: [PATCH 77/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/reference/config-user-env.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index d32f4d0a..cbf8abd5 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -23,13 +23,11 @@ This section will focus on user environments, which includes the following: To make packages available to users, you will typically install packages system-wide or in a shared environment. - This installation location should always be in the same environment where `jupyterhub-singleuser` itself is installed in, and must be _readable and executable_ by your users. If you want your users to be able to install additional packages, the installation location must also be _writable_ by your users. - If you are using a standard Python installation on your system, use the following command: ```bash @@ -78,6 +76,7 @@ with the following substitutions: ::: To enable Jupyter notebook's internal idle-shutdown behavior (requires notebook ≥ 5.4), set the following in the `/etc/jupyter/jupyter_server_config.py` file: + ```python # shutdown the server after no activity for an hour c.ServerApp.shutdown_no_activity_timeout = 60 * 60 @@ -92,12 +91,10 @@ c.MappingKernelManager.cull_interval = 2 * 60 You may have multiple Jupyter kernels installed and want to make sure that they are available to all of your users. This means installing kernelspecs either system-wide (e.g. in /usr/local/) or in the `sys.prefix` of JupyterHub itself. - Jupyter kernelspec installation is system-wide by default, but some kernels may default to installing kernelspecs in your home directory. These will need to be moved system-wide to ensure that they are accessible. - To see where your kernelspecs are, you can use the following command: ```bash @@ -133,16 +130,13 @@ or a custom prefix such as `/opt/conda`. When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or DockerSpawner), the 'system-wide' environment is really the container image used for users. - In both cases, you want to _avoid putting configuration in user home directories_ because users can change those configuration settings. Also, home directories typically persist once they are created, thereby making it difficult for admins to update later. ## Named servers - By default, in a JupyterHub deployment, each user has one server only. - JupyterHub can, however, have multiple servers per user. This is mostly useful in deployments where users can configure the environment in which their server will start (e.g. resource requests on an HPC cluster), so that a given user can have multiple configurations running at the same time, without having to stop and restart their own server. @@ -161,11 +155,9 @@ as well as the admin page: ![named servers on the admin page](../images/named-servers-admin.png) - Named servers can be accessed, created, started, stopped, and deleted from these pages. Activity tracking is now per server as well. - To limit the number of **named server** per user by setting a constant value, use this: ```python @@ -192,7 +184,6 @@ If `named_server_limit_per_user` is set to `0`, no limit is enforced. ## Switching back to the classic notebook - By default, the single-user server launches JupyterLab, which is based on [Jupyter Server][]. @@ -215,7 +206,6 @@ no longer the legacy [Jupyter Notebook][] server. JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`), and the Jupyter server could be selected by specifying the following: - ```python # jupyterhub_config.py c.Spawner.cmd = ["jupyter-labhub"] From 281658ccce2935c1b070232c5b8c511946fb315a Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Thu, 20 Oct 2022 07:48:52 +0100 Subject: [PATCH 78/91] update websecurity.md Delete erroneous text from merge conflict --- docs/source/reference/websecurity.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/source/reference/websecurity.md b/docs/source/reference/websecurity.md index 2e77f176..4b82c8d2 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/reference/websecurity.md @@ -118,16 +118,9 @@ extend to securing the `tcp` sockets as well. ## Security audits -<<<<<<< HEAD We recommend that you do periodic reviews of your deployment's security. It's good practice to keep [JupyterHub](https://readthedocs.org/projects/jupyterhub/), [configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy), and [nodejs versions](https://github.com/nodejs/Release) up to date. -======= -We recommend that you do periodic reviews of your deployment's security. It is -good practice to keep JupyterHub, configurable-http-proxy, and nodejs -versions up to date. - -> > > > > > > main A handy website for testing your deployment is [Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html). From 145ccfbd4f4820dfa3d94ae36bbe29466d63f60f Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Thu, 20 Oct 2022 10:36:59 +0100 Subject: [PATCH 79/91] update websecurity.md --- docs/source/reference/websecurity.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/reference/websecurity.md b/docs/source/reference/websecurity.md index 4b82c8d2..67d9e8f2 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/reference/websecurity.md @@ -119,12 +119,14 @@ extend to securing the `tcp` sockets as well. ## Security audits We recommend that you do periodic reviews of your deployment's security. It's -good practice to keep [JupyterHub](https://readthedocs.org/projects/jupyterhub/), [configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy), and [nodejs +good practice to keep [JupyterHub](https://readthedocs.org/projects/jupyterhub/), [configurable-http-proxy][], and [nodejs versions](https://github.com/nodejs/Release) up to date. A handy website for testing your deployment is [Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html). +[configurable-http-proxy]: https://github.com/jupyterhub/configurable-http-proxy + ## Vulnerability reporting If you believe you have found a security vulnerability in JupyterHub, or any From 91f06f49e0c7fd40b6c1e7fc0c3690194f408801 Mon Sep 17 00:00:00 2001 From: lumenCodes Date: Thu, 20 Oct 2022 12:54:42 +0100 Subject: [PATCH 80/91] update to the spawner basic file --- docs/source/getting-started/spawners-basics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/getting-started/spawners-basics.md b/docs/source/getting-started/spawners-basics.md index b264c043..9cc02631 100644 --- a/docs/source/getting-started/spawners-basics.md +++ b/docs/source/getting-started/spawners-basics.md @@ -1,7 +1,7 @@ # Spawners and single-user notebook servers -Since the single-user server is an instance of `jupyter notebook`, an entirely separate -multi-process application, there are many aspects of that server that can be configured and a lot +A Spawner starts each single-user notebook server. Since the single-user server is an instance of `jupyter notebook`, an entire separate +multi-process application, many aspects of that server can be configured and there are a lot of ways to express that configuration. At the JupyterHub level, you can set some values on the Spawner. The simplest of these is @@ -14,7 +14,7 @@ expanded to the user's home directory. c.Spawner.notebook_dir = '~/notebooks' ``` -You can also specify extra command line arguments to the notebook server with the following: +You can also specify extra command line arguments to the notebook server with: ```python c.Spawner.args = ['--debug', '--profile=PHYS131'] @@ -30,4 +30,4 @@ Since the single-user server extends the notebook server application, it still loads configuration from the `jupyter_notebook_config.py` config file. Each user may have one of these files in `$HOME/.jupyter/`. Jupyter also supports loading system-wide config files from `/etc/jupyter/`, -which is the place to put the configuration that you want to affect all of your users. +which is the place to put configuration that you want to affect all of your users. From cd3f37f6a6e237d6a195d5a3bfddb7a8cb72409d Mon Sep 17 00:00:00 2001 From: PoorvajaRayas <106921794+PoorvajaRayas@users.noreply.github.com> Date: Thu, 20 Oct 2022 17:24:55 +0530 Subject: [PATCH 81/91] Update troubleshooting.md --- docs/source/troubleshooting.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 6950264a..5363e295 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting -While troubleshooting, you may see unexpected behaviors or receive an error +When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides links for identifying the cause of the problem and how to resolve it. @@ -8,14 +8,14 @@ problem and how to resolve it. ### JupyterHub proxy fails to start -If you have tried to start the JupyterHub proxy and it fails to run: +If you have tried to start the JupyterHub proxy and it fails to start: - check if the JupyterHub IP configuration setting is `c.JupyterHub.ip = '*'`; if it is, try `c.JupyterHub.ip = ''` - Try starting with `jupyterhub --ip=0.0.0.0` **Note**: If this occurs on Ubuntu/Debian, check that you are using a -recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with an older version +recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with a very old version of Node and it is necessary to update Node. ### sudospawner fails to run @@ -37,7 +37,7 @@ to the config file, `jupyterhub_config.py`. When nothing is given for these lists, there will be no admins, and all users who can authenticate on the system (i.e. all the Unix users on the server with a password) will be allowed to start a server. The allowed username set lets you limit -this to a particular set of users, and admin_users let you specify who +this to a particular set of users, and admin_users lets you specify who among them may use the admin interface (not necessary, unless you need to do things like inspect other users' servers or modify the user list at runtime). @@ -87,7 +87,7 @@ sudo MY_ENV=abc123 \ ### Error 500 after spawning my single-user server -You receive an Error 500 while accessing the URL `/user//...`. +You receive a 500 error while accessing the URL `/user//...`. This is often seen when your single-user server cannot verify your user cookie with the Hub. @@ -100,7 +100,7 @@ There are two likely reasons for this: #### Symptoms The main symptom is a failure to load _any_ page served by the single-user -server, met with an Error 500. This is typically the first page at `/user/` +server, met with a 500 error. This is typically the first page at `/user/` after logging in or clicking "Start my server". When a single-user notebook server receives a request, the notebook server makes an API request to the Hub to check if the cookie corresponds to the right user. This request is logged. @@ -167,7 +167,7 @@ When your whole JupyterHub sits behind an organization proxy (_not_ a reverse pr [JupyterHub services](https://jupyterhub.readthedocs.io/en/stable/reference/services.html) allow processes to interact with JupyterHub's REST API. Example use-cases include: -- **Secure Testing**: provides a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems. +- **Secure Testing**: provide a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems. - **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such as grading assignments. - **Private Dashboards**: share dashboards with certain group members. @@ -324,7 +324,7 @@ Or use syslog: ### Toree integration with HDFS rack awareness script -The Apache Toree kernel will have an issue while running with JupyterHub if the standard HDFS +The Apache Toree kernel will have an issue when running with JupyterHub if the standard HDFS rack awareness script is used. This will materialize in the logs as a repeated WARN: ```bash @@ -371,7 +371,7 @@ You can also tail logs to view them in real-time using the `-f` option: ## Troubleshooting commands The following commands provide additional detail about installed packages, -versions, and system information that may be helpful while troubleshooting +versions, and system information that may be helpful when troubleshooting a JupyterHub deployment. The commands are: - System and deployment information From 9fcaf8df52e17b37493330cbdd67268ba0b5f9c8 Mon Sep 17 00:00:00 2001 From: Alexander Chosen Okon Date: Thu, 20 Oct 2022 11:55:23 +0000 Subject: [PATCH 82/91] further simplified the words in the document I made changes to some of the words used by simplifying them to ensure that all users can easily understand the document. --- docs/source/reference/config-user-env.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/reference/config-user-env.md b/docs/source/reference/config-user-env.md index cbf8abd5..3850dcbe 100644 --- a/docs/source/reference/config-user-env.md +++ b/docs/source/reference/config-user-env.md @@ -47,7 +47,7 @@ have their own configuration systems. As a JupyterHub administrator, you will typically want to install and configure environments for all JupyterHub users. For example, let's say you wish for each student in a class to have the same user environment configuration. -Jupyter and IPython support **"system-wide"** locations for configuration, which is the logical place to put global configuration that you want to affect all users. It's generally more efficient to configure user environments "system-wide",and it's a good practice to avoid creating files in the users' home directories. +Jupyter and IPython support **"system-wide"** locations for configuration, which is the logical place to put global configuration that you want to affect all users. It's generally more efficient to configure user environments "system-wide", and it's a good practice to avoid creating files in the users' home directories. The typical locations for these config files are: - **system-wide** in `/etc/{jupyter|ipython}` @@ -140,7 +140,7 @@ By default, in a JupyterHub deployment, each user has one server only. JupyterHub can, however, have multiple servers per user. This is mostly useful in deployments where users can configure the environment in which their server will start (e.g. resource requests on an HPC cluster), so that a given user can have multiple configurations running at the same time, without having to stop and restart their own server. -To allow named servers, use this: +To allow named servers, include this code snippet in your config file: ```python c.JupyterHub.allow_named_servers = True @@ -158,13 +158,13 @@ as well as the admin page: Named servers can be accessed, created, started, stopped, and deleted from these pages. Activity tracking is now per server as well. -To limit the number of **named server** per user by setting a constant value, use this: +To limit the number of **named server** per user by setting a constant value, include this code snippet in your config file: ```python c.JupyterHub.named_server_limit_per_user = 5 ``` -Alternatively, to use a callable/awaitable based on the handler object, use this: +Alternatively, to use a callable/awaitable based on the handler object, include this code snippet in your config file: ```python def named_server_limit_per_user_fn(handler): From 677895c3eb5597a87bebcf7ffb2450403b1f5765 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 20 Oct 2022 11:55:28 +0000 Subject: [PATCH 83/91] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 5363e295..cbbf20c1 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -15,7 +15,7 @@ If you have tried to start the JupyterHub proxy and it fails to start: - Try starting with `jupyterhub --ip=0.0.0.0` **Note**: If this occurs on Ubuntu/Debian, check that you are using a -recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with a very old version +recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with a very old version of Node and it is necessary to update Node. ### sudospawner fails to run From dd8259fb469b0a967009bb804cab0773ac128796 Mon Sep 17 00:00:00 2001 From: PoorvajaRayas <106921794+PoorvajaRayas@users.noreply.github.com> Date: Thu, 20 Oct 2022 17:47:13 +0530 Subject: [PATCH 84/91] Updated the document by making necessary changes --- docs/source/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index cbbf20c1..e27fe48e 100644 --- a/docs/source/troubleshooting.md +++ b/docs/source/troubleshooting.md @@ -41,7 +41,7 @@ this to a particular set of users, and admin_users lets you specify who among them may use the admin interface (not necessary, unless you need to do things like inspect other users' servers or modify the user list at runtime). -### What to do when JupyterHub Docker container is not accessible at localhost? +### JupyterHub Docker container is not accessible at localhost Even though the command to start your Docker container exposes port 8000 (`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`), From f71388633fc282050cde814f59fe4153684df81f Mon Sep 17 00:00:00 2001 From: Kelvin Obidozie Date: Thu, 20 Oct 2022 13:38:12 +0100 Subject: [PATCH 85/91] Added text to documentation for more readability --- docs/source/getting-started/config-basics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/getting-started/config-basics.md b/docs/source/getting-started/config-basics.md index 8b4babe6..03495a62 100644 --- a/docs/source/getting-started/config-basics.md +++ b/docs/source/getting-started/config-basics.md @@ -1,6 +1,6 @@ # Configuration Basics -The section contains basic information about configuring settings for a JupyterHub +This section contains basic information about configuring settings for a JupyterHub deployment. The [Technical Reference](../reference/index) documentation provides additional details. @@ -49,7 +49,7 @@ that Jupyter uses. ## Configure using command line options -To display all command line options that are available for configuration: +To display all command line options that are available for configuration run the following command: ```bash jupyterhub --help-all @@ -81,7 +81,7 @@ specific [authenticators](./authenticators-users-basics) and [spawners](./spawners-basics) can be set in the configuration file. This enables JupyterHub to be used with a variety of authentication methods or process control and deployment environments. [Some examples](../reference/config-examples), -meant as illustration, are: +meant as illustrations, are: - Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyterhub/oauthenticator) - Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyterhub/dockerspawner) From 248bf8ef835212ee828a43fc5e97a089e6faaa4c Mon Sep 17 00:00:00 2001 From: Eshy10 Date: Thu, 20 Oct 2022 14:25:36 +0100 Subject: [PATCH 86/91] chore: remove capitalize word and "This is" after the colon for environments --- docs/source/admin/upgrading.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/admin/upgrading.rst b/docs/source/admin/upgrading.rst index 84e30cbf..7e541726 100644 --- a/docs/source/admin/upgrading.rst +++ b/docs/source/admin/upgrading.rst @@ -63,11 +63,11 @@ Upgrade JupyterHub packages There are two environments where the ``jupyterhub`` package is installed: -#. The *hub environment*: Which is where the JupyterHub server process +#. 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*: This is where the user notebook +#. 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 From 8e111665cd8fd28e9ed91b838699a5ff097818ed Mon Sep 17 00:00:00 2001 From: Toyibat Adele Date: Thu, 20 Oct 2022 17:44:56 +0100 Subject: [PATCH 87/91] Added Punctuations and Capitalized words where necessary. --- docs/source/reference/oauth.md | 54 +++++++++++++++++----------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/source/reference/oauth.md b/docs/source/reference/oauth.md index a658eb90..7611e9be 100644 --- a/docs/source/reference/oauth.md +++ b/docs/source/reference/oauth.md @@ -30,19 +30,19 @@ Some relevant points: Here are some key definitions to keep in mind when we are talking about OAuth. You can also read more detail [here](https://www.oauth.com/oauth2-servers/definitions/). -- **provider** the entity responsible for managing identity and authorization, +- **provider**: The entity responsible for managing identity and authorization, always a web server. JupyterHub is _always_ an oauth provider for JupyterHub's components. When OAuthenticator is used, an external service, such as GitHub or KeyCloak, is also an oauth provider. -- **client** An entity that requests OAuth **tokens** on a user's behalf, +- **client**: An entity that requests OAuth **tokens** on a user's behalf, generally a web server of some kind. OAuth **clients** are services that _delegate_ authentication and/or authorization to an OAuth **provider**. JupyterHub _services_ or single-user _servers_ are OAuth **clients** of the JupyterHub **provider**. When OAuthenticator is used, JupyterHub is itself _also_ an OAuth **client** for the external oauth **provider**, e.g. GitHub. -- **browser** A user's web browser, which makes requests and stores things like cookies -- **token** The secret value used to represent a user's authorization. This is the final product of the OAuth process. -- **code** A short-lived temporary secret that the **client** exchanges +- **browser**: A user's web browser, which makes requests and stores things like cookies. +- **token**: The secret value used to represent a user's authorization. This is the final product of the OAuth process. +- **code**: A short-lived temporary secret that the **client** exchanges for a **token** at the conclusion of oauth, in what's generally called the "oauth callback handler." @@ -56,8 +56,8 @@ A single oauth flow generally goes like this: 1. A **browser** makes an HTTP request to an oauth **client**. 2. There are no credentials, so the client _redirects_ the browser to an "authorize" page on the oauth **provider** with some extra information: - - the oauth **client id** of the client itself - - the **redirect uri** to be redirected back to after completion + - the oauth **client id** of the client itself. + - the **redirect uri** to be redirected back to after completion. - the **scopes** requested, which the user should be presented with to confirm. This is the "X would like to be able to Y on your behalf. Allow this?" page you see on all the "Login with ..." pages around the Internet. 3. During this authorize step, @@ -77,8 +77,8 @@ That's the end of the requests made between the **browser** and the **provider** At this point: -- The browser is authenticated with the _provider_ -- The user's authorized permissions are recorded in an _oauth code_ +- The browser is authenticated with the _provider_. +- The user's authorized permissions are recorded in an _oauth code_. - The _provider_ knows that the given oauth client's requested permissions have been granted, but the client doesn't know this yet. - All requests so far have been made directly by the browser. No requests have originated at the client or provider. @@ -86,8 +86,8 @@ At this point: ### OAuth Client Handles Callback Request Now we get to finish the OAuth process. -Let's dig into what the oauth client does when it handles -the oauth callback request with the +Let's dig into what the OAuth client does when it handles +the OAuth callback request. - The OAuth client receives the _code_ and makes an API request to the _provider_ to exchange the code for a real _token_. This is the first direct request between the OAuth _client_ and the _provider_. @@ -113,24 +113,24 @@ So that's _one_ OAuth process. ## Full sequence of OAuth in JupyterHub -Let's go through the above oauth process in JupyterHub, +Let's go through the above OAuth process in JupyterHub, with specific examples of each HTTP request and what information is contained. -For bonus points, we are using the double-oauth example of JupyterHub configured with GitHubOAuthenticator. +For bonus points, we are using the double-OAuth example of JupyterHub configured with GitHubOAuthenticator. -To disambiguate, we will call the OAuth process where JupyterHub is the **provider** "internal oauth," -and the one with JupyterHub as a **client** "external oauth." +To disambiguate, we will call the OAuth process where JupyterHub is the **provider** "internal OAuth," +and the one with JupyterHub as a **client** "external OAuth." Our starting point: - a user's single-user server is running. Let's call them `danez` -- jupyterhub is running with GitHub as an oauth provider (this means two full instances of oauth), -- Danez has a fresh browser session with no cookies yet +- Jupyterhub is running with GitHub as an OAuth provider (this means two full instances of OAuth), +- Danez has a fresh browser session with no cookies yet. First request: - browser->single-user server running JupyterLab or Jupyter Classic - `GET /user/danez/notebooks/mynotebook.ipynb` -- no credentials, so single-user server (as an oauth **client**) starts internal oauth process with JupyterHub (the **provider**) +- no credentials, so single-user server (as an OAuth **client**) starts internal OAuth process with JupyterHub (the **provider**) - response: 302 redirect -> `/hub/api/oauth2/authorize` with: - client-id=`jupyterhub-user-danez` @@ -138,9 +138,9 @@ First request: Second request, following redirect: -- browser->jupyterhub +- browser->JupyterHub - `GET /hub/api/oauth2/authorize` -- no credentials, so jupyterhub starts external oauth process _with GitHub_ +- no credentials, so JupyterHub starts external OAuth process _with GitHub_ - response: 302 redirect -> `https://github.com/login/oauth/authorize` with: - client-id=`jupyterhub-client-uuid` @@ -154,8 +154,8 @@ c.JupyterHub.authenticator_class = 'github' ``` That means authenticating a request to the Hub itself starts -a _second_, external oauth process with GitHub as a provider. -This external oauth process is optional, though. +a _second_, external OAuth process with GitHub as a provider. +This external OAuth process is optional, though. If you were using the default username+password PAMAuthenticator, this redirect would have been to `/hub/login` instead, to present the user with a login form. @@ -171,7 +171,7 @@ Here, GitHub prompts for login and asks for confirmation of authorization After successful authorization (either by looking up a pre-existing authorization, or recording it via form submission) -GitHub issues an **oauth code** and redirects to `/hub/oauth_callback?code=github-code` +GitHub issues an **OAuth code** and redirects to `/hub/oauth_callback?code=github-code` Next request: @@ -194,9 +194,9 @@ The second: - request made with access **token** in the `Authorization` header - response is the user model, including username, email, etc. -Now the external oauth callback request completes with: +Now the external OAuth callback request completes with: -- set cookie on `/hub/` path, recording jupyterhub authentication so we don't need to do external oauth with GitHub again for a while +- set cookie on `/hub/` path, recording jupyterhub authentication so we don't need to do external OAuth with GitHub again for a while - redirect -> `/hub/api/oauth2/authorize` 🎉 At this point, we have completed our first OAuth flow! 🎉 @@ -211,14 +211,14 @@ Now, we get our first repeated request: 2. automatically accepts authorization (shortcut taken when a user is visiting their own server) - redirect -> `/user/danez/oauth_callback?code=jupyterhub-code` -Here, we start the same oauth callback process as before, but at Danez's single-user server for the _internal_ oauth +Here, we start the same OAuth callback process as before, but at Danez's single-user server for the _internal_ OAuth. - browser->single-user server - `GET /user/danez/oauth_callback` (in handler) -Inside the internal oauth callback handler, +Inside the internal OAuth callback handler, Danez's server makes two API requests to JupyterHub: The first: From fedcd22b0cfd3c7dde87e0693f3f1d8211a5ffd3 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Fri, 21 Oct 2022 01:29:31 +0100 Subject: [PATCH 88/91] update spawners.md --- docs/source/reference/spawners.md | 36 +++++++++++++++---------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/source/reference/spawners.md b/docs/source/reference/spawners.md index afb58744..921ed202 100644 --- a/docs/source/reference/spawners.md +++ b/docs/source/reference/spawners.md @@ -4,9 +4,9 @@ A [Spawner][] starts each single-user notebook server. The Spawner represents an abstract interface to a process, and a custom Spawner needs to be able to take three actions: -- start the process -- poll whether the process is still running -- stop the process +- start a process +- poll whether a process is still running +- stop a process ## Examples @@ -15,9 +15,9 @@ Some examples include: - [DockerSpawner](https://github.com/jupyterhub/dockerspawner) for spawning user servers in Docker containers - `dockerspawner.DockerSpawner` for spawning identical Docker containers for - each users + each user - `dockerspawner.SystemUserSpawner` for spawning Docker containers with an - environment and home directory for each users + environment and home directory for each user - both `DockerSpawner` and `SystemUserSpawner` also work with Docker Swarm for launching containers on remote machines - [SudoSpawner](https://github.com/jupyterhub/sudospawner) enables JupyterHub to @@ -34,7 +34,7 @@ Some examples include: ### Spawner.start -`Spawner.start` should start the single-user server for a single user. +`Spawner.start` starts a single-user server for a single user. Information about the user can be retrieved from `self.user`, an object encapsulating the user's name, authentication, and server info. @@ -69,13 +69,13 @@ via relaxing the `Spawner.start_timeout` config value. #### Note on IPs and ports -`Spawner.ip` and `Spawner.port` attributes set the _bind_ url, +`Spawner.ip` and `Spawner.port` attributes set the _bind_ URL, which the single-user server should listen on (passed to the single-user process via the `JUPYTERHUB_SERVICE_URL` environment variable). -The _return_ value is the ip and port (or full url) the Hub should _connect to_. +The _return_ value is the `ip` and `port` (or full URL) the Hub should _connect to_. These are not necessarily the same, and usually won't be in any Spawner that works with remote resources or containers. -The default for Spawner.ip, and Spawner.port is `127.0.0.1:{random}`, +The default for `Spawner.ip`, and `Spawner.port` is `127.0.0.1:{random}`, which is appropriate for Spawners that launch local processes, where everything is on localhost and each server needs its own port. For remote or container Spawners, it will often make sense to use a different value, @@ -111,7 +111,7 @@ class MySpawner(Spawner): #### Exception handling -When `Spawner.start` raises an Exception, a message can be passed on to the user via the exception via a `.jupyterhub_html_message` or `.jupyterhub_message` attribute. +When `Spawner.start` raises an Exception, a message can be passed on to the user via the exception using a `.jupyterhub_html_message` or `.jupyterhub_message` attribute. When the Exception has a `.jupyterhub_html_message` attribute, it will be rendered as HTML to the user. @@ -121,11 +121,11 @@ If both attributes are not present, the Exception will be shown to the user as u ### Spawner.poll -`Spawner.poll` should check if the spawner is still running. +`Spawner.poll` checks if the spawner is still running. It should return `None` if it is still running, and an integer exit status, otherwise. -For the local process case, `Spawner.poll` uses `os.kill(PID, 0)` +In the case of local processes, `Spawner.poll` uses `os.kill(PID, 0)` to check if the local process is still running. On Windows, it uses `psutil.pid_exists`. ### Spawner.stop @@ -141,7 +141,7 @@ A JSON-able dictionary of state can be used to store persisted information. Unlike start, stop, and poll methods, the state methods must not be coroutines. -For the single-process case, the Spawner state is only the process ID of the server: +In the case of single processes, the Spawner state is only the process ID of the server: ```python def get_state(self): @@ -297,18 +297,18 @@ Additional variables can be specified via the `Spawner.environment` configuratio The process environment is returned by `Spawner.get_env`, which specifies the following environment variables: -- JUPYTERHUB*SERVICE_URL - the \_bind* url where the server should launch its http server (`http://127.0.0.1:12345`). +- JUPYTERHUB*SERVICE_URL - the \_bind* URL where the server should launch its http server (`http://127.0.0.1:12345`). This includes Spawner.ip and Spawner.port; _new in 2.0, prior to 2.0 ip,port were on the command-line and only if specified_ - JUPYTERHUB_SERVICE_PREFIX - the URL prefix the service will run on (e.g. `/user/name/`) - JUPYTERHUB_USER - the JupyterHub user's username - JUPYTERHUB_SERVER_NAME - the server's name, if using named servers (default server has an empty name) -- JUPYTERHUB_API_URL - the full url for the JupyterHub API (http://17.0.0.1:8001/hub/api) -- JUPYTERHUB_BASE_URL - the base url of the whole jupyterhub deployment, i.e. the bit before `hub/` or `user/`, +- JUPYTERHUB_API_URL - the full URL for the JupyterHub API (http://17.0.0.1:8001/hub/api) +- JUPYTERHUB_BASE_URL - the base URL of the whole jupyterhub deployment, i.e. the bit before `hub/` or `user/`, as set by c.JupyterHub.base_url (default: `/`) - JUPYTERHUB_API_TOKEN - the API token the server can use to make requests to the Hub. This is also the OAuth client secret. - JUPYTERHUB_CLIENT_ID - the OAuth client ID for authenticating visitors. -- JUPYTERHUB_OAUTH_CALLBACK_URL - the callback URL to use in oauth, typically `/user/:name/oauth_callback` +- JUPYTERHUB_OAUTH_CALLBACK_URL - the callback URL to use in OAuth, typically `/user/:name/oauth_callback` - JUPYTERHUB_OAUTH_ACCESS_SCOPES - the scopes required to access the server (called JUPYTERHUB_OAUTH_SCOPES prior to 3.0) - JUPYTERHUB_OAUTH_CLIENT_ALLOWED_SCOPES - the scopes the service is allowed to request. If no scopes are requested explicitly, these scopes will be requested. @@ -326,7 +326,7 @@ Optional environment variables, depending on configuration: sets maximum log level when Spawner.debug is True (new in 2.0, previously passed via CLI) -- JUPYTERHUB*[MEM|CPU]*[LIMIT_GUARANTEE] - the values of cpu and memory limits and guarantees. +- JUPYTERHUB*[MEM|CPU]*[LIMIT_GUARANTEE] - the values of CPU and memory limits and guarantees. These are not expected to be enforced by the process, but are made available as a hint, e.g. for resource monitoring extensions. From 69869ee8230bbbfe37a9bef381f88da740963e19 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Fri, 21 Oct 2022 01:49:36 +0100 Subject: [PATCH 89/91] update spawners.md --- docs/source/reference/spawners.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/source/reference/spawners.md b/docs/source/reference/spawners.md index 921ed202..5d774a2d 100644 --- a/docs/source/reference/spawners.md +++ b/docs/source/reference/spawners.md @@ -34,7 +34,7 @@ Some examples include: ### Spawner.start -`Spawner.start` starts a single-user server for a single user. +`Spawner.start` should start a single-user server for a single user. Information about the user can be retrieved from `self.user`, an object encapsulating the user's name, authentication, and server info. @@ -283,7 +283,7 @@ would result in spawning the command: my-singleuser-wrapper --debug --flag ``` -The `Spawner.get_args()` method is how Spawner.args is accessed, +The `Spawner.get_args()` method is how `Spawner.args` is accessed, and can be used by Spawners to customize/extend user-provided arguments. Prior to 2.0, JupyterHub unconditionally added certain options _if specified_ to the command-line, @@ -297,14 +297,14 @@ Additional variables can be specified via the `Spawner.environment` configuratio The process environment is returned by `Spawner.get_env`, which specifies the following environment variables: -- JUPYTERHUB*SERVICE_URL - the \_bind* URL where the server should launch its http server (`http://127.0.0.1:12345`). - This includes Spawner.ip and Spawner.port; _new in 2.0, prior to 2.0 ip,port were on the command-line and only if specified_ +- JUPYTERHUB*SERVICE_URL - the \_bind* URL where the server should launch its HTTP server (`http://127.0.0.1:12345`). + This includes `Spawner.ip` and `Spawner.port`; _new in 2.0, prior to 2.0 `ip`, `port` were on the command-line and only if specified_ - JUPYTERHUB_SERVICE_PREFIX - the URL prefix the service will run on (e.g. `/user/name/`) - JUPYTERHUB_USER - the JupyterHub user's username - JUPYTERHUB_SERVER_NAME - the server's name, if using named servers (default server has an empty name) - JUPYTERHUB_API_URL - the full URL for the JupyterHub API (http://17.0.0.1:8001/hub/api) - JUPYTERHUB_BASE_URL - the base URL of the whole jupyterhub deployment, i.e. the bit before `hub/` or `user/`, - as set by c.JupyterHub.base_url (default: `/`) + as set by `c.JupyterHub.base_url` (default: `/`) - JUPYTERHUB_API_TOKEN - the API token the server can use to make requests to the Hub. This is also the OAuth client secret. - JUPYTERHUB_CLIENT_ID - the OAuth client ID for authenticating visitors. @@ -315,15 +315,15 @@ The process environment is returned by `Spawner.get_env`, which specifies the fo Optional environment variables, depending on configuration: -- JUPYTERHUB*SSL*[KEYFILE|CERTFILE|CLIENT_CI] - SSL configuration, when internal_ssl is enabled -- JUPYTERHUB_ROOT_DIR - the root directory of the server (notebook directory), when Spawner.notebook_dir is defined (new in 2.0) -- JUPYTERHUB_DEFAULT_URL - the default URL for the server (for redirects from /user/:name/), - if Spawner.default_url is defined +- JUPYTERHUB*SSL*[KEYFILE|CERTFILE|CLIENT_CI] - SSL configuration, when `internal_ssl` is enabled +- JUPYTERHUB_ROOT_DIR - the root directory of the server (notebook directory), when `Spawner.notebook_dir` is defined (new in 2.0) +- JUPYTERHUB_DEFAULT_URL - the default URL for the server (for redirects from `/user/:name/`), + if `Spawner.default_url` is defined (new in 2.0, previously passed via CLI) -- JUPYTERHUB_DEBUG=1 - generic debug flag, sets maximum log level when Spawner.debug is True +- JUPYTERHUB_DEBUG=1 - generic debug flag, sets maximum log level when `Spawner.debug` is True (new in 2.0, previously passed via CLI) - JUPYTERHUB_DISABLE_USER_CONFIG=1 - disable loading user config, - sets maximum log level when Spawner.debug is True (new in 2.0, + sets maximum log level when `Spawner.debug` is True (new in 2.0, previously passed via CLI) - JUPYTERHUB*[MEM|CPU]*[LIMIT_GUARANTEE] - the values of CPU and memory limits and guarantees. @@ -338,7 +338,7 @@ guarantees on resources, such as CPU and memory. To provide a consistent experience for sysadmins and users, we provide a standard way to set and discover these resource limits and guarantees, such as for memory and CPU. For the limits and guarantees to be useful, **the spawner must implement -support for them**. For example, LocalProcessSpawner, the default +support for them**. For example, `LocalProcessSpawner`, the default spawner, does not support limits and guarantees. One of the spawners that supports limits and guarantees is the `systemdspawner`. @@ -367,7 +367,7 @@ limits or guarantees are provided, and no environment values are set. `c.Spawner.cpu_limit`: In supported spawners, you can set `c.Spawner.cpu_limit` to limit the total number of cpu-cores that a single-user notebook server can use. These can be fractional - `0.5` means 50% -of one CPU core, `4.0` is 4 cpu-cores, etc. This value is also set in the +of one CPU core, `4.0` is 4 CPU-cores, etc. This value is also set in the single-user notebook server's environment variable `CPU_LIMIT`. The limit does not claim that you will be able to use all the CPU up to your limit as other higher priority applications might be taking up CPU. From a71f6be00176dd1ae5e4da434ff2bfb1f67ce097 Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Fri, 21 Oct 2022 12:04:45 +0100 Subject: [PATCH 90/91] Update docs/source/reference/spawners.md Co-authored-by: Sarah Gibson <44771837+sgibson91@users.noreply.github.com> --- docs/source/reference/spawners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/spawners.md b/docs/source/reference/spawners.md index 5d774a2d..bd6bd5c0 100644 --- a/docs/source/reference/spawners.md +++ b/docs/source/reference/spawners.md @@ -72,7 +72,7 @@ via relaxing the `Spawner.start_timeout` config value. `Spawner.ip` and `Spawner.port` attributes set the _bind_ URL, which the single-user server should listen on (passed to the single-user process via the `JUPYTERHUB_SERVICE_URL` environment variable). -The _return_ value is the `ip` and `port` (or full URL) the Hub should _connect to_. +The _return_ value is the IP and port (or full URL) the Hub should _connect to_. These are not necessarily the same, and usually won't be in any Spawner that works with remote resources or containers. The default for `Spawner.ip`, and `Spawner.port` is `127.0.0.1:{random}`, From 37b82f7c2ae45f3433326d052109e1ba3e36f1aa Mon Sep 17 00:00:00 2001 From: Christian Dike Date: Fri, 21 Oct 2022 12:05:12 +0100 Subject: [PATCH 91/91] Update docs/source/reference/spawners.md Co-authored-by: Sarah Gibson <44771837+sgibson91@users.noreply.github.com> --- docs/source/reference/spawners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/spawners.md b/docs/source/reference/spawners.md index bd6bd5c0..80b2bccd 100644 --- a/docs/source/reference/spawners.md +++ b/docs/source/reference/spawners.md @@ -298,7 +298,7 @@ Additional variables can be specified via the `Spawner.environment` configuratio The process environment is returned by `Spawner.get_env`, which specifies the following environment variables: - JUPYTERHUB*SERVICE_URL - the \_bind* URL where the server should launch its HTTP server (`http://127.0.0.1:12345`). - This includes `Spawner.ip` and `Spawner.port`; _new in 2.0, prior to 2.0 `ip`, `port` were on the command-line and only if specified_ + This includes `Spawner.ip` and `Spawner.port`; _new in 2.0, prior to 2.0 IP, port were on the command-line and only if specified_ - JUPYTERHUB_SERVICE_PREFIX - the URL prefix the service will run on (e.g. `/user/name/`) - JUPYTERHUB_USER - the JupyterHub user's username - JUPYTERHUB_SERVER_NAME - the server's name, if using named servers (default server has an empty name)