diff --git a/docs/contributing/docs.rst b/docs/contributing/docs.rst index e1429d4..9480889 100644 --- a/docs/contributing/docs.rst +++ b/docs/contributing/docs.rst @@ -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 ` diff --git a/docs/howto/admin/resource-estimation.rst b/docs/howto/admin/resource-estimation.rst index 96ef3e5..74bd077 100644 --- a/docs/howto/admin/resource-estimation.rst +++ b/docs/howto/admin/resource-estimation.rst @@ -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 ==================== diff --git a/docs/images/providers/amazon/completed_system_log.png b/docs/images/providers/amazon/completed_system_log.png new file mode 100644 index 0000000..bcdf58c Binary files /dev/null and b/docs/images/providers/amazon/completed_system_log.png differ diff --git a/docs/install/amazon.rst b/docs/install/amazon.rst index 5402350..184fd79 100644 --- a/docs/install/amazon.rst +++ b/docs/install/amazon.rst @@ -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 `_. +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 `_ 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 `_ 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 ```` 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. @@ -274,4 +273,4 @@ Step 2: Adding more users Step 3: Install conda / pip packages for all users ================================================== -.. include:: add_packages.txt \ No newline at end of file +.. include:: add_packages.txt