Re-add user env files

docs/howto/index.md

@@ -19,9 +19,9 @@ content/share-data
 :caption: The user environment
 :titlesonly: true
 
-env/user-environment
-env/notebook-interfaces
-env/server-resources
+user-env/user-environment
+user-env/notebook-interfaces
+user-env/server-resources
 ```
 
 ## Authentication
@@ -31,6 +31,7 @@ with your JupyterHub. For more information on Authentication, see
 [](/topic/authenticator-configuration)
 
 ```{toctree}
+:caption: Authentication
 :titlesonly: true
 
 auth/dummy

docs/howto/user-env/notebook-interfaces.md

@@ -0,0 +1,57 @@
+(howto/user-env/notebook-interfaces)=
+
+# Change default User Interface
+
+By default, logging into TLJH puts you in the classic Jupyter Notebook
+interface we all know and love. However, there are at least two other
+popular notebook interfaces you can use:
+
+1.  [JupyterLab](http://jupyterlab.readthedocs.io/en/stable/)
+2.  [nteract](https://nteract.io/)
+
+Both these interfaces are also shipped with TLJH by default. You can try
+them temporarily, or set them to be the default interface whenever you
+login.
+
+## Trying an alternate interface temporarily
+
+When you log in & start your server, by default the URL in your browser
+will be something like `/user/<username>/tree`. The `/tree` is what
+tells the notebook server to give you the classic notebook interface.
+
+-   **For the JupyterLab interface**: change `/tree` to `/lab`.
+-   **For the nteract interface**: change `/tree` to `/nteract`
+
+You can play around with them and see what fits your use cases best.
+
+## Changing the default user interface
+
+You can change the default interface users get when they log in by
+modifying `config.yaml` as an admin user.
+
+1.  To launch **JupyterLab** when users log in, run the following in an
+    admin console:
+
+    ```bash
+    sudo tljh-config set user_environment.default_app jupyterlab
+    ```
+
+2.  Alternatively, to launch **nteract** when users log in, run the
+    following in the admin console:
+
+    ```bash
+    sudo tljh-config set user_environment.default_app nteract
+    ```
+
+3.  Apply the changes by restarting JupyterHub. This should not disrupt
+    current users.
+
+    ```bash
+    sudo tljh-config reload hub
+    ```
+
+    If this causes problems, check the [logs](#troubleshoot-logs-jupyterhub) for
+    clues on what went wrong.
+
+Users might have to restart their servers from control panel to get the
+new interface.

docs/howto/user-env/server-resources.md

@@ -0,0 +1,8 @@
+(howto/user-env/server-resources)=
+
+# Configure resources available to users
+
+To configure the resources that are available to your users (such as
+RAM, CPU and Disk Space), see the section [](#tljh-set-user-limits). 
+For information on **resizing** the environment available to users *after* you\'ve created
+your JupyterHub, see [](#howto-admin-resize).

docs/howto/user-env/user-environment.md

@@ -0,0 +1,214 @@
+(howto/user-env/user-environment)=
+
+# Install conda, pip or apt packages
+
+`TLJH (The Littlest JupyterHub)`{.interpreted-text role="abbr"} 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 [admin rights](#howto-admin-admin-users)
+can install packages easily.
+
+(howto/user-env/user-environment-pip)=
+
+## Installing pip packages 
+
+[pip](https://pypi.org/project/pip/) is the recommended 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.
+
+    ![New Terminal button under New menu](../../images/notebook/new-terminal-button.png)
+
+    If you already have a terminal open as an admin user, that should
+    work too!
+
+2.  Install a package!
+
+    ```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`.
+    :::
+
+(howto/user-env/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.
+
+    ![New Terminal button under New menu](../../images/notebook/new-terminal-button.png)
+
+    If you already have a terminal open as an admin user, that should
+    work too!
+
+2.  Install a package!
+
+    ```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`.
+    :::
+
+(howto/user-env/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.
+
+    ![New Terminal button under New menu](../../images/notebook/new-terminal-button.png)
+
+    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.
+
+    ```bash
+    sudo apt update
+    ```
+
+3.  Install the packages you want.
+
+    ```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 environment 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:
+
+```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:
+
+```bash
+sudo conda install -c conda-forge gdal
+sudo: conda: command not found
+```
+
+The most common & portable way to fix this when using `ssh` is:
+
+```bash
+sudo PATH=${PATH} conda install -c conda-forge gdal
+```
+
+## Upgrade to a newer Python version
+
+All new TLJH installs use miniconda 4.7.10, which comes with a Python
+3.7 environment for the users. The previously TLJH installs came with
+miniconda 4.5.4, which meant a Python 3.6 environment.
+
+To upgrade the Python version of the user environment, one can:
+
+-   **Start fresh on a machine that doesn\'t have TLJH already
+    installed.**
+
+    See the [](#install-installing) section about how to install TLJH.
+
+-   **Upgrade Python manually.**
+
+    Because upgrading Python for existing installs can break packages
+    already installed under the old Python, upgrading your current TLJH
+    installation, will NOT upgrade the Python version of the user
+    environment, but you may do so manually.
+
+    **Steps:**
+
+    1.  Activate the user environment, if using ssh. If the terminal was
+        started with JupyterHub, this step can be skipped:
+
+        ```bash
+        source /opt/tljh/user/bin/activate
+        ```
+
+    2.  Get the list of currently installed pip packages (so you can
+        later install them under the new Python):
+
+        ```bash
+        pip freeze > pip_pkgs.txt
+        ```
+
+    3.  Update all conda installed packages in the environment:
+
+        ```bash
+        sudo PATH=${PATH} conda update --all
+        ```
+
+    4.  Update Python version:
+
+        ```bash
+        sudo PATH=${PATH} conda install python=3.7
+        ```
+
+    5.  Install the pip packages previously saved:
+
+        ```bash
+        pip install -r pip_pkgs.txt
+        ```