Merge pull request #181 from Paleantology/master

adding update on resizing droplet

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 <digitalocean/resize>`.
+
+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 <https://github.com/yuvipanda/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

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`.

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
 

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`. 
+

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 ``<property-path>`` 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 ``<property-path>`` 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 ``<property-path>`` 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 ``<property-path>`` 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``
 =========================