Document all the actions the installer performs

docs/index.rst

@@ -80,6 +80,7 @@ Topic guides provide in-depth explanations of specific topics.
    topic/requirements
    topic/security
    topic/customizing-installer
+   topic/installer-actions
    topic/tljh-config
    topic/authenticator-configuration
 

docs/topic/customizing-installer.rst

@@ -1,3 +1,5 @@
+.. _topic/customizing-installer:
+
 =========================
 Customizing the Installer
 =========================

docs/topic/installer-actions.rst

@@ -0,0 +1,92 @@
+.. _topic/installer-actions:
+
+===========================
+What does the installer do?
+===========================
+
+This document details what exactly the installer does to the machine it is 
+run on.
+
+``apt`` Packages installed
+==========================
+
+The packages ``python3`` and ``python3-venv`` are installed from the apt repositories.
+Since we need an recent & supported version of ``nodejs``, we install it from 
+`nodesource <https://github.com/nodesource/distributions>`_.
+
+Hub environment
+===============
+
+JupyterHub is run from a python3 virtual environment located in ``/opt/tljh/hub``. It
+uses the system's installed python and is owned by root. It also contains a ``npm``
+install of `configurable-http-proxy <https://github.com/jupyterhub/configurable-http-proxy>`_
+and a binary install of `traefik <http://traefik.io/>`_. This virtual environment is
+completely managed by TLJH.
+
+User environment
+================
+
+By default, a ``miniconda`` environment is installed in ``/opt/tljh/user``. This contains
+the notebook interface used to launch all users, and the various packages available to all
+users. The environment is owned by the ``root`` user. JupyterHub admins may use 
+to ``sudo -E conda install`` or ``sudo -E pip install`` packages into this environment.
+
+This conda environment is added to ``$PATH`` for all users started with JupyterHub. If you
+are using ``ssh`` instead, you can activate this environment by running the following:
+
+.. code-block:: bash
+
+   source /opt/tljh/user/bin/activate
+
+This should let you run various ``conda`` and ``pip`` commands. If  you run into errors like
+``Command 'conda' not found``, try prefixing your command with:
+
+.. code-block:: bash
+
+   sudo PATH=${PATH} <command> 
+
+By default, ``sudo`` does not respect any custom environments you have activated. The ``PATH=${PATH}``
+'fixes' that.
+
+``tljh-config`` symlink
+========================
+
+We create a symlink from ``/usr/local/bin/tljh-config`` to ``/opt/tljh/hub/bin/tljh-cohnfig``, so users
+can run ``sudo -E tljh-config <somethihng>`` from their terminal. While the user environment is added
+to users' ``$PATH`` when they launch through JupyterHub, the hub environment is not. This makes it
+hard to access the ``tljh-config`` command used to change most config parameters. Hence we symlink the
+``tljh-config`` command to ``/usr/local/bin``, so it is directly accessible with ``sudo -E tljh-config <command>``.
+
+Systemd Units
+=============
+
+TLJH places 3 systemd units on your computer. They all start on system startup.
+
+#. ``jupyterhub.service`` - starts the JupyterHub service.
+#. ``configurable-http-proxy.service`` - starts the nodejs based proxy that is used by JupyterHub.
+#. ``traefik.service`` - starts traefik proxy that manages HTTPS
+
+In addition, each running Jupyter user gets their own systemd unit of the name ``jupyter-<username>``.
+
+User groups
+===========
+
+TLJH creates two user groups when installed:
+
+#. ``jupyterhub-users`` contains all users managed by this JupyterHub
+#. ``jupyterhub-admins`` contains all users with admin rights managed by this JupyterHub.
+
+When a new JupyterHub user logs in, a unix user is created for them. The unix user is always added
+to the ``jupyterhub-users`` group. If the user is an admin, they are added to the ``jupyterhub-admins``
+group whenever they start / stop their notebook server.
+
+If you uninstall TLJH, you should probably remove all user accounts associated with both these
+user groups, and then remove the groups themselves. You might have to archive or delete the home
+directories of these users under ``/home/``.
+
+Passwordless ``sudo`` for JupyterHub admins
+============================================
+
+``/etc/sudoers.d/jupyterhub-admins`` is created to provide passwordless sudo for all JupyterHub
+admins. We also set it up to inherit ``$PATH`` with ``sudo -E``, to more easily call ``conda``,
+``pip``, etc.

docs/tutorials/custom.rst

@@ -32,11 +32,16 @@ Step 1: Installing The Littlest JupyterHub
 
    .. code-block:: bash
 
-    #!/bin/bash
+      #!/bin/bash
-    curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
+      curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
-     | sudo python3 - \
+        | sudo python3 - \
        --admin <admin-user-name>
 
+   .. 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.
+
 #. Press ``Enter`` to start the installation process. This will take 5-10 minutes,
    and will say 'Done!' when the installation process is complete.
 

docs/tutorials/digitalocean.rst

@@ -62,10 +62,15 @@ Let's create the server on which we can run JupyterHub.
 
    .. code-block:: bash
 
-    #!/bin/bash
+      #!/bin/bash
-    curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
+      curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
-     | sudo python3 - \
+        | sudo python3 - \
-       --admin <admin-user-name>
+          --admin <admin-user-name>
+
+   .. 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.
 
 #. Under the **Finalize and create** section, enter a ``hostname`` that descriptively
    identifies this server for you.

docs/tutorials/google.rst

@@ -143,14 +143,19 @@ Let's create the server on which we can run JupyterHub.
 
    .. code-block:: bash
 
-    #!/bin/bash
+       #!/bin/bash
-    curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
+       curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
-     | sudo python3 - \
+         | sudo python3 - \
-       --admin <admin-user-name>
+           --admin <admin-user-name>
 
    .. image:: ../images/providers/google/startup-script.png
       :alt: Install JupyterHub with the Startup script textbox
 
+   .. 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.
+
 #. Click the **Create** button at the bottom to start your server!
 
    .. image:: ../images/providers/google/create-vm-button.png

docs/tutorials/jetstream.rst

@@ -84,10 +84,15 @@ Let's create the server on which we can run JupyterHub.
 
    .. code-block:: bash
 
-    #!/bin/bash
+      #!/bin/bash
-    curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
+      curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
-     | sudo python3 - \
+        | sudo python3 - \
-       --admin <admin-user-name>
+          --admin <admin-user-name>
+
+   .. 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.
 
 #. Under **Execution Strategy Type**, select **Run script on first boot**.