Add documentation on adding / removing admin users

docs/guides/admin.rst

@@ -1,57 +0,0 @@
-.. _admin_access:
-
-=====================
-Administrative Access
-=====================
-
-In The Littlest JupyterHub, we try to allow users to do as many administrative
-tasks as possible within JupyterHub itself. Admin users can:
-
-1. Have full root access with passwordless ``sudo``
-2. Install system-wide packages with ``apt``
-3. Install ``conda`` / ``pip`` packages for all JupyterHub users
-4. Change the amount of RAM / CPU available to each user, and more!
-
-By default, there are no admin users. You should add some after installation.
-
-Adding admin users
-==================
-
-Admin users are specified in the `YAML <https://en.wikipedia.org/wiki/YAML>`_
-config file at ``/opt/tljh/config.yaml``. This file is created upon installing
-tljh.
-
-1. Open the ``config.yaml`` file for editing.
-
-   .. code-block:: bash
-
-      sudo nano /opt/tljh/config.yaml
-
-2. Add usernames that should have admin access.
-
-   .. code-block:: yaml
-
-      users:
-        admin:
-          - user1
-          - user2
-
-   Be careful around the syntax - indentation matters, and you should be using
-   spaces and not tabs.
-
-   When you are done, save the file and exit. In ``nano``, you can do this with
-   ``Ctrl+X`` key.
-
-3. When you are sure the format is ok, restart JupyterHub to let the config take
-   effect.
-
-   .. code-block:: bash
-
-      sudo systemctl restart jupyterhub
-
-This should give you admin access from JupyterHub! You can verify this by:
-
-1. Opening a Terminal in your JupyterHub and checking if ``sudo`` works
-2. Opening your JupyterHub ``Control Panel`` and checking for the **Admin** tab
-
-From now on, you can use the JupyterHub to do most configuration changes.

docs/howto/admin-users.rst

@@ -0,0 +1,55 @@
+.. _howto/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.
+
+Make sure an admin user is present
+==================================
+
+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 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/index.rst

@@ -54,6 +54,7 @@ How-To guides answer the question 'How do I...?' for a lot of topics.
    :titlesonly:
 
    howto/user-environment
+   howto/admin-users
    howto/notebook-interfaces
    howto/resource-estimation
 
@@ -74,7 +75,6 @@ Topic guides provide in-depth explanations of specific topics.
    :titlesonly:
 
    topic/requirements
-   guides/admin
    topic/security
    topic/customizing-installer
    topic/tljh-config

docs/topic/customizing-installer.rst

@@ -13,6 +13,8 @@ is executed as:
 
 This page documents the various options you can pass as commandline parameters to the installer.
 
+.. _topic/customizing-installer/admin:
+
 Adding admin users
 ===================