diff --git a/docs/conf.py b/docs/conf.py index 0c40f58..677ed3b 100644 --- a/docs/conf.py +++ b/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", } diff --git a/docs/howto/admin/admin-users.md b/docs/howto/admin/admin-users.md index 1102853..95bd5e6 100644 --- a/docs/howto/admin/admin-users.md +++ b/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. ::: diff --git a/docs/howto/admin/resource-estimation.md b/docs/howto/admin/resource-estimation.md index 9bc7113..6e7f263 100644 --- a/docs/howto/admin/resource-estimation.md +++ b/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. 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..d83a05b --- /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..906d49c --- /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..74b7285 --- /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 + ``` diff --git a/docs/install/add_packages.txt b/docs/install/add-packages.md similarity index 93% rename from docs/install/add_packages.txt rename to docs/install/add-packages.md index 10f8972..826f65b 100644 --- a/docs/install/add_packages.txt +++ b/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. diff --git a/docs/install/add_users.txt b/docs/install/add-users.md similarity index 100% rename from docs/install/add_users.txt rename to docs/install/add-users.md diff --git a/docs/install/amazon.md b/docs/install/amazon.md index 227af91..dd042be 100644 --- a/docs/install/amazon.md +++ b/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 ``` diff --git a/docs/install/azure.md b/docs/install/azure.md index 90f9c98..a9f862f 100644 --- a/docs/install/azure.md +++ b/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 ``` diff --git a/docs/install/custom-server.md b/docs/install/custom-server.md index 85760a9..8ef92d8 100644 --- a/docs/install/custom-server.md +++ b/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 ``` diff --git a/docs/install/digitalocean.md b/docs/install/digitalocean.md index b6c3411..2f367c6 100644 --- a/docs/install/digitalocean.md +++ b/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 ``` diff --git a/docs/install/google.md b/docs/install/google.md index 8fd73d6..e6d125e 100644 --- a/docs/install/google.md +++ b/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 ``` diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 7205cf8..b068ca1 100644 --- a/docs/install/jetstream.md +++ b/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 ``` diff --git a/docs/install/ovh.md b/docs/install/ovh.md index 2a562f6..eec287e 100644 --- a/docs/install/ovh.md +++ b/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 ```