[MRG] updating content from zexuan's user test

docs/_static/custom.css

@@ -0,0 +1,3 @@
+div.sphinxsidebarwrapper h1.logo {
+  font-size: 2.3rem;
+}

docs/doc-requirements.txt

@@ -0,0 +1 @@
+sphinx_copybutton

docs/howto/admin/admin-users.rst

@@ -0,0 +1,101 @@
+.. _howto/admin/admin-users:
+
+========================
+Add / Remove admin users
+========================
+
+Admin users in TLJH have the following powers:
+
+#. Full root access to the server with passwordless ``sudo``.
+   This lets them do literally whatever they want in the server
+#. Access servers / home directories of all other users
+#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
+#. Change configuration of TLJH
+
+This is a lot of power, so make sure you know who you are giving it
+to. Admin users should have decent passwords / secure logni mechanisms,
+so attackers can not easily gain control of the system.
+
+.. important::
+
+   You should make sure an admin user is present when you **install** TLJH
+   the very first time. The ``:ref:`--admin <topic/customizing-installer/admin>```
+   flag passed to the installer does this. If you had forgotten to do so, the
+   easiest way to fix this is to run the installer again.
+
+Adding admin users from the JupyterHub interface
+================================================
+
+There are two primary user interfaces for doing work on your JupyterHub. By
+default, this is the Notebook Interface, and will be used in this section.
+If you are using JupyterLab, you can access the Notebook Interface by replacing
+``/lab`` with ``/tree`` in your URL.
+
+#. First, navigate to the Jupyter Notebook interface home page. You can do this
+   by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
+
+#. Open the **Control Panel** by clicking the control panel button on the top
+   right of your JupyterHub.
+
+   .. image:: ../../images/control-panel-button.png
+      :alt: Control panel button in notebook, top right
+
+#. In the control panel, open the **Admin** link in the top left.
+
+   .. image:: ../../images/admin/admin-access-button.png
+      :alt: Admin button in control panel, top left
+
+   This opens up the JupyterHub admin page, where you can add / delete users,
+   start / stop peoples' servers and see who is online.
+
+#. Click the **Add Users** button.
+
+   .. image:: ../../images/admin/add-users-button.png
+      :alt: Add Users button in the admin page
+
+   A **Add Users** dialog box opens up.
+
+#. Type the names of users you want to add to this JupyterHub in the dialog box,
+   one per line. **Make sure to tick the Admin checkbox**.
+
+   .. image:: ../../images/admin/add-users-dialog.png
+      :alt: Adding users with add users dialog
+
+#. Click the **Add Users** button in the dialog box. Your users are now added
+   to the JupyterHub with administrator privileges!
+
+Adding admin users from the command line
+========================================
+
+Sometimes it is easier to add or remove admin users from the command line (for
+example, if you forgot to add an admin user when first setting up your JupyterHub).
+
+Adding new admin users
+----------------------
+
+New admin users can be added by executing the following commands on an
+admin terminal:
+
+.. code-block:: bash
+
+   sudo -E tljh-config add-item users.admin <username>
+   sudo -E tljh-config reload
+
+If the user is already using the JupyterHub, they might have to stop and
+start their server from the control panel to gain new powers.
+
+Removing admin users
+--------------------
+
+You can remove an existing admin user by executing the following commands in
+an admin terminal:
+
+.. code-block:: bash
+
+   sudo -E tljh-config remove-item users.admin <username>
+   sudo -E tljh-config reload
+
+If the user is already using the JupyterHub, they will continue to have
+some of their admin powers until their server is stopped. Another admin
+can force their server to stop by clicking 'Stop Server' in the admin
+panel.

docs/howto/https.rst → docs/howto/admin/https.rst

@@ -1,4 +1,4 @@
-.. _howto/https:
+.. _howto/admin/https:
 
 ============
 Enable HTTPS

docs/howto/nbresuse.rst → docs/howto/admin/nbresuse.rst

@@ -1,4 +1,4 @@
-.. _howto/nbresuse:
+.. _howto/admin/nbresuse:
 
 =======================
 Check your memory usage
@@ -11,5 +11,5 @@ top right corner of the notebook interface. Note that this is memory usage
 for everything your user is running through the Jupyter notebook interface,
 not just the specific notebook it is shown on.
 
-.. image:: ../images/nbresuse.png
+.. image:: ../../images/nbresuse.png
    :alt: Memory limit / usage shown with nbresuse

docs/howto/resource-estimation.rst → docs/howto/admin/resource-estimation.rst

@@ -1,4 +1,4 @@
-.. _howto/resource-estimation:
+.. _howto/admin/resource-estimation:
 
 ===================================
 Estimate Memory / CPU / Disk needed
@@ -40,7 +40,7 @@ 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. You can use :ref:`howto/nbresuse`
+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.
 
 A good rule of thumb is to take the maximum amount of memory you used during

docs/howto/auth/firstuse.rst

@@ -0,0 +1,36 @@
+.. _howto/auth/firstuse:
+
+==================================================
+Let users choose a password when they first log in
+==================================================
+
+The **First Use Authenticator** lets users choose their own password.
+Upon their first log-in attempt, whatever password they use will be stored
+as their password for subsequent log in attempts. This is
+the default authenticator that ships with TLJH.
+
+Enabling the authenticator
+==========================
+
+.. note:: the FirstUseAuthenticator is enabled by default in TLJH.
+
+#. Enable the authenticator and reload config to apply the configuration:
+
+   sudo -E tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
+   sudo -E tljh-config reload
+
+Users who are currently logged in will continue to be logged in. When they
+log out and try to log back in, they will be asked to provide a username and
+password.
+
+Allowing anyone to log in to your JupyterHub
+============================================
+
+By default, you need to manually create user accounts before they will be able
+to log in to your JupyterHub. If you wish to allow **any** user to access
+the JupyterHub, run the following command.
+
+.. code-block:: bash
+
+   tljh-config set auth.FirstUseAuthenticator.create_users true
+   tljh-config reload

docs/howto/auth/github.rst

@@ -9,52 +9,81 @@ GitHub user ID / password. To do so, you'll first need to register an
 application with GitHub, and then provide information about this
 application to your ``tljh`` configuration.
 
-Enabling the authenticator
-==========================
-
 .. note::
 
    You'll need a GitHub account in order to complete these steps.
 
-#. Create a GitHub application
-   #. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
-   #. **Application name**: Choose a descriptive application name (e.g. ``tljh``)
-   #. **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
-   #. **Application description**: Use any description that you like.
-   #. **Authorization callback URL**: Insert text with the following form::
+Step 1: Create a GitHub application
+===================================
+
+#. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
+
+   * **Application name**: Choose a descriptive application name (e.g. ``tljh``)
+   * **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
+   * **Application description**: Use any description that you like.
+   * **Authorization callback URL**: Insert text with the following form::
 
-      http://<my-tljh-url>/hub/oauth_callback
+          http://<my-tljh-ip-address>/hub/oauth_callback
 
-   #. When you're done filling in the page, it should look something like this:
+   * When you're done filling in the page, it should look something like this:
 
       .. image:: ../../images/auth/github/create_application.png
          :alt: Create a GitHub OAuth application
-   #. Click "Register application".
-   #. You'll be taken to a page with the registered application details. Note
-      the **Client ID** and **Client Secret**, as you will use these later.
+#. Click "Register application". You'll be taken to a page with the registered application details.
+#. Copy the **Client ID** and **Client Secret** from the application details
+   page. You will use these later to configure your JupyterHub authenticator.
+
+   .. image:: ../../images/auth/github/client_id_secret.png
+     :alt: Your client ID and secret
+
+.. important::
+
+   If you are using a virtual machine from a cloud provider and
+   **stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
+   IP address** to it. In this case, **you must update your GitHub application information**
+   with the new IP address.
+
+Configure your JupyterHub to use the GitHub Oauthenticator
+==========================================================
+
+We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
+For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
+
+#. Log in as an administrator account to your JupyterHub.
+#. Open a terminal window.
+
+   .. image:: ../../images/notebook/new-terminal-button.png
+      :alt: New terminal button.
+
+#. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands::
+
+     sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
+
+   ::
+
+     sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
+
+#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
 
-      .. image:: ../../images/auth/github/client_id_secret.png
-        :alt: Your client ID and secret
+     sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
 
-#. Configure your JupyterHub to use the GitHub Oathenticator
-   #. Log in as an administrator account to your JupyterHub.
-   #. Open a terminal on your JupyterHub.
-   #. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands::
+#. Restart your JupyterHub so that new users see these changes::
 
-        sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
-        sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
+     sudo -E tljh-config reload
 
-   #. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
+Confirm that the new authentactor works
+=======================================
 
-        sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
+#. **Open an incognito window** in your browser (do not log out until you confirm
+   that the new authentication method works!)
+#. Go to your JupyterHub URL.
+#. You should see a GitHub login button like below:
 
-   #. Restart your JupyterHub so that new users see these changes::
+   .. image:: ../../images/auth/github/login_button.png
+      :alt: The GitHub authenticator login button.
 
-        sudo -E tljh-config reload
-#. Confirm that the new authentactor works.
-   #. Open an **incognito window** in your browser.
-   #. Go to your JupyterHub URL.
-   #. You should see a GitHub login button like below:
+#. After you log in with your GitHub credentials, you should be directed to the
+   Jupyter interface used in this JupyterHub.
 
-      .. image:: ../../images/auth/github/client_id_secret.png
-         :alt: The GitHub authenticator login button.
+#. **If this does not work** you can revert back to the default
+   JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`.