diff --git a/docs/index.rst b/docs/index.rst index a8c887d..5c54c13 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/topic/customizing-installer.rst b/docs/topic/customizing-installer.rst index 7a68fe8..30f1f99 100644 --- a/docs/topic/customizing-installer.rst +++ b/docs/topic/customizing-installer.rst @@ -1,3 +1,5 @@ +.. _topic/customizing-installer: + ========================= Customizing the Installer ========================= diff --git a/docs/topic/installer-actions.rst b/docs/topic/installer-actions.rst new file mode 100644 index 0000000..dc50260 --- /dev/null +++ b/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 `_. + +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 `_ +and a binary install of `traefik `_. 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} + +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 `` 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 ``. + +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-``. + +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. diff --git a/docs/tutorials/custom.rst b/docs/tutorials/custom.rst index 75ba1e4..e9405cb 100644 --- a/docs/tutorials/custom.rst +++ b/docs/tutorials/custom.rst @@ -32,11 +32,16 @@ Step 1: Installing The Littlest JupyterHub .. code-block:: bash - #!/bin/bash - curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ - | sudo python3 - \ + #!/bin/bash + curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ + | sudo python3 - \ --admin + .. 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. diff --git a/docs/tutorials/digitalocean.rst b/docs/tutorials/digitalocean.rst index 0cac0e8..d625727 100644 --- a/docs/tutorials/digitalocean.rst +++ b/docs/tutorials/digitalocean.rst @@ -62,10 +62,15 @@ Let's create the server on which we can run JupyterHub. .. code-block:: bash - #!/bin/bash - curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ - | sudo python3 - \ - --admin + #!/bin/bash + curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ + | sudo python3 - \ + --admin + + .. 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. diff --git a/docs/tutorials/google.rst b/docs/tutorials/google.rst index e9fe1b1..e5c3dce 100644 --- a/docs/tutorials/google.rst +++ b/docs/tutorials/google.rst @@ -143,14 +143,19 @@ Let's create the server on which we can run JupyterHub. .. code-block:: bash - #!/bin/bash - curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ - | sudo python3 - \ - --admin + #!/bin/bash + curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ + | sudo python3 - \ + --admin .. 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 diff --git a/docs/tutorials/jetstream.rst b/docs/tutorials/jetstream.rst index 6d320eb..f695c4e 100644 --- a/docs/tutorials/jetstream.rst +++ b/docs/tutorials/jetstream.rst @@ -84,10 +84,15 @@ Let's create the server on which we can run JupyterHub. .. code-block:: bash - #!/bin/bash - curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ - | sudo python3 - \ - --admin + #!/bin/bash + curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ + | sudo python3 - \ + --admin + + .. 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**.