Merge pull request #902 from jrdnbradford/add-user-env

Add user env doc files

docs/conf.py

@@ -107,4 +107,7 @@ ogp_use_first_image = True
 rediraffe_branch = "main"
 rediraffe_redirects = {
     # "old-file": "new-folder/new-file-name",
+    "howto/env/user-environment": "howto/user-env/user-environment",
+    "howto/env/notebook-interfaces": "howto/user-env/notebook-interfaces",
+    "howto/env/server-resources": "howto/user-env/server-resources",
 }

docs/howto/admin/admin-users.md

@@ -17,7 +17,7 @@ so attackers can not easily gain control of the system.
 :::{important}
 You should make sure an admin user is present when you **install** TLJH
 the very first time. It is recommended that you also set a password
-for the admin at this step. The [`--admin`] (/topic/customizing-installer/admin)
+for the admin at this step. The [`--admin`](#howto-admin-admin-users)
 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.
 :::

docs/howto/admin/resource-estimation.md

@@ -72,6 +72,7 @@ $$
 
 ## Resizing your server
 
-Lots of cloud providers let your dynamically resize your server if you need it
+Many cloud providers let your dynamically resize your server if you need it
 to be larger or smaller. Usually this requires a restart of the whole server -
 active users will be logged out, but otherwise usually nothing bad happens.
+See [](#howto-admin-resize) for provider-specific instructions on resizing.

docs/howto/index.md

@@ -19,9 +19,9 @@ content/share-data
 :caption: The user environment
 :titlesonly: true
 
-env/user-environment
+user-env/user-environment
-env/notebook-interfaces
+user-env/notebook-interfaces
-env/server-resources
+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
+      ```

docs/install/add-packages.md

@@ -27,4 +27,4 @@ The packages `gdal` and `there` 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}`howto-env-user-environment` for more information.
+See [](#howto/user-env/user-environment) for more information.

docs/install/amazon.md

@@ -268,12 +268,12 @@ Let's create the server on which we can run JupyterHub.
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```

docs/install/azure.md

@@ -215,12 +215,12 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```

docs/install/custom-server.md

@@ -79,13 +79,13 @@ for custom server installations.
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```
 

docs/install/digitalocean.md

@@ -112,12 +112,12 @@ Let's create the server on which we can run JupyterHub.
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```

docs/install/google.md

@@ -208,12 +208,12 @@ Let's create the server on which we can run JupyterHub.
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```

docs/install/jetstream.md

@@ -141,12 +141,12 @@ Let's create the server on which we can run JupyterHub.
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```

docs/install/ovh.md

@@ -122,12 +122,12 @@ Let's create the server on which we can run JupyterHub.
 
 ## Step 2: Adding more users
 
-```{include} add_users.txt
+```{include} add-users.md
 
 ```
 
 ## Step 3: Install conda / pip packages for all users
 
-```{include} add_packages.txt
+```{include} add-packages.md
 
 ```