From 5803e2ab3b63362645b0188399ae1b148526777b Mon Sep 17 00:00:00 2001 From: Jordan Bradford <36420801+jrdnbradford@users.noreply.github.com> Date: Mon, 22 May 2023 20:33:07 -0400 Subject: [PATCH] Re-add user env files --- docs/howto/index.md | 7 +- docs/howto/user-env/notebook-interfaces.md | 57 ++++++ docs/howto/user-env/server-resources.md | 8 + docs/howto/user-env/user-environment.md | 214 +++++++++++++++++++++ 4 files changed, 283 insertions(+), 3 deletions(-) create mode 100644 docs/howto/user-env/notebook-interfaces.md create mode 100644 docs/howto/user-env/server-resources.md create mode 100644 docs/howto/user-env/user-environment.md diff --git a/docs/howto/index.md b/docs/howto/index.md index 7a73b8c..05c2a84 100644 --- a/docs/howto/index.md +++ b/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 diff --git a/docs/howto/user-env/notebook-interfaces.md b/docs/howto/user-env/notebook-interfaces.md new file mode 100644 index 0000000..ef0645f --- /dev/null +++ b/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//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. diff --git a/docs/howto/user-env/server-resources.md b/docs/howto/user-env/server-resources.md new file mode 100644 index 0000000..f31b064 --- /dev/null +++ b/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). diff --git a/docs/howto/user-env/user-environment.md b/docs/howto/user-env/user-environment.md new file mode 100644 index 0000000..3347f3c --- /dev/null +++ b/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 `, 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 + ```