small updates to the docs

docs/howto/auth/ldap.rst

@@ -0,0 +1,46 @@
+.. _howto/auth/ldap:
+
+=============================
+Using LDAP for authentication
+=============================
+
+`LDAP <https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`_
+is an open and widely-used protocol for authentication.
+
+The `LDAPAuthenticator's documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
+lists the various configuration options you can set for LDAPAuthenticator. You can set them
+in TLJH with the following pattern:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.<authenticator-name>.<config-option-name> <config-option-value>
+
+When the documentation asks you to set ``LDAPAuthenticator.server_address`` to some
+value, you can do that with the following command:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.LDAPAuthenticator.server_address = 'my-ldap-server'
+
+Enabling the authenticator
+==========================
+
+For LDAPAuthenticator, the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
+This is the same name that the `documentation asks <https://github.com/jupyterhub/ldapauthenticator#usage>`_
+you to set ``c.JupyterHub.authenticator_class`` to.
+
+For LDAPAuthenticator, this would be:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
+
+Once enabled, you need to reload JupyterHub for the config to take effect.
+
+.. code-block:: bash
+
+   sudo -E tljh-config reload
+
+Try logging in a separate incognito window to check if your configuration works. This
+lets you preserve your terminal in case there were errors. If there are
+errors, :ref:`troubleshooting/logs` should help you debug them.

docs/howto/resource-estimation.rst

@@ -40,9 +40,16 @@ 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
+workflow yourself, and measure how much memory is used.
-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.
+For example, you can begin running a Jupyter Notebook session on your JupyterHub, then open a
+terminal on the JupyterHub and use ``top`` to track how much memory you use
+as you go through the material. 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 kernel will restart (and all
+their progress in the current session will be lost).
 
 CPU
 ===
@@ -56,7 +63,7 @@ stop, unlike with RAM.
     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
+is the amount of CPU the server you acquire should have. We recommend using
 the same process used to estimate Memory required for estimating CPU required.
 
 Disk space

docs/index.rst

@@ -3,13 +3,13 @@ The Littlest JupyterHub
 =======================
 
 A simple `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_ distribution for
-a small (0-50) number of users on a single server.
+a small (0-100) number of users on a single server.
 
 Development Status
 ==================
 
 This project is currently in **alpha** state. Most things work, but we might
-still make breaking changes that have no clear upgrade pathway. We are targetting
+still make breaking changes that have no clear upgrade pathway. We are targeting
 a v0.1 release sometime in mid-August 2018. Follow `this milestone <https://github.com/jupyterhub/the-littlest-jupyterhub/milestone/1>`_
 to see progress towards the release!
 
@@ -61,13 +61,18 @@ How-To guides answer the question 'How do I...?' for a lot of topics.
    howto/notebook-interfaces
    howto/resource-estimation
 
+Authentication
+^^^^^^^^^^^^^^
+
 We have a special set of How-To Guides on using various forms of authentication
-with your JupyterHub.
+with your JupyterHub. For more information on Authentication, see
+:ref:`topic/authenticator-configuration`
 
 .. toctree::
    :titlesonly:
 
    howto/auth/dummy
+   howto/auth/ldap
 
 Topic Guides
 ============

docs/topic/authenticator-configuration.rst

@@ -24,6 +24,12 @@ example.
 Configuring the authenticator
 =============================
 
+Some authenticators have unique configuration options. This section covers a
+few common ones.
+
+LDAPAuthenticator
+^^^^^^^^^^^^^^^^^
+
 LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
 lists the various configuration options you can set for LDAPAuthenticator. You can set them
 in TLJH with the following pattern:
@@ -36,7 +42,7 @@ When the documentation asks you to set ``LDAPAuthenticator.server_address`` to s
 value, you can do that with the following command:
 
 .. code-block:: bash
-   
+
    sudo -E tljh-config set auth.LDAPAuthenticator.server_address = 'my-ldap-server'
 
 Most authenticators require you set multiple configuration options before you can
@@ -45,7 +51,9 @@ enable them. Read the authenticator's documentation carefully for more informati
 Enabling the authenticator
 ==========================
 
-Once you have configured the authenticator as you want, it should be enabled. 
+Once you have configured the authenticator as you want, you should then
+enable it. We'll use the LDAPAuthenticator as an example, though the process
+is similar for the other authenticators.
 
 .. code-block:: bash
 
@@ -70,4 +78,3 @@ Once enabled, you need to reload JupyterHub for the config to take effect.
 Try logging in a separate incognito window to check if your configuration works. This
 lets you preserve your terminal in case there were errors. If there are
 errors, :ref:`troubleshooting/logs` should help you debug them.
-

docs/topic/security.rst

@@ -10,7 +10,7 @@ information about the security model of The Littlest JupyterHub.
 System user accounts
 ====================
 
-Each JupyterHub user gets their own unix user account created when they
+Each JupyterHub user gets their own Unix user account created when they
 first start their server. This protects users from each other, gives them a
 home directory at a well known location, and allows sharing based on file system
 permissions.
@@ -38,8 +38,8 @@ command on the terminal. No password required.
 
 This is a **lot** of power, and they can do pretty much anything they want to
 the server - look at other people's work, modify it, break the server in cool &
-funky ways, etc. This also means if an admin's credentials are compromised (
+funky ways, etc. This also means **if an admin's credentials are compromised (
-easy to guess password, password re-use, etc) the entire JupyterHub is compromised.
+easy to guess password, password re-use, etc) the entire JupyterHub is compromised.**
 
 Off-boarding users securely
 ===========================
@@ -47,7 +47,13 @@ Off-boarding users securely
 When you delete users from the JupyterHub admin console, their unix user accounts
 are **not** removed. This means they might continue to have access to the server
 even after you remove them from JupyterHub. Admins should manually remove the user
-from the server & archive their home directories as needed. If the user removed
+from the server & archive their home directories as needed. For example, the
+following command deletes the user ``yuvi``.
+
+.. code-block::
+   userdel yuvi
+
+If the user removed
 from the server is an admin, extra care must be taken since they could have
 modified the system earlier to continue giving them access.
 
@@ -62,6 +68,5 @@ feature of systemd.
 HTTPS
 =====
 
-The Littlest JupyterHub does not currently support HTTPS. Follow `this issue
+Any internet-facing JupyterHub should use HTTPS to secure its traffic. For
-<https://github.com/jupyterhub/the-littlest-jupyterhub/issues/29>`_ for progress
+information on how to use HTTPS with your JupyterHub, see :ref:`_howto/https`.
-on HTTPS support.

docs/topic/tljh-config.rst

@@ -5,7 +5,7 @@ Configuring TLJH with ``tljh-config``
 =====================================
 
 ``tljh-config`` is the commandline program used to make configuration
-changes to TLJH. 
+changes to TLJH.
 
 Running ``tljh-config``
 ======================`
@@ -75,7 +75,7 @@ restarted and loaded with the new configuration.
 Advanced: ``config.yaml``
 =========================
 
-``tljh-config`` is a simple program that modifies the contents of the 
+``tljh-config`` is a simple program that modifies the contents of the
-``config.yaml`` file located at ``/opt/tljh/config.yaml``. ``tljh-config`` 
+``config.yaml`` file located at ``/opt/tljh/config.yaml``. ``tljh-config``
 is the recommended method of editing / viewing configuration since editing
-YAML by hand in a terminal text editor is a large source of errors.
+YAML by hand in a terminal text editor is a large source of errors.

docs/tutorials/nbgitpuller.rst

@@ -7,12 +7,12 @@ Distributing materials to users with nbgitpuller
 Goal
 ====
 
-A very common educational need when using JupyterHub for education is to easily
+A very common need when using JupyterHub is to easily
 distribute study materials / lab notebooks to students.
 
 Students should be able to:
 
-1. Easily get latest version of materials, including any updates the instructor
+1. Easily get the latest version of materials, including any updates the instructor
    has made to materials the student already has a copy of.
 2. Be confident they won't lose any of their work. If an instructor has modified
    something the student has also modified, the student's modification should
@@ -108,4 +108,10 @@ Step 2: Users click on the nbgitpuller link
 #. Users will now be redirected to the notebook specified in the URL!
 
 This workflow lets users land directly in the notebook you specified
-without having to understand much about git or the JupyterHub interface.
+without having to understand much about git or the JupyterHub interface.
+
+Advanced: hand-crafting an nbgitpuller link
+===========================================
+
+For information on hand-crafting an ``nbgitpuller`` link, see
+`the nbgitpuller README <https://github.com/jupyterhub/nbgitpuller#constructing-the-nbgitpuller-url>`_.