Add guide for customizing user environments

docs/guides/user-environment.rst

@@ -0,0 +1,154 @@
+.. _user_environment:
+
+Customizing user environment
+============================
+
+:abbr:`TLJH (The Littlest JupyterHub)` starts all users in the same `conda <https://conda.io/docs/>`_
+environment. Packages / libraries installed in this environment are available
+to all users on the JupyterHub. Users with :ref:`admin_access` can install packages
+easily.
+
+.. _user_environment_pip:
+
+Installing pip packages
+-----------------------
+
+`pip <https://pypi.org/project/pip/>`_ is the recomended tool for installing packages
+in Python from the `Python Packaging Index (PyPI) <https://pypi.org/>`_. PyPI has
+almost 145,000 packages in it right now, so a lot of what you need is going to be there!
+
+1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
+
+   .. image:: ../images/new_terminal_button.png
+      :alt: New Terminal button under New menu
+
+   If you already have a terminal open as an admin user, that should work too!
+
+2. Install a package!
+
+   .. code-block:: bash
+
+      sudo -E pip install numpy
+
+   This installs the ``numpy`` library from PyPI and makes it available
+   to all users.
+
+   .. note::
+
+      If you get an error message like ``sudo: pip: command not found``,
+      make sure you are not missing the ``-E`` parameter after ``sudo``.
+
+.. _user_environment_conda:
+
+Installing conda packages
+-------------------------
+
+Conda lets you install new languages (such as new versions of python, node, R, etc)
+as well as packages in those languages. For lots of scientific software, installing
+with conda is often simpler & easier than installing with pip - especially if it
+links to C / Fortran code.
+
+We recommend installing packages from `conda-forge <https://conda-forge.org/>`_,
+a community maintained repository of  conda packages.
+
+1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
+
+   .. image:: ../images/new_terminal_button.png
+      :alt: New Terminal button under New menu
+
+   If you already have a terminal open as an admin user, that should work too!
+
+2. Install a package!
+
+   .. code-block:: bash
+
+      sudo -E conda install -c conda-forge gdal
+
+   This installs the ``gdal`` library from ``conda-forge`` and makes it available
+   to all users. ``gdal`` is much harder to install with pip.
+
+   .. note::
+
+      If you get an error message like ``sudo: conda: command not found``,
+      make sure you are not missing the ``-E`` parameter after ``sudo``.
+
+.. _user_environment_apt:
+
+Installing apt packages
+-----------------------
+
+`apt <https://help.ubuntu.com/lts/serverguide/apt.html.en>`_ is the official package
+manager for the `Ubuntu Linux distribution <https://www.ubuntu.com/>`_. You can install
+utilities (such as ``vim``, ``sl``, ``htop``, etc), servers (``postgres``, ``mysql``, ``nginx``, etc)
+and a lot more languages than present in ``conda`` (``haskell``, ``prolog``, ``INTERCAL``).
+Some third party software (such as `RStudio <https://www.rstudio.com/products/rstudio/download/>`_)
+is distributed as ``.deb`` files, which are the files ``apt`` uses to install software.
+
+You can search for packages with `Ubuntu Package search <https://packages.ubuntu.com/>`_ -
+make sure to look in the version of Ubuntu you are using!
+
+1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
+
+   .. image:: ../images/new_terminal_button.png
+      :alt: New Terminal button under New menu
+
+   If you already have a terminal open as an admin user, that should work too!
+
+2. Update list of packages available. This makes sure you get the latest version of
+   the packages possible from the repositories.
+
+   .. code-block:: bash
+
+      sudo apt update
+
+3. Install the packages you want.
+
+   .. code-block:: bash
+
+      sudo apt install mysql-server git
+
+   This installs (and starts) a ``MySQL <https://www.mysql.com/>`` database server
+   and ``git``.
+
+
+User environment location
+-------------------------
+
+The user environment is a conda enviornment set up in ``/opt/tljh/user``, with
+a Python3 kernel as the default. It is readable by all users, but writeable only
+by users who have root access. This makes it possible for JupyterHub admins (who have
+root access with ``sudo``) to install software in the user environment easily.
+
+Accessing user environment outside JupyterHub
+---------------------------------------------
+
+We add ``/opt/tljh/user/bin`` to the ``$PATH`` environment variable for all JupyterHub
+users, so everything installed in the user environment is available to them automatically.
+If you are using ``ssh`` to access your server instead, you can get access to the same
+environment with:
+
+.. code-block:: bash
+
+   export PATH=/opt/tljh/user/bin:${PATH}
+
+Whenever you run any command now, the user environment will be searched first before
+your system environment is. So if you run ``python3 <somefile>``, it'll use the ``python3``
+installed in the user environment (``/opt/tljh/user/bin/python3``) rather than the ``python3``
+installed in your system environment (``/usr/bin/python3``). This is usually what you want!
+
+To make this change 'stick', you can add the line to the end of the ``.bashrc`` file in
+your home directory.
+
+When using ``sudo``, the ``PATH`` environment variable is usually reset, for security
+reasons. This leads to error messages like:
+
+.. code-block:: console
+
+   $ sudo conda install -c conda-forge gdal
+   sudo: conda: command not found
+
+The most common & portable way to fix this when using ``ssh`` is:
+
+.. code-block:: bash
+
+   sudo PATH=${PATH} conda install -c conda-forge gdal

docs/index.rst

@@ -41,6 +41,7 @@ Guides provide in-depth explanations of specific topics.
    guides/requirements
    guides/install
    guides/admin
+   guides/user-environment
 
 Troubleshooting
 ===============

docs/tutorials/quickstart.rst

@@ -98,7 +98,9 @@ let the changes take effect.
 
 Congratulations, you are now an admin user in JupyterHub! Most administrative
 actions can now be performed from inside the Terminal in Jupyter Notebooks,
-without requiring SSH usage. See :ref:`admin_access` for more information.
+without requiring SSH usage.
+
+See :ref:`admin_access` for more information.
 
 Step 3: Install conda / pip packages for all users
 --------------------------------------------------
@@ -109,11 +111,11 @@ available to all users. Admin users can install packages in this environment
 with ``sudo -E``.
 
 1. As an admin user, open a terminal in your notebook server
-2. Install ``numpy`` from `conda-forge <https://conda-forge.org/>`_.
+2. Install `gdal <https://anaconda.org/conda-forge/gdal>`_ from `conda-forge <https://conda-forge.org/>`_.
 
    .. code-block:: bash
 
-      sudo -E conda install -c conda-forge numpy
+      sudo -E conda install -c conda-forge gdal
 
    The ``sudo -E`` is very important!
 
@@ -121,8 +123,10 @@ with ``sudo -E``.
 
    .. code-block:: bash
 
-      sudo -E pip install there
+      sudo -E pip install numpy
 
-The packages ``numpy`` and ``there`` are now available to all users in JupyterHub.
+The packages ``gdal`` and ``numpy`` are now available to all users in JupyterHub.
 If a user already had a python notebook running, they have to restart their notebook's
 kernel to make the new libraries available.
+
+See :ref:`user_environment` for more information.