diff --git a/docs/howto/admin/enable-extensions.rst b/docs/howto/admin/enable-extensions.rst new file mode 100644 index 0000000..3dd5b18 --- /dev/null +++ b/docs/howto/admin/enable-extensions.rst @@ -0,0 +1,60 @@ +.. _howto/admin/extensions: + +==================================== +Enabling Jupyter Notebook extensions +==================================== + +Jupyter contributed notebook +`extensions `_ are +community-contributed and maintained plug-ins to the Jupyter notebook. These extensions +serve many purposes, from `pedagogical tools `_ +to tools for `converting `_ +and `editing `_ +notebooks. + +Extensions are often added and enabled through the graphical user interface of the notebook. +However, this interface only makes the extension available to the user, not all users on a +hub. Instead, to make contributed extensions available to your users, you will use the command +line. This can be completed using the terminal in the JupyterHub (or via SSH-ing into your +VM and using this terminal). + +.. _tljh_extension_cli: + +Enabling extensions via the command line +======================================== + +#. There are `multiple ways `_ + to install contributed extensions. For this example, we will use ``pip``. + + .. code-block:: bash + + sudo -E pip install jupyter_contrib_nbextensions + +#. Next, add the notebook extension style files to the Jupyter configuration files. + + .. code-block:: bash + + sudo -E jupyter contrib nbextension install --system + +#. Then, you will enable the extensions you would like to use. The syntax for this is + ``jupyter nbextension enable`` followed by the path to the desired extension's main file. + For example, to enable `scratchpad `_, + you would type the following: + + .. code-block:: bash + + sudo -E jupyter nbextension enable scratchpad/main --system + +#. When this is completed, the enabled extension should be visible in the extension list: + + .. code-block:: bash + + jupyter nbextension list + +#. You can also verify the availability of the extension via its user interface in the notebook. + For example, spellchecker adds an ABC checkmark icon to the interface. + + .. image:: ../../images/admin/enable-spellcheck.png + :alt: spellcheck-interface-changes + + diff --git a/docs/howto/admin/resize.rst b/docs/howto/admin/resize.rst index 95b897b..f0d0c12 100644 --- a/docs/howto/admin/resize.rst +++ b/docs/howto/admin/resize.rst @@ -1,15 +1,21 @@ .. _howto/admin/resize: -================= -Resizing a server -================= +================================================= +Resize the resources available to your JupyterHub +================================================= -As you are using your JupyterHub, you may find that you have a need to increase or decrease -the amount of resources allocated to your TLJH install. How resources can be reallocated -will depend on the server interface; consult the installation page for your provider for -more information. +As you are using your JupyterHub, you may need to increase or decrease +the amount of resources allocated to your TLJH install. The kinds of resources that can be +allocated, as well as the process to do so, will depend on the provider / interface for your +VM. We recommend consulting the installation page for your provider for more information. This +page covers the steps your should take on your JupyterHub *after* you've reallocated resources on +the cloud provider of your choice. -However, once resources have been reallocated, you must tell TLJH to make use of these resources, +Currently there are instructions to resize your resources on the following providers: + +* :ref:`Digital Ocean `. + +Once resources have been reallocated, you must tell TLJH to make use of these resources, and verify that the resources have become available. .. _tljh_verify: @@ -17,11 +23,10 @@ and verify that the resources have become available. Verifying a Resize ================== -#. Once you have resized your server, you will need to tell the JupyterHub to make use of - these new resources. To accomplish this, you will follow the instructions in - :ref:`topic/tljh-config` to edit :ref:`tljh-set-user-limits`, and - reload the hub. These steps can be completed using the terminal in the JupyterHub. - They can also be completed through the terminal. +#. Once you have resized your server, tell the JupyterHub to make use of + these new resources. To accomplish this, follow the instructions in + :ref:`topic/tljh-config` to set new memory or CPU limits and reload the hub. This can be completed + using the terminal in the JupyterHub (or via SSH-ing into your VM and using this terminal). #. TLJH configuration options can be verified by viewing the tljh-config output. @@ -29,28 +34,29 @@ Verifying a Resize sudo tljh-config show + Double-check that your changes are reflected in the output. -#. If you have changed your memory availability successfully, this will be reflected - in the `nbresuse `_ extension in the upper-right - when you open a Jupyter notebook on the Hub. +#. **To verify changes to memory**, confirm that it worked by starting + a new server (if you had one previously running, click "Control Panel -> Stop My Server" to + shut down your active server first), opening a notebook, and checking the value of the + `nbresuse `_ extension in the upper-right. .. image:: ../../images/nbresuse.png :alt: nbresuse demonstration -#. If you have changed the number of cores, this can be verified at the command line. - ``nproc`` displays the number of available cores, and should be equal to the +#. **To verify changes to CPU**, use the ``nproc`` from a terminal. + This command displays the number of available cores, and should be equal to the number of cores you selected in your provider's interface. .. code-block:: bash nproc --all - -#. Disk space changes can be verified, as well. The ``df`` command shows how much disk - space is available. The ``-hT`` argument allows us to have this printed in a human readable - format, and condenses the output to show one storage volume. +#. **To verify currently-available disk space**, use the ``df`` command in a terminal. This shows + how much disk space is available. The ``-hT`` argument allows us to have this printed in a human readable + format, and condenses the output to show one storage volume. Note that currently you cannot + change the disk space on a per-user basis. .. code-block:: bash df -hT /home - diff --git a/docs/howto/env/server-resources.rst b/docs/howto/env/server-resources.rst new file mode 100644 index 0000000..1295672 --- /dev/null +++ b/docs/howto/env/server-resources.rst @@ -0,0 +1,10 @@ +.. _howto/env/server-resources: + +====================================== +Configure resources available to users +====================================== + +To configure the resources that are available to your users (such as RAM, CPU +and Disk Space), see the section :ref:`tljh-set-user-limits`. For information +on **resizing** the environment available to users *after* you've created your +JupyterHub, see :ref:`howto/admin/resize`. diff --git a/docs/images/admin/enable-spellcheck.png b/docs/images/admin/enable-spellcheck.png new file mode 100644 index 0000000..af1cc94 Binary files /dev/null and b/docs/images/admin/enable-spellcheck.png differ diff --git a/docs/images/providers/digitalocean/power-off.png b/docs/images/providers/digitalocean/power-off.png new file mode 100644 index 0000000..7b6bbe6 Binary files /dev/null and b/docs/images/providers/digitalocean/power-off.png differ diff --git a/docs/index.rst b/docs/index.rst index 98f1c1f..1ad841c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,6 +58,7 @@ The user environment howto/env/user-environment howto/env/notebook-interfaces + howto/env/server-resources Authentication -------------- @@ -84,6 +85,8 @@ Administration and security howto/admin/resize howto/admin/nbresuse howto/admin/https + howto/admin/enable-extensions + Topic Guides ============ diff --git a/docs/install/digitalocean.rst b/docs/install/digitalocean.rst index 363f5e2..a4e316e 100644 --- a/docs/install/digitalocean.rst +++ b/docs/install/digitalocean.rst @@ -118,16 +118,38 @@ Step 3: Install conda / pip packages for all users .. include:: add_packages.txt +.. _digitalocean/resize: + Step 4: Resizing and editing the droplet ======================================== -#. As you are using your JupyterHub, you may find that you need more memory, - disk space, or CPUs. Digital Ocean servers can be resized in the - "Resize Droplet" panel. +As you use your JupyterHub, you may find that you need more memory, +disk space, or CPUs. Digital Ocean servers can be resized in the +"Resize Droplet" panel. These instructions take you through the process. + +#. First, click on the name of your newly-created + Droplet to enter its configuration page. + +#. Next, **turn off your Droplet**. This allows DigitalOcean to make + modifications to your VM. This will shut down your JupyterHub (temporarily). + + .. image:: ../images/providers/digitalocean/power-off.png + :alt: Power off your Droplet + :width: 200px + +#. Once your Droplet has been turned off, click "Resize", + which will take you to a menu with options to resize your VM. .. image:: ../images/providers/digitalocean/resize-droplet.png :alt: Resize panel of digital ocean - Further information on making more resources available to TLJH and verifying resource - availability can be found in the How-To :ref:`howto/admin/resize`. +#. Decide what kinds of resources you'd like to resize, then click on a new VM + type in the list below. Finally, click "Resize". This may take a few moments! + +#. Once your Droplet is resized, **turn your Droplet back on**. This makes your JupyterHub + available to the world once again. This will take a few moments to complete. + +Now that you've resized your Droplet, you may want to change the resources available +to your users. Further information on making more resources available to +users and verifying resource availability can be found in :ref:`howto/admin/resize`.