Merge pull request #68 from jupyterhub/guidance-resources

Add a how-to guide on selecting VM Memory / CPU / Disk size

docs/howto/resource-estimation.rst

@@ -0,0 +1,77 @@
+.. _howto/resource-estimation:
+
+===================================
+Estimate Memory / CPU / Disk needed
+===================================
+
+This page helps you estimate how much Memory / CPU / Disk the server you install
+The Littlest JupyterHub on should have. These are just guidelines to help
+with estimation - your actual needs will vary.
+
+Memory
+======
+
+Memory is usually the biggest determinant of server size in most JupyterHub
+installations.
+
+.. math::
+
+    Server Memory Recommended = (Maximum concurrent users \times Maximum memory allowed per user) + 128MB
+
+
+The ``128MB`` is overhead for TLJH and related services. **Server Memory Recommended**
+is the amount of Memory (RAM) the server you aquire should have - we recommend
+erring on the side of 'more Memory'. The other terms are explained below.
+
+Maximum concurrent users
+------------------------
+
+Even if your class has 100 students, most of them will not be using the JupyterHub
+actively at an given moment. At 2am on a normal night, maybe you'll have 10 students
+using it. At 2am before a final, maybe you'll have 60 students using it. Maybe
+you'll have a lab session with all 100 of your students using it at the same time.
+
+The *maximum* number of users actively using the JupyterHub at any given time determines
+how much memory your server will need. You'll get better at estimating this number
+over time. We generally recommend between 40-60% of your total class size to start with.
+
+Maximum memory allowed per user
+-------------------------------
+
+Depending on what kinda work your users are doing, they will use different amounts
+of memory. The easiest way to determine this is to run through a typical user
+workflow yourself, and measure how much memory is used. Add 20-40% headroom for
+users to 'play around', and that should be the maximum memory allowed per user.
+The system will prevent users from using more memory than this.
+
+CPU
+===
+
+CPU estimation is more forgiving than Memory estimation. If there isn't
+enough CPU for your users, their computation becomes very slow - but does not
+stop, unlike with RAM.
+
+.. math::
+
+    Server CPU Recommended = (Maximum concurrent users \times Maximum CPU usage per user) + 0.2
+
+The ``0.2`` is overhead for TLJH and related services. **Server CPU Recommended**
+is the amount of CPU the server you aquire should have. We recommend using
+the same process used to estimate Memory required for estimating CPU required.
+
+Disk space
+==========
+
+Unlike Memory & CPU, disk space is predicated on **total** number of users,
+rather than **maximum concurrent** users.
+
+.. math::
+
+    Server Disk Size Recommended = (Total \times Maximum disk usage per user) + 2GB
+
+Resizing your server
+====================
+
+Lots of cloud providers let your dynamically resize your server if you need it
+to be larger or smaller. Usually this requires a restart of the whole server -
+active users will be logged out, but otherwise usually nothing bad happens.

docs/index.rst

@@ -44,6 +44,7 @@ How-To guides answer the question 'How do I...?' for a lot of topics.
 
    howto/user-environment
    howto/notebook-interfaces
+   howto/resource-estimation
 
 Topic Guides
 ============

docs/tutorials/digitalocean.rst

@@ -43,6 +43,9 @@ Let's create the server on which we can run JupyterHub.
    (4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server
    later if you need.
 
+   Check out our guide on How To :ref:`howto/resource-estimation` to help pick
+   how much Memory, CPU & disk space your server needs.
+
 #. Scroll down to **Select additional options**, and select **User data**.
 
    .. image:: ../images/providers/digitalocean/additional-options.png

docs/tutorials/google.rst

@@ -83,8 +83,8 @@ Let's create the server on which we can run JupyterHub.
    .. image:: ../images/providers/google/machine-type-advanced.png
       :alt: Select a customized VM size
 
-   For more guidance on the different options available to you, as well as
+   Check out our guide on How To :ref:`howto/resource-estimation` to help pick
-   pricing considerations on Google Cloud, see the `GCP Choosing a VM Guide <https://cloud.google.com/compute/docs/instances/creating-instance-with-custom-machine-type?hl=en_US>`_.
+   how much Memory / CPU your server needs.
 
 #. Under **Boot Disk**, click the **Change** button. This lets us change the
    operating system and the size of your disk.
@@ -109,8 +109,8 @@ Let's create the server on which we can run JupyterHub.
    to a hard drive. **SSD persistent disk** gives you a faster but more expensive
    disk, similar to an SSD.
 
-   In Google Cloud, the higher your disk **size** the faster your disk is. The
+   Check out our guide on How To :ref:`howto/resource-estimation` to help pick
-   default (10GB) is pretty low, so you might want to increase it.
+   how much Disk space your server needs.
 
 #. Click the **Select** button to dismiss the Boot disk popup and go back to the
    Create an instance screen.

docs/tutorials/jetstream.rst

@@ -53,6 +53,10 @@ Let's create the server on which we can run JupyterHub.
 
    #. Give your server a descriptive **Instance Name**.
    #. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
+
+      Check out our guide on How To :ref:`howto/resource-estimation` to help pick
+      how much Memory, CPU & disk space your server needs.
+
    #. If you have multiple allocations, make sure you are 'charging' this server
       to the correct allocation.