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 01/10] 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 02/10] 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 03/10] 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 04/10] 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 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 05/10] 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 06/10] 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 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 07/10] 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 08/10] 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 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 09/10] 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 10/10] 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