diff --git a/docs/howto/admin/resize.rst b/docs/howto/admin/resize.rst new file mode 100644 index 0000000..d0e9548 --- /dev/null +++ b/docs/howto/admin/resize.rst @@ -0,0 +1,62 @@ +.. _howto/admin/resize: + +================================================= +Resize the resources available to your JupyterHub +================================================= + +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. + +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. + +.. _tljhconf: + +Verifying a Resize +================== + +#. 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. + + .. code-block:: bash + + sudo tljh-config show + + Double-check that your changes are reflected in the output. + +#. **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 + +#. **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 + +#. **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/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/images/providers/digitalocean/resize-droplet.png b/docs/images/providers/digitalocean/resize-droplet.png new file mode 100644 index 0000000..bc33a88 Binary files /dev/null and b/docs/images/providers/digitalocean/resize-droplet.png differ diff --git a/docs/index.rst b/docs/index.rst index 7488489..002ca8c 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 -------------- @@ -81,6 +82,7 @@ Administration and security howto/admin/admin-users howto/admin/resource-estimation + howto/admin/resize howto/admin/nbresuse howto/admin/https diff --git a/docs/install/digitalocean.rst b/docs/install/digitalocean.rst index a1e7041..a4e316e 100644 --- a/docs/install/digitalocean.rst +++ b/docs/install/digitalocean.rst @@ -117,3 +117,39 @@ Step 3: Install conda / pip packages for all users ================================================== .. include:: add_packages.txt + +.. _digitalocean/resize: + +Step 4: Resizing and editing the droplet +======================================== + +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 + +#. 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`. + diff --git a/docs/topic/tljh-config.rst b/docs/topic/tljh-config.rst index 901ae21..0570d63 100644 --- a/docs/topic/tljh-config.rst +++ b/docs/topic/tljh-config.rst @@ -8,17 +8,20 @@ Configuring TLJH with ``tljh-config`` changes to TLJH. Running ``tljh-config`` -======================` +======================= You can run ``tljh-config`` in two ways: #. From inside a terminal in JupyterHub while logged in as an admin user. - This method is **recommended**. + This method is recommended. #. By directly calling ``/opt/tljh/hub/bin/tljh-config`` as root when logged in to the server via other means (such as SSH). This is an advanced use case, and not covered much in this guide. +.. _tljh-set: + + Set a configuration property ============================ @@ -49,13 +52,21 @@ This can only set string and numerical properties, not lists. Some of the existing ```` are listed below by categories: -**Authentication** + +.. _tljh-set-auth: + +Authentication +-------------- Use ``auth.type`` to determine authenticator to use. All parameters in the config under ``auth.{auth.type}`` will be passed straight to the authenticators themselves. -**User Lists** +.. _tljh-set-user-lists: + +User Lists +---------- + * ``users.allowed`` takes in usernames to whitelist @@ -63,7 +74,11 @@ Some of the existing ```` are listed below by categories: * ``users.admin`` takes in usernames to designate as admins -**User Server Limits** +.. _tljh-set-user-limits: + +User Server Limits +------------------ + * ``limits.memory`` Specifies the maximum memory that can be used by each individual user. It can be specified as an absolute byte value. You can use @@ -90,7 +105,11 @@ Some of the existing ```` are listed below by categories: sudo tljh-config set limits.cpu 2 -**User Environment** +.. _tljh-set-user-env: + +User Environment +---------------- + ``user_environment.default_app`` Set default application users are launched into. Currently can be set to the following values @@ -100,6 +119,8 @@ Some of the existing ```` are listed below by categories: sudo tljh-config set user_environment.default_app jupyterlab +.. _tljh-view-conf: + View current configuration ========================== @@ -112,6 +133,9 @@ To see the current configuration, you can run the following command: This will print the current configuration of your TLJH. This is very useful when asking for support! +.. _tljh-reload-hub: + + Reloading JupyterHub to apply configuration =========================================== @@ -125,6 +149,8 @@ it to take effect. You can do so with: This should not affect any running users. The JupyterHub will be restarted and loaded with the new configuration. +.. _tljh-edit-yaml: + Advanced: ``config.yaml`` =========================