zhangyiss/the-littlest-jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/the-littlest-jupyterhub.git synced 2025-12-18 21:54:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #296 from laxdog/master

Browse Source 
Update / clarify / shorten docs, add missing image from AWS install
This commit is contained in:
Yuvi Panda
2019-04-17 11:16:13 -07:00
committed by GitHub
parent 0e091c2de7 979b36c4d1
commit e90f453d7c
4 changed files with 52 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/contributing/docs.rst
View File

@@ -60,6 +60,12 @@ Then from the ``docs`` directory, build the HTML:
$ make html
If you encounter this error, it's likely that you are running inside a virtual environment.
.. code-block:: console
Error in "currentmodule" directive:
To get started contributing, you'll want to read the :ref:`reStructuredText
reference <sphinx:rst-index>`

19
docs/howto/admin/resource-estimation.rst
View File

@@ -16,7 +16,8 @@ installations.
.. math::
Server Memory Recommended = (Maximum concurrent users \times Maximum memory allowed per user) + 128MB
Recommended\, Memory =
(Max\, concurrent\, users \times Max\, mem\, per\, user) + 128MB
The ``128MB`` is overhead for TLJH and related services. **Server Memory Recommended**
@@ -27,7 +28,7 @@ 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
actively at a single 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.
@@ -38,7 +39,7 @@ over time. We generally recommend between 40-60% of your total class size to sta
Maximum memory allowed per user
-------------------------------
Depending on what kinda work your users are doing, they will use different amounts
Depending on what kind of 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. You can use :ref:`howto/admin/nbresuse`
to determine how much memory your user is using.
@@ -47,7 +48,7 @@ A good rule of thumb is to take the maximum amount of memory you used during
your session, and add 20-40% headroom for users to 'play around'. This is the
maximum amount of memory that should be given to each user.
If users use *more* than this alloted amount of memory, their notebook kernel will restart.
If users use *more* than this alloted amount of memory, their notebook kernel will *restart*.
CPU
===
@@ -58,11 +59,13 @@ stop, unlike with RAM.
.. math::
Server CPU Recommended = (Maximum concurrent users \times Maximum CPU usage per user) + 0.2
Recommended\, CPU = (Max\, concurrent\, users \times Max\, CPU\, usage\, per\, user) + 20\%
The ``0.2`` is overhead for TLJH and related services. **Server CPU Recommended**
is the amount of CPU the server you acquire should have. We recommend using
The ``20%`` is overhead for TLJH and related services. This is around 20% of a
single modern CPU. This, of course, is just an estimate. We recommend using
the same process used to estimate Memory required for estimating CPU required.
You cannot use nbresuse for this, but you should carry out normal workflow and
investigate the CPU usage on the machine.
Disk space
==========
@@ -72,7 +75,7 @@ rather than **maximum concurrent** users.
.. math::
Server Disk Size Recommended = (Total \times Maximum disk usage per user) + 2GB
Recommended\, Disk\, Size = (Total\, users \times Max\, disk\, usage\, per\, user) + 2GB
Resizing your server
====================

BIN
docs/images/providers/amazon/completed_system_log.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 108 KiB

69
docs/install/amazon.rst
View File

@@ -7,19 +7,19 @@ Installing on Amazon Web Services
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
`Amazon Web Services <https://aws.amazon.com/>`_.
To have a JupyterHub with admin users and a user environment with conda / pip packages.
Prerequisites
=============
#. An Amazon Web Services account. When you set it up, it will probably ask you
to set your default region.
#. An Amazon Web Services account.
There is a tier of compute use that is free for the first year that is fully
The `AWS free tier <https://aws.amazon.com/free/>`_ is fully
capable of running a minimal littlest Jupyterhub for testing purposes.
If asked to choose a default region, choose the one closest to the majority
of your users.
Step 1: Installing The Littlest JupyterHub
==========================================
@@ -31,9 +31,8 @@ Let's create the server on which we can run JupyterHub.
If you need to adjust your region from your default, there is a drop-down
menu between your name and the **Support** menu on the far right of the dark
navigation bar across the top of the window. Adjust the region of the
services you want to interact with now to match the closest one to the
majority of your users.
navigation bar across the top of the window. Adjust the region to match the
closest one to the majority of your users.
#. On the screen listing all the availabe services, pick **EC2** under **Compute**
on the left side at the top of the first column.
@@ -56,19 +55,19 @@ Let's create the server on which we can run JupyterHub.
:alt: Click launch instance
This will start the 'launch instance wizard' process. This lets you customize
the kind of server you want, the resources it will have & what it'll be called.
the kind of server you want, the resources it will have and its name.
#. On the page **Step 1: Choose an Amazon Machine Image (AMI)** you are going
to pick the base image your remote server machine will have. The view will
to pick the base image your remote server will have. The view will
default to the 'Quick-start' tab selected and just a few down the page, select
**Ubuntu Server 18.04 LTS (HVM), SSD Volume Type - ami-0ac019f4fcb7cb7e6**.
**Ubuntu Server 18.04 LTS (HVM), SSD Volume Type - ami-XXXXXXXXXXXXXXXXX**.
.. image:: ../images/providers/amazon/select_ubuntu_18.png
:alt: Click Ubuntu server 18.04
The `ami` alpha-numeric at the end references the specific Amazon machine
image. It may be different as Amazon updates these routinely. The
image, ignore this as Amazon updates them routinely. The
**Ubuntu Server 18.04 LTS (HVM)** is the important part.
@@ -84,21 +83,18 @@ Let's create the server on which we can run JupyterHub.
You may wish to consult the listing `here <https://www.ec2instances.info/>`_
because it shows cost per hour. The **On Demand** price is the pertinent cost.
(For point of reference, I was able to get a minimal hub that worked for
developing this tutorial using **t2.micro** tier. That tier is free for
Amazon users the first year they sign up. Two users were able to concurrently
access this development hub.)
(For reference, a minimal hub that worked for developing this tutorial used a
**t2.micro** tier, which is free for Amazon users the first year they sign
up. Two users were able to concurrently utilize this development hub without issue.)
If you want to **GPUs**, you'll have to scroll down about half way to find
the `GPU graphics` and `GPU compute` products.
``GPU graphics`` and ``GPU compute`` products are also available around half way down the page
#. Under **Step 3: Configure Instance Details**, scroll to the bottom of the page
and toggle the arrow next to **Advanced Details** to get the rest of the page to
drop down. Scroll down further to reveal a section entitled 'User data'. Copy
and toggle the arrow next to **Advanced Details**. Scroll down to 'User data'. Copy
the text below, and paste it into the **User data** text box. Replace
``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
configure it. **Remember to add your username**!
.. code-block:: bash
@@ -112,8 +108,8 @@ Let's create the server on which we can run JupyterHub.
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
See :ref:`topic/installer-actions` for a detailed description and
:ref:`topic/customizing-installer` for other options that can be used.
#. Under **Step 4: Add Storage**, you can change the **size** and **type of your
disk by adjusting the value in **Size (GiB)** and selecting **Volume Type**.
@@ -121,11 +117,11 @@ Let's create the server on which we can run JupyterHub.
.. image:: ../images/providers/amazon/change_size_type.png
:alt: Selecting disk size and type
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
Check out :ref:`howto/admin/resource-estimation` to help pick
how much Disk space your server needs.
Hover over the encircled `i` next to **Volume Type** for an explanation of
each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is
each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is
recommended for most workloads. With `Provisioned IOPS SSD (io1)` being the
highest-performance SSD volume. Magnetic (standard) is a previous generation
volume and not suited for a hub for multi-users.
@@ -150,7 +146,7 @@ Let's create the server on which we can run JupyterHub.
**Create a new security group**. You should give it a disitnguishing name
under **Security group name**
such as `ssh_web` for future reference. If you have, one from before you can
selectit and adjust it to have the rules you need, if oyu prefer.
select it and adjust it to have the rules you need, if you prefer.
The rules will default to include `SSH`. Leave that there, and then click on
the **Add Rule** button. Under **Type** for the new rule, change the field
@@ -186,8 +182,8 @@ Let's create the server on which we can run JupyterHub.
acknowledge your choice in order to proceed. If you already have a key pair you
can select to associate it with this instance, otherwise you need to
**Create a new key pair**. Choosing to `Proceed with a key pair` is not
recommended as you'll have no way to access your server if anything goes wrong
with the Jupyterhub amd no way to recover files via download.
recommended as you'll have no way to access your server via SSH if anything
goes wrong with the Jupyterhub and have no way to recover files via download.
Download and keep the key pair file unless you are associating one you already
have.
@@ -244,23 +240,26 @@ Let's create the server on which we can run JupyterHub.
expecting to see when trying the URL and things work.
While waiting until the appropriate time to try, another way to check if
things are churning away, is to open the **System Log**. To do this, go to
the **EC2 Management Console** & highlight the instance by clicking on that
the **EC2 Management Console** & highlight the instance by clicking on that
row and then right-click **Instance Settings** > **Get System Log**.
.. image:: ../images/providers/amazon/get_system_log.png
:alt: Getting system log.
When the Jupyterhub creation process works and the hub is ready to show you
the login the **System Log** will look like the image below if you scroll to
the bottom. Note the line **Starting TLJH installer**. (Somtimes I would
also see **Started jupyterhub.service** shortly after that, but not always.)
#. When the Jupyterhub creation process finishes and the hub is ready to show
the login, the **System Log** should look similar to the image below. Scroll to
the bottom of your output from the previous step.
Note the line **Starting TLJH installer**, you may also see **Started jupyterhub.service**
.. image:: ../images/providers/amazon/completed_system_log.png
:alt: Completed system log
#. When the installation is complete, it should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 6, and a password. Use a
#. Login using the **admin user name** you used in step 7, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.