zhangyiss/the-littlest-jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/the-littlest-jupyterhub.git synced 2025-12-18 21:54:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #863 from minrk/myst

Browse Source 
docs: transition from rst to myst markdown using rst2myst
This commit is contained in:
Erik Sundell
2023-04-04 21:35:43 +02:00
committed by GitHub
parent 25e4290f79 ee0a2c9b66
commit fa4a8bf6cb
98 changed files with 4199 additions and 4566 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
CONTRIBUTING.rst
View File

@@ -1,8 +0,0 @@
Contributing to The Littlest JupyterHub development
---------------------------------------------------
This is an open source project that is developed and maintained by volunteers.
Your contribution is integral to the future of the project. Thank you!
See the `contributing guide <https://the-littlest-jupyterhub.readthedocs.io/en/latest/contributing/index.html>`_
for information on the different ways of contributing to The Littlest JupyterHub.

4
docs/PULL_REQUEST_TEMPLATE.md
View File

@@ -1,4 +0,0 @@
- [ ] Add / update documentation
- [ ] Add tests
<!-- Read more about our code-review guidelines at https://the-littlest-jupyterhub.readthedocs.io/en/latest/contributing/code-review.html -->

16
docs/conf.py
View File

@@ -23,9 +23,10 @@ extensions = [
"sphinx_copybutton",
"sphinxext.opengraph",
"sphinxext.rediraffe",
"myst_parser",
]
root_doc = "index"
source_suffix = [".rst"]
source_suffix = [".md"]
# -- Options for HTML output -------------------------------------------------
@@ -59,6 +60,19 @@ html_context = {
"doc_path": "docs",
}
# -- MyST configuration ------------------------------------------------------
# ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
#
myst_heading_anchors = 2
myst_enable_extensions = [
# available extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
"attrs_inline",
"colon_fence",
"deflist",
"dollarmath",
"fieldlist",
]
# -- Options for linkcheck builder -------------------------------------------
# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder

29
docs/contributing/code-review.rst → docs/contributing/code-review.md
View File

@@ -1,37 +1,32 @@
.. _contributing/code-review:
(contributing-code-review)=
======================
Code Review guidelines
======================
# Code Review guidelines
This document outlines general guidelines to follow when you are making
or reviewing a Pull Request.
Have empathy
============
## Have empathy
We recommend reading `On Empathy & Pull Requests <https://slack.engineering/on-empathy-pull-requests-979e4257d158>`_
and `How about code reviews <https://slack.engineering/how-about-code-reviews-2695fb10d034>`_
We recommend reading [On Empathy & Pull Requests](https://slack.engineering/on-empathy-pull-requests-979e4257d158)
and [How about code reviews](https://slack.engineering/how-about-code-reviews-2695fb10d034)
to learn more about being empathetic in code reviews.
Write documentation
===================
## Write documentation
If your pull request touches any code, you must write or update documentation
for it. For this project, documentation is a lot more important than the code.
If a feature is not documented, it does not exist. If a behavior is not documented,
it is a bug.
If a feature is not documented, it does not exist. If a behavior is not documented,
it is a bug.
Do not worry about having perfect documentation! Documentation improves over
time. The requirement is to have documentation before merging a pull request,
not to have *perfect* documentation before merging a pull request. If you
not to have _perfect_ documentation before merging a pull request. If you
are new and not sure how to add documentation, other contributors will
be happy to guide you.
See :ref:`contributing/docs` for guidelines on writing documentation.
See [](/contributing/docs) for guidelines on writing documentation.
Write tests
===========
## Write tests
If your pull request touches any code, you must write unit or integration tests
to exercise it. This helps validate & communicate that your pull request works
@@ -48,4 +43,4 @@ add more tests.
If you are unsure what kind of tests to add for your pull request, other
contributors to the repo will be happy to help guide you!
See :ref:`contributing/tests` for guidelines on writing tests.
See [](/contributing/tests) for guidelines on writing tests.

72
docs/contributing/dev-setup.md Normal file
View File

@@ -0,0 +1,72 @@
(contributing-dev-setup)=
# Setting up Development Environment
The easiest & safest way to develop & test TLJH is with [Docker](https://www.docker.com/).
1. Install Docker Community Edition by following the instructions on
[their website](https://www.docker.com/community-edition).
2. Clone the [git repo](https://github.com/jupyterhub/the-littlest-jupyterhub) (or your fork of it).
3. Build a docker image that has a functional systemd in it.
```bash
docker build -t tljh-systemd . -f integration-tests/Dockerfile
```
4. Run a docker container with the image in the background, while bind mounting
your TLJH repository under `/srv/src`.
```bash
docker run \
--privileged \
--detach \
--name=tljh-dev \
--publish 12000:80 \
--mount type=bind,source=$(pwd),target=/srv/src \
tljh-systemd
```
5. Get a shell inside the running docker container.
```bash
docker exec -it tljh-dev /bin/bash
```
6. Run the bootstrapper from inside the container (see step above):
The container image is already set up to default to a `dev` install, so
it'll install from your local repo rather than from github.
```console
python3 /srv/src/bootstrap/bootstrap.py --admin admin
```
> Or, if you would like to setup the admin's password during install,
> you can use this command (replace "admin" with the desired admin username
> and "password" with the desired admin password):
>
> > ```console
> > python3 /srv/src/bootstrap/bootstrap.py --admin admin:password
> > ```
> >
> > The primary hub environment will also be in your PATH already for convenience.
1. You should be able to access the JupyterHub from your browser now at
[http://localhost:12000](http://localhost:12000). Congratulations, you are
set up to develop TLJH!
2. Make some changes to the repository. You can test easily depending on what
you changed.
- If you changed the `bootstrap/bootstrap.py` script or any of its dependencies,
you can test it by running `python3 /srv/src/bootstrap/bootstrap.py`.
- If you changed the `tljh/installer.py` code (or any of its dependencies),
you can test it by running `python3 -m tljh.installer`.
- If you changed `tljh/jupyterhub_config.py`, `tljh/configurer.py`,
`/opt/tljh/config/` or any of their dependencies, you only need to
restart jupyterhub for them to take effect. `tljh-config reload hub`
should do that.
[](/troubleshooting/logs) has information on looking at various logs in the container
to debug issues you might have.

75
docs/contributing/dev-setup.rst
View File

@@ -1,75 +0,0 @@
.. _contributing/dev-setup:
==================================
Setting up Development Environment
==================================
The easiest & safest way to develop & test TLJH is with `Docker <https://www.docker.com/>`_.
#. Install Docker Community Edition by following the instructions on
`their website <https://www.docker.com/community-edition>`_.
#. Clone the `git repo <https://github.com/jupyterhub/the-littlest-jupyterhub>`_ (or your fork of it).
#. Build a docker image that has a functional systemd in it.
.. code-block:: bash
docker build -t tljh-systemd . -f integration-tests/Dockerfile
#. Run a docker container with the image in the background, while bind mounting
your TLJH repository under ``/srv/src``.
.. code-block:: bash
docker run \
--privileged \
--detach \
--name=tljh-dev \
--publish 12000:80 \
--mount type=bind,source=$(pwd),target=/srv/src \
tljh-systemd
#. Get a shell inside the running docker container.
.. code-block:: bash
docker exec -it tljh-dev /bin/bash
#. Run the bootstrapper from inside the container (see step above):
The container image is already set up to default to a ``dev`` install, so
it'll install from your local repo rather than from github.
.. code-block:: console
python3 /srv/src/bootstrap/bootstrap.py --admin admin
Or, if you would like to setup the admin's password during install,
you can use this command (replace "admin" with the desired admin username
and "password" with the desired admin password):
.. code-block:: console
python3 /srv/src/bootstrap/bootstrap.py --admin admin:password
The primary hub environment will also be in your PATH already for convenience.
#. You should be able to access the JupyterHub from your browser now at
`http://localhost:12000 <http://localhost:12000>`_. Congratulations, you are
set up to develop TLJH!
#. Make some changes to the repository. You can test easily depending on what
you changed.
* If you changed the ``bootstrap/bootstrap.py`` script or any of its dependencies,
you can test it by running ``python3 /srv/src/bootstrap/bootstrap.py``.
* If you changed the ``tljh/installer.py`` code (or any of its dependencies),
you can test it by running ``python3 -m tljh.installer``.
* If you changed ``tljh/jupyterhub_config.py``, ``tljh/configurer.py``,
``/opt/tljh/config/`` or any of their dependencies, you only need to
restart jupyterhub for them to take effect. ``tljh-config reload hub``
should do that.
:ref:`troubleshooting/logs` has information on looking at various logs in the container
to debug issues you might have.

178
docs/contributing/docs.rst → docs/contributing/docs.md
View File

@@ -1,13 +1,11 @@
.. _contributing/docs:
(contributing-docs)=
=====================
Writing documentation
=====================
# Writing documentation
.. note::
Heavily inspired by the
`django project's guidelines <https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/>`_
:::{note}
Heavily inspired by the
[django project's guidelines](https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/)
:::
We place a high importance on consistency, readability and completeness of documentation.
If a feature is not documented, it does not exist. If a behavior is not documented,
@@ -17,70 +15,62 @@ possible.
Documentation changes generally come in two forms:
* General improvements: typo corrections, error fixes and better
- General improvements: typo corrections, error fixes and better
explanations through clearer writing and more examples.
* New features: documentation of features that have been added to the
- New features: documentation of features that have been added to the
framework since the last release.
This section explains how writers can craft their documentation changes
in the most useful and least error-prone ways.
Getting the raw documentation
=============================
## Getting the raw documentation
Though TLJH's documentation is intended to be read as HTML at
https://the-littlest-jupyterhub.readthedocs.io/, we edit it as a collection of text files for
maximum flexibility. These files live in the top-level ``docs/`` directory of
<https://the-littlest-jupyterhub.readthedocs.io/>, we edit it as a collection of text files for
maximum flexibility. These files live in the top-level `docs/` directory of
TLJH's repository.
If you'd like to start contributing to our docs, get the development version of
TLJH from the source code repository. The development version has the
latest-and-greatest documentation, just as it has latest-and-greatest code.
Getting started with Sphinx
===========================
## Getting started with Sphinx
TLJH's documentation uses the Sphinx__ documentation system, which in turn
is based on docutils__. The basic idea is that lightly-formatted plain-text
TLJH's documentation uses the [Sphinx](http://sphinx-doc.org/) documentation system, which in turn
is based on [docutils](http://docutils.sourceforge.net/). The basic idea is that lightly-formatted plain-text
documentation is transformed into HTML, PDF, and any other output format.
__ http://sphinx-doc.org/
__ http://docutils.sourceforge.net/
To build the documentation locally, install the Sphinx dependencies:
.. code-block:: console
```console
$ cd docs/
$ pip install -r requirements.txt
```
$ cd docs/
$ pip install -r requirements.txt
Then from the `docs` directory, build the HTML:
Then from the ``docs`` directory, build the HTML:
.. code-block:: console
$ make html
```console
$ make html
```
If you encounter this error, it's likely that you are running inside a virtual environment.
.. code-block:: console
```console
Error in "currentmodule" directive:
```
Error in "currentmodule" directive:
To get started contributing, you'll want to read the :ref:`reStructuredText
reference <sphinx:rst-index>`
To get started contributing, you'll want to get familiar with [markdown](https://commonmark.org/help/) and [MyST](https://myst-parser.readthedocs.io).
Your locally-built documentation will be themed differently than the
documentation at `the-littlest-jupyterhub.readthedocs.io <https://the-littlest-jupyterhub.readthedocs.io>`_.
documentation at [the-littlest-jupyterhub.readthedocs.io](https://the-littlest-jupyterhub.readthedocs.io).
This is OK! If your changes look good on your local machine, they'll look good
on the website.
How the documentation is organized
==================================
## How the documentation is organized
The documentation is organized into several categories:
* **Tutorials** take the reader by the hand through a series
- **Tutorials** take the reader by the hand through a series
of steps to create something.
The important thing in a tutorial is to help the reader achieve something
@@ -97,7 +87,7 @@ The documentation is organized into several categories:
systems. These should cross-link a lot to other parts of the documentation,
avoid forcing the user to learn to SSH if possible & have lots of screenshots.
* **Topic guides** aim to explain a concept or subject at a
- **Topic guides** aim to explain a concept or subject at a
fairly high level.
Link to reference material rather than repeat it. Use examples and don't be
@@ -107,7 +97,7 @@ The documentation is organized into several categories:
Providing background context helps a newcomer connect the topic to things
that they already know.
* **Reference guides** contain technical reference for APIs.
- **Reference guides** contain technical reference for APIs.
They describe the functioning of TLJH's internal machinery and instruct in
its use.
@@ -119,7 +109,7 @@ The documentation is organized into several categories:
yourself explaining basic concepts, you may want to move that material to a
topic guide.
* **How-to guides** are recipes that take the reader through
- **How-to guides** are recipes that take the reader through
steps in key subjects.
What matters most in a how-to guide is what a user wants to achieve.
@@ -131,83 +121,56 @@ The documentation is organized into several categories:
hesitate to refer the reader back to the appropriate tutorial rather than
repeat the same material.
* **Troubleshooting guides** help reader answer the question "Why is my JupyterHub
- **Troubleshooting guides** help reader answer the question "Why is my JupyterHub
not working?".
These guides help readers try find causes for their symptoms, and hopefully fix
the issues. Some of these need to be specific to cloud providers, and that is
acceptable.
Writing style
=============
## Writing style
Typically, documentation is written in second person, referring to the reader as “you”.
Typically, documentation is written in second person, referring to the reader as “you”.
When using pronouns in reference to a hypothetical person, such as "a user with
a running notebook", gender neutral pronouns (they/their/them) should be used.
Instead of:
* he or she... use they.
* him or her... use them.
* his or her... use their.
* his or hers... use theirs.
* himself or herself... use themselves.
- he or she... use they.
- him or her... use them.
- his or her... use their.
- his or hers... use theirs.
- himself or herself... use themselves.
Commonly used terms
===================
## Commonly used terms
Here are some style guidelines on commonly used terms throughout the
documentation:
* **TLJH** -- common abbreviation of The Littlest JupyterHub. Fully
- **TLJH** -- common abbreviation of The Littlest JupyterHub. Fully
capitalized except when used in code / the commandline.
* **Python** -- when referring to the language, capitalize Python.
* **Notebook Interface** -- generic term for referring to JupyterLab,
- **Python** -- when referring to the language, capitalize Python.
- **Notebook Interface** -- generic term for referring to JupyterLab,
nteract, classic notebook & other user interfaces for accessing
## Guidelines for markdown files
Guidelines for reStructuredText files
=====================================
These guidelines regulate the format of our reST (reStructuredText)
These guidelines regulate the format of our markdown
documentation:
* In section titles, capitalize only initial words and proper nouns.
- In section titles, capitalize only initial words and proper nouns.
* Wrap the documentation at 120 characters wide, unless a code example
- Wrap the documentation at sentence breaks or around 120 characters wide, unless a code example
is significantly less readable when split over two lines, or for another
good reason.
* Use these heading styles::
===
One
===
Two
===
Three
-----
Four
~~~~
Five
^^^^
Documenting new features
========================
## Documenting new features
Our policy for new features is:
All new features must have appropriate documentation before they
can be merged.
> All new features must have appropriate documentation before they
> can be merged.
Choosing image size
===================
## Choosing image size
When adding images to the documentation, try to keep them as small as possible.
Larger images make the site load more slowly on browsers, and may make the site
@@ -217,37 +180,34 @@ If you're adding screenshots, make the size of your shot as small as possible.
If you're uploading large images, consider using an image optimizer in order
to reduce its size.
For example, for PNG files, use OptiPNG and AdvanceCOMP's ``advpng``:
For example, for PNG files, use OptiPNG and AdvanceCOMP's `advpng`:
.. code-block:: console
$ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
```console
$ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
```
This is based on OptiPNG version 0.7.5. Older versions may complain about the
``--strip all`` option being lossy.
`--strip all` option being lossy.
Spelling check
==============
## Spelling check
Before you commit your docs, it's a good idea to run the spelling checker.
You'll need to install a couple packages first:
* `pyenchant <https://pypi.org/project/pyenchant/>`_ (which requires
`enchant <https://www.abisource.com/projects/enchant/>`_)
- [pyenchant](https://pypi.org/project/pyenchant/) (which requires
[enchant](https://www.abisource.com/projects/enchant/))
- [sphinxcontrib-spelling](https://pypi.org/project/sphinxcontrib-spelling/)
* `sphinxcontrib-spelling
<https://pypi.org/project/sphinxcontrib-spelling/>`_
Then from the ``docs`` directory, run ``make spelling``. Wrong words (if any)
Then from the `docs` directory, run `make spelling`. Wrong words (if any)
along with the file and line number where they occur will be saved to
``_build/spelling/output.txt``.
`_build/spelling/output.txt`.
If you encounter false-positives (error output that actually is correct), do
one of the following:
* Surround inline code or brand/technology names with grave accents (`).
* Find synonyms that the spell checker recognizes.
* If, and only if, you are sure the word you are using is correct - add it
to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
- Surround inline code or brand/technology names with grave accents (\`).
- Find synonyms that the spell checker recognizes.
- If, and only if, you are sure the word you are using is correct - add it
to `docs/spelling_wordlist` (please keep the list in alphabetical order).

23
docs/contributing/index.rst → docs/contributing/index.md
View File

@@ -1,6 +1,4 @@
============
Contributing
============
# Contributing
✨ Thank you for thinking about contributing to the littlest JupyterHub! ✨
@@ -9,14 +7,15 @@ Your contribution is integral to the future of the project. Thank you!
This section contains documentation for people who want to contribute.
You can find the `source code on GitHub <https://github.com/jupyterhub/the-littlest-jupyterhub/tree/HEAD/tljh>`_
You can find the [source code on GitHub](https://github.com/jupyterhub/the-littlest-jupyterhub/tree/HEAD/tljh)
.. toctree::
:titlesonly:
```{toctree}
:titlesonly: true
docs
dev-setup
tests
plugins
code-review
packages
docs
dev-setup
tests
plugins
code-review
packages
```

30
docs/contributing/packages.rst → docs/contributing/packages.md
View File

@@ -1,46 +1,40 @@
.. _contributing/packages:
(contributing-packages)=
=======================
Environments & Packages
=======================
# Environments & Packages
TLJH installs packages from different sources during installation.
This document describes the various sources and how to upgrade
versions of packages installed.
Python Environments
===================
## Python Environments
TLJH sets up two python environments during installation.
1. **Hub Environment**. JupyterHub, authenticators, spawners, TLJH plugins
and the TLJH configuration management code is installed into this
environment. A `venv <https://docs.python.org/3/library/venv.html>`_ is used,
environment. A [venv](https://docs.python.org/3/library/venv.html) is used,
primarily since conda does not support ARM CPUs and we'd like to support the
RaspberryPI someday. Admins generally do not install custom packages
in this environment.
2. **User Environment**. Jupyter Notebook, JupyterLab, nteract, kernels,
and packages the users wanna use (such as numpy, scipy, etc) are installed
here. A `conda <https://conda.io>`_ environment is used here, since
a lot of scientific packages are available from Conda. ``pip`` is still
here. A [conda](https://conda.io) environment is used here, since
a lot of scientific packages are available from Conda. `pip` is still
used to install Jupyter specific packages, primarily because most notebook
extensions are still available only on `PyPI <https://pypi.org>`_.
extensions are still available only on [PyPI](https://pypi.org).
Admins can install packages here for use by all users.
Python package versions
=======================
## Python package versions
In ``installer.py``, most Python packages have a version specified. This
In `installer.py`, most Python packages have a version specified. This
can be upgraded freely whenever needed. Some of them have version checks
in ``integration-tests/test_extensions.py``, so those might need
in `integration-tests/test_extensions.py`, so those might need
updating too.
Apt packages
============
## Apt packages
Base operating system packages, including Python itself, are installed
via ``apt`` from the base Ubuntu repositories.
via `apt` from the base Ubuntu repositories.
We generally do not pin versions of packages provided by apt, instead
just using the latest versions provided by Ubuntu.

132
docs/contributing/plugins.md Normal file
View File

@@ -0,0 +1,132 @@
(contributing-plugins)=
# TLJH Plugins
TLJH plugins are the official way to make customized 'spins' or 'stacks'
with TLJH as the base. For example, the earth sciences community can make
a plugin that installs commonly used packages, set up authentication
and pre-download useful datasets. The mybinder.org community can
make a plugin that gives you a single-node, single-repository mybinder.org.
Plugins are very powerful, so the possibilities are endless.
## Design
[pluggy](https://github.com/pytest-dev/pluggy) is used to implement
plugin functionality. TLJH exposes specific **hooks** that your plugin
can provide implementations for. This allows us to have specific hook
points in the application that can be explicitly extended by plugins,
balancing the need to change TLJH internals in the future with the
stability required for a good plugin ecosystem.
## Installing Plugins
Include `--plugin <install_name>` in the Installer script. See [](/topic/customizing-installer) for more info.
## Writing a simple plugins
We shall try to write a simple plugin that installs a few libraries,
and use it to explain how the plugin mechanism works. We shall call
this plugin `tljh-simple`.
### Plugin directory layout
We recommend creating a new git repo for your plugin. Plugins are
normal python packages - however, since they are usually simpler,
we recommend they live in one file.
For `tljh-simple`, the repository's structure should look like:
```none
tljh_simple:
- tljh_simple.py
- setup.py
- README.md
- LICENSE
```
The `README.md` (or `README.rst` file) contains human readable
information about what your plugin does for your users. `LICENSE`
specifies the license used by your plugin - we recommend the
3-Clause BSD License, since that is what is used by TLJH itself.
### `setup.py` - metadata & registration
`setup.py` marks this as a python package, and contains metadata
about the package itself. It should look something like:
```python
from setuptools import setup
setup(
name="tljh-simple",
author="YuviPanda",
version="0.1",
license="3-clause BSD",
url='https://github.com/yuvipanda/tljh-simple',
entry_points={"tljh": ["simple = tljh_simple"]},
py_modules=["tljh_simple"],
)
```
This is a mostly standard `setup.py` file. `entry_points={"tljh": ["simple = tljh_simple]}`
'registers' the module `tljh_simple` (in file `tljh_simple.py`) with TLJH as a plugin.
### `tljh_simple.py` - implementation
In `tljh_simple.py`, you provide implementations for whichever hooks
you want to extend.
A hook implementation is a function that has the following characteristics:
1. Has same name as the hook
2. Accepts some or all of the parameters defined for the hook
3. Is decorated with the `hookimpl` decorator function, imported from
`tljh.hooks`.
The current list of available hooks and when they are called can be
seen in [tljh/hooks.py](https://github.com/jupyterhub/the-littlest-jupyterhub/blob/main/tljh/hooks.py)
in the source repository. Example implementations of each hook can be referenced from
[integration-tests/plugins/simplest/tljh_simplest.py](https://github.com/jupyterhub/the-littlest-jupyterhub/blob/main/integration-tests/plugins/simplest/tljh_simplest.py).
This example provides an implementation for the `tljh_extra_user_conda_packages`
hook, which can return a list of conda packages that'll be installed in users'
environment from conda-forge.
```python
from tljh.hooks import hookimpl
@hookimpl
def tljh_extra_user_conda_packages():
return [
'xarray',
'iris',
'dask',
]
```
## Publishing plugins
Plugins are python packages and should be published on PyPI. Users
can also install them directly from GitHub - although this is
not good long term practice.
The python package should be named `tljh-<pluginname>`.
## List of known plugins
If you are looking for a way to extend or customize your TLJH deployment, you might want to look for existing plugins.
Here is a non-exhaustive list of known TLJH plugins:
- [tljh-pangeo](https://github.com/yuvipanda/tljh-pangeo): TLJH plugin for setting up the Pangeo Stack.
- [tljh-voila-gallery](https://github.com/voila-dashboards/tljh-voila-gallery): TLJH plugin that installs a gallery of Voilà dashboards.
- [tljh-repo2docker](https://github.com/plasmabio/tljh-repo2docker): TLJH plugin to build multiple user environments with
[repo2docker](https://repo2docker.readthedocs.io).
- [tljh-shared-directory](https://github.com/kafonek/tljh-shared-directory): TLJH plugin which sets up a _shared directory_
for the Hub users in `/srv/scratch`.
- [tljh-db](https://github.com/sinzlab/tljh-db): TLJH plugin for working with mysql databases.
If you have authored a plugin, please open a PR to add it to this list!
We also recommend adding the `tljh-plugin` topic to the GitHub repository to make it more discoverable:
[https://github.com/topics/tljh-plugin](https://github.com/topics/tljh-plugin)

147
docs/contributing/plugins.rst
View File

@@ -1,147 +0,0 @@
.. _contributing/plugins:
============
TLJH Plugins
============
TLJH plugins are the official way to make customized 'spins' or 'stacks'
with TLJH as the base. For example, the earth sciences community can make
a plugin that installs commonly used packages, set up authentication
and pre-download useful datasets. The mybinder.org community can
make a plugin that gives you a single-node, single-repository mybinder.org.
Plugins are very powerful, so the possibilities are endless.
Design
======
`pluggy <https://github.com/pytest-dev/pluggy>`_ is used to implement
plugin functionality. TLJH exposes specific **hooks** that your plugin
can provide implementations for. This allows us to have specific hook
points in the application that can be explicitly extended by plugins,
balancing the need to change TLJH internals in the future with the
stability required for a good plugin ecosystem.
Installing Plugins
==================
Include ``--plugin <install_name>`` in the Installer script. See :ref:`topic/customizing-installer` for more info.
Writing a simple plugins
========================
We shall try to write a simple plugin that installs a few libraries,
and use it to explain how the plugin mechanism works. We shall call
this plugin ``tljh-simple``.
Plugin directory layout
-----------------------
We recommend creating a new git repo for your plugin. Plugins are
normal python packages - however, since they are usually simpler,
we recommend they live in one file.
For ``tljh-simple``, the repository's structure should look like:
.. code-block:: none
tljh_simple:
- tljh_simple.py
- setup.py
- README.md
- LICENSE
The ``README.md`` (or ``README.rst`` file) contains human readable
information about what your plugin does for your users. ``LICENSE``
specifies the license used by your plugin - we recommend the
3-Clause BSD License, since that is what is used by TLJH itself.
``setup.py`` - metadata & registration
--------------------------------------
``setup.py`` marks this as a python package, and contains metadata
about the package itself. It should look something like:
.. code-block:: python
from setuptools import setup
setup(
name="tljh-simple",
author="YuviPanda",
version="0.1",
license="3-clause BSD",
url='https://github.com/yuvipanda/tljh-simple',
entry_points={"tljh": ["simple = tljh_simple"]},
py_modules=["tljh_simple"],
)
This is a mostly standard ``setup.py`` file. ``entry_points={"tljh": ["simple = tljh_simple]}``
'registers' the module ``tljh_simple`` (in file ``tljh_simple.py``) with TLJH as a plugin.
``tljh_simple.py`` - implementation
-----------------------------------
In ``tljh_simple.py``, you provide implementations for whichever hooks
you want to extend.
A hook implementation is a function that has the following characteristics:
#. Has same name as the hook
#. Accepts some or all of the parameters defined for the hook
#. Is decorated with the ``hookimpl`` decorator function, imported from
``tljh.hooks``.
The current list of available hooks and when they are called can be
seen in `tljh/hooks.py <https://github.com/jupyterhub/the-littlest-jupyterhub/blob/main/tljh/hooks.py>`_
in the source repository. Example implementations of each hook can be referenced from
`integration-tests/plugins/simplest/tljh_simplest.py
<https://github.com/jupyterhub/the-littlest-jupyterhub/blob/main/integration-tests/plugins/simplest/tljh_simplest.py>`_.
This example provides an implementation for the ``tljh_extra_user_conda_packages``
hook, which can return a list of conda packages that'll be installed in users'
environment from conda-forge.
.. code-block:: python
from tljh.hooks import hookimpl
@hookimpl
def tljh_extra_user_conda_packages():
return [
'xarray',
'iris',
'dask',
]
Publishing plugins
==================
Plugins are python packages and should be published on PyPI. Users
can also install them directly from GitHub - although this is
not good long term practice.
The python package should be named ``tljh-<pluginname>``.
List of known plugins
=====================
If you are looking for a way to extend or customize your TLJH deployment, you might want to look for existing plugins.
Here is a non-exhaustive list of known TLJH plugins:
- `tljh-pangeo <https://github.com/yuvipanda/tljh-pangeo>`_: TLJH plugin for setting up the Pangeo Stack.
- `tljh-voila-gallery <https://github.com/voila-dashboards/tljh-voila-gallery>`_: TLJH plugin that installs a gallery of Voilà dashboards.
- `tljh-repo2docker <https://github.com/plasmabio/tljh-repo2docker>`_: TLJH plugin to build multiple user environments with
`repo2docker <https://repo2docker.readthedocs.io>`_.
- `tljh-shared-directory <https://github.com/kafonek/tljh-shared-directory>`_: TLJH plugin which sets up a *shared directory*
for the Hub users in ``/srv/scratch``.
- `tljh-db <https://github.com/sinzlab/tljh-db>`_: TLJH plugin for working with mysql databases.
If you have authored a plugin, please open a PR to add it to this list!
We also recommend adding the ``tljh-plugin`` topic to the GitHub repository to make it more discoverable:
`https://github.com/topics/tljh-plugin <https://github.com/topics/tljh-plugin>`_

62
docs/contributing/tests.md Normal file
View File

@@ -0,0 +1,62 @@
(contributing-tests)=
# Testing TLJH
Unit and integration tests are a core part of TLJH, as important as
the code & documentation. They help validate that the code works as
we think it does, and continues to do so when changes occur. They
also help communicate in precise terms what we expect our code
to do.
## Integration tests
TLJH is a _distribution_ where the primary value is the many
opinionated choices we have made on components to use and how
they fit together. Integration tests are perfect for testing
that the various components fit together and work as they should.
So we write a lot of integration tests, and put in more effort
towards them than unit tests.
All integration tests are run in [GitHub Actions](https://github.com/jupyterhub/the-littlest-jupyterhub/actions)
for each PR and merge, making sure we don't have broken tests
for too long.
The integration tests are in the `integration-tests` directory
in the git repository. `py.test` is used to write the integration
tests. Each file should contain tests that can be run in any order
against the same installation of TLJH.
### Running integration tests locally
You need `docker` installed and callable by the user running
the integration tests without needing sudo.
You can then run the tests with:
```bash
.github/integration-test.py run-test <name-of-run> <test-file-names>
```
- `<name-of-run>` is an identifier for the tests - you can choose anything you want
- `<test-file-names>>` is list of test files (under `integration-tests`) that should be run in one go.
For example, to run all the basic tests, you would write:
```bash
.github/integration-test.py run-test basic-tests \
test_hub.py \
test_proxy.py \
test_install.py \
test_extensions.py
```
This will run the tests in the three files against the same installation
of TLJH and report errors.
If you would like to run the tests with a custom pip spec for the bootstrap script, you can use the `--bootstrap-pip-spec`
parameter:
```bash
.github/integration-test.py run-test <name-of-run> <test-file-names> \
--bootstrap-pip-spec="git+https://github.com/your-username/the-littlest-jupyterhub.git@branch-name"
```

66
docs/contributing/tests.rst
View File

@@ -1,66 +0,0 @@
.. _contributing/tests:
============
Testing TLJH
============
Unit and integration tests are a core part of TLJH, as important as
the code & documentation. They help validate that the code works as
we think it does, and continues to do so when changes occur. They
also help communicate in precise terms what we expect our code
to do.
Integration tests
=================
TLJH is a *distribution* where the primary value is the many
opinionated choices we have made on components to use and how
they fit together. Integration tests are perfect for testing
that the various components fit together and work as they should.
So we write a lot of integration tests, and put in more effort
towards them than unit tests.
All integration tests are run in `GitHub Actions <https://github.com/jupyterhub/the-littlest-jupyterhub/actions>`_
for each PR and merge, making sure we don't have broken tests
for too long.
The integration tests are in the ``integration-tests`` directory
in the git repository. ``py.test`` is used to write the integration
tests. Each file should contain tests that can be run in any order
against the same installation of TLJH.
Running integration tests locally
---------------------------------
You need ``docker`` installed and callable by the user running
the integration tests without needing sudo.
You can then run the tests with:
.. code-block:: bash
.github/integration-test.py run-test <name-of-run> <test-file-names>
- ``<name-of-run>`` is an identifier for the tests - you can choose anything you want
- ``<test-file-names>>`` is list of test files (under ``integration-tests``) that should be run in one go.
For example, to run all the basic tests, you would write:
.. code-block:: bash
.github/integration-test.py run-test basic-tests \
test_hub.py \
test_proxy.py \
test_install.py \
test_extensions.py
This will run the tests in the three files against the same installation
of TLJH and report errors.
If you would like to run the tests with a custom pip spec for the bootstrap script, you can use the ``--bootstrap-pip-spec``
parameter:
.. code-block:: bash
.github/integration-test.py run-test <name-of-run> <test-file-names> \
--bootstrap-pip-spec="git+https://github.com/your-username/the-littlest-jupyterhub.git@branch-name"

100
docs/howto/admin/admin-users.md Normal file
View File

@@ -0,0 +1,100 @@
(howto-admin-admin-users)=
# Add / Remove admin users
Admin users in TLJH have the following powers:
1. Full root access to the server with passwordless `sudo`.
This lets them do literally whatever they want in the server
2. Access servers / home directories of all other users
3. Install new packages for everyone with `conda`, `pip` or `apt`
4. Change configuration of TLJH
This is a lot of power, so make sure you know who you are giving it
to. Admin users should have decent passwords / secure login mechanisms,
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)
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.
:::
## Adding admin users from the JupyterHub interface
There are two primary user interfaces for doing work on your JupyterHub. By
default, this is the Notebook Interface, and will be used in this section.
If you are using JupyterLab, you can access the Notebook Interface by replacing
`/lab` with `/tree` in your URL.
1. First, navigate to the Jupyter Notebook interface home page. You can do this
by going to the URL `<my-hub-url>/user/<my-username>/tree`.
2. Open the **Control Panel** by clicking the control panel button on the top
right of your JupyterHub.
```{image} ../../images/control-panel-button.png
:alt: Control panel button in notebook, top right
```
3. In the control panel, open the **Admin** link in the top left.
```{image} ../../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
```
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
4. Click the **Add Users** button.
```{image} ../../images/admin/add-users-button.png
:alt: Add Users button in the admin page
```
A **Add Users** dialog box opens up.
5. Type the names of users you want to add to this JupyterHub in the dialog box,
one per line. **Make sure to tick the Admin checkbox**.
```{image} ../../images/admin/add-users-dialog.png
:alt: Adding users with add users dialog
```
6. Click the **Add Users** button in the dialog box. Your users are now added
to the JupyterHub with administrator privileges!
## Adding admin users from the command line
Sometimes it is easier to add or remove admin users from the command line (for
example, if you forgot to add an admin user when first setting up your JupyterHub).
### Adding new admin users
New admin users can be added by executing the following commands on an
admin terminal:
```bash
sudo tljh-config add-item users.admin <username>
sudo tljh-config reload
```
If the user is already using the JupyterHub, they might have to stop and
start their server from the control panel to gain new powers.
### Removing admin users
You can remove an existing admin user by executing the following commands in
an admin terminal:
```bash
sudo tljh-config remove-item users.admin <username>
sudo tljh-config reload
```
If the user is already using the JupyterHub, they will continue to have
some of their admin powers until their server is stopped. Another admin
can force their server to stop by clicking 'Stop Server' in the admin
panel.

102
docs/howto/admin/admin-users.rst
View File

@@ -1,102 +0,0 @@
.. _howto/admin/admin-users:
========================
Add / Remove admin users
========================
Admin users in TLJH have the following powers:
#. Full root access to the server with passwordless ``sudo``.
This lets them do literally whatever they want in the server
#. Access servers / home directories of all other users
#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
#. Change configuration of TLJH
This is a lot of power, so make sure you know who you are giving it
to. Admin users should have decent passwords / secure login mechanisms,
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 :ref:`--admin <topic/customizing-installer/admin>`
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.
Adding admin users from the JupyterHub interface
================================================
There are two primary user interfaces for doing work on your JupyterHub. By
default, this is the Notebook Interface, and will be used in this section.
If you are using JupyterLab, you can access the Notebook Interface by replacing
``/lab`` with ``/tree`` in your URL.
#. First, navigate to the Jupyter Notebook interface home page. You can do this
by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
#. Open the **Control Panel** by clicking the control panel button on the top
right of your JupyterHub.
.. image:: ../../images/control-panel-button.png
:alt: Control panel button in notebook, top right
#. In the control panel, open the **Admin** link in the top left.
.. image:: ../../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
#. Click the **Add Users** button.
.. image:: ../../images/admin/add-users-button.png
:alt: Add Users button in the admin page
A **Add Users** dialog box opens up.
#. Type the names of users you want to add to this JupyterHub in the dialog box,
one per line. **Make sure to tick the Admin checkbox**.
.. image:: ../../images/admin/add-users-dialog.png
:alt: Adding users with add users dialog
#. Click the **Add Users** button in the dialog box. Your users are now added
to the JupyterHub with administrator privileges!
Adding admin users from the command line
========================================
Sometimes it is easier to add or remove admin users from the command line (for
example, if you forgot to add an admin user when first setting up your JupyterHub).
Adding new admin users
----------------------
New admin users can be added by executing the following commands on an
admin terminal:
.. code-block:: bash
sudo tljh-config add-item users.admin <username>
sudo tljh-config reload
If the user is already using the JupyterHub, they might have to stop and
start their server from the control panel to gain new powers.
Removing admin users
--------------------
You can remove an existing admin user by executing the following commands in
an admin terminal:
.. code-block:: bash
sudo tljh-config remove-item users.admin <username>
sudo tljh-config reload
If the user is already using the JupyterHub, they will continue to have
some of their admin powers until their server is stopped. Another admin
can force their server to stop by clicking 'Stop Server' in the admin
panel.

56
docs/howto/admin/enable-extensions.md Normal file
View File

@@ -0,0 +1,56 @@
(howto-admin-extensions)=
# Enabling Jupyter Notebook extensions
Jupyter contributed notebook
[extensions](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/index.html) are
community-contributed and maintained plug-ins to the Jupyter notebook. These extensions
serve many purposes, from [pedagogical tools](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/codefolding/readme.html)
to tools for [converting](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/latex_envs/README.html)
and [editing](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/spellchecker/README.html)
notebooks.
Extensions are often added and enabled through the graphical user interface of the notebook.
However, this interface only makes the extension available to the user, not all users on a
hub. Instead, to make contributed extensions available to your users, you will use the command
line. This can be completed using the terminal in the JupyterHub (or via SSH-ing into your
VM and using this terminal).
(tljh-extension-cli)=
## Enabling extensions via the command line
1. There are [multiple ways](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html)
to install contributed extensions. For this example, we will use `pip`.
```bash
sudo -E pip install jupyter_contrib_nbextensions
```
2. Next, add the notebook extension style files to the Jupyter configuration files.
```bash
sudo -E jupyter contrib nbextension install --sys-prefix
```
3. Then, you will enable the extensions you would like to use. The syntax for this is
`jupyter nbextension enable` followed by the path to the desired extension's main file.
For example, to enable [scratchpad](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/scratchpad/README.html),
you would type the following:
```bash
sudo -E jupyter nbextension enable scratchpad/main --sys-prefix
```
4. When this is completed, the enabled extension should be visible in the extension list:
```bash
jupyter nbextension list
```
5. You can also verify the availability of the extension via its user interface in the notebook.
For example, spellchecker adds an ABC checkmark icon to the interface.
```{image} ../../images/admin/enable-spellcheck.png
:alt: spellcheck-interface-changes
```

58
docs/howto/admin/enable-extensions.rst
View File

@@ -1,58 +0,0 @@
.. _howto/admin/extensions:
====================================
Enabling Jupyter Notebook extensions
====================================
Jupyter contributed notebook
`extensions <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/index.html>`_ are
community-contributed and maintained plug-ins to the Jupyter notebook. These extensions
serve many purposes, from `pedagogical tools <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/codefolding/readme.html>`_
to tools for `converting <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/latex_envs/README.html>`_
and `editing <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/spellchecker/README.html>`_
notebooks.
Extensions are often added and enabled through the graphical user interface of the notebook.
However, this interface only makes the extension available to the user, not all users on a
hub. Instead, to make contributed extensions available to your users, you will use the command
line. This can be completed using the terminal in the JupyterHub (or via SSH-ing into your
VM and using this terminal).
.. _tljh_extension_cli:
Enabling extensions via the command line
========================================
#. There are `multiple ways <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html>`_
to install contributed extensions. For this example, we will use ``pip``.
.. code-block:: bash
sudo -E pip install jupyter_contrib_nbextensions
#. Next, add the notebook extension style files to the Jupyter configuration files.
.. code-block:: bash
sudo -E jupyter contrib nbextension install --sys-prefix
#. Then, you will enable the extensions you would like to use. The syntax for this is
``jupyter nbextension enable`` followed by the path to the desired extension's main file.
For example, to enable `scratchpad <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/scratchpad/README.html>`_,
you would type the following:
.. code-block:: bash
sudo -E jupyter nbextension enable scratchpad/main --sys-prefix
#. When this is completed, the enabled extension should be visible in the extension list:
.. code-block:: bash
jupyter nbextension list
#. You can also verify the availability of the extension via its user interface in the notebook.
For example, spellchecker adds an ABC checkmark icon to the interface.
.. image:: ../../images/admin/enable-spellcheck.png
:alt: spellcheck-interface-changes

118
docs/howto/admin/https.md Normal file
View File

@@ -0,0 +1,118 @@
(howto-admin-https)=
# Enable HTTPS
Every JupyterHub deployment should enable HTTPS!
HTTPS encrypts traffic so that usernames, passwords and your data are
communicated securely. sensitive bits of information are communicated
securely. The Littlest JupyterHub supports automatically configuring HTTPS
via [Let's Encrypt](https://letsencrypt.org), or setting it up
[manually](#howto-admin-https-manual) with your own TLS key and
certificate. Unless you have a strong reason to use the manual method,
you should use the [Let's Encrypt](#howto-admin-https-letsencrypt)
method.
:::{note}
You _must_ have a domain name set up to point to the IP address on
which TLJH is accessible before you can set up HTTPS.
To do that, you would have to log in to the website of your registrar
and go to the DNS records section. The interface will look like something
similar to this:
> ```{image} ../../images/dns.png
> :alt: Adding an entry to the DNS records
> ```
:::
(howto-admin-https-letsencrypt)=
## Automatic HTTPS with Let's Encrypt
:::{note}
If the machine you are running on is not reachable from the internet -
for example, if it is a machine internal to your organization that
is cut off from the internet - you can not use this method. Please
set up a DNS entry and HTTPS [manually](#howto-admin-https-manual).
:::
To enable HTTPS via letsencrypt:
```
sudo tljh-config set https.enabled true
sudo tljh-config set https.letsencrypt.email you@example.com
sudo tljh-config add-item https.letsencrypt.domains yourhub.yourdomain.edu
```
where `you@example.com` is your email address and `yourhub.yourdomain.edu`
is the domain where your hub will be running.
Once you have loaded this, your config should look like:
```
sudo tljh-config show
```
```yaml
https:
enabled: true
letsencrypt:
email: you@example.com
domains:
- yourhub.yourdomain.edu
```
Finally, you can reload the proxy to load the new configuration:
```
sudo tljh-config reload proxy
```
At this point, the proxy should negotiate with Let's Encrypt to set up a
trusted HTTPS certificate for you. It may take a moment for the proxy to
negotiate with Let's Encrypt to get your certificates, after which you can
access your Hub securely at <https://yourhub.yourdomain.edu>.
These certificates are valid for 3 months. The proxy will automatically
renew them for you before they expire.
(howto-admin-https-manual)=
## Manual HTTPS with existing key and certificate
You may already have an SSL key and certificate.
If so, you can tell your deployment to use these files:
```
sudo tljh-config set https.enabled true
sudo tljh-config set https.tls.key /etc/mycerts/mydomain.key
sudo tljh-config set https.tls.cert /etc/mycerts/mydomain.cert
```
Once you have loaded this, your config should look like:
```
sudo tljh-config show
```
```yaml
https:
enabled: true
tls:
key: /etc/mycerts/mydomain.key
cert: /etc/mycerts/mydomain.cert
```
Finally, you can reload the proxy to load the new configuration:
```
sudo tljh-config reload proxy
```
and now access your Hub securely at <https://yourhub.yourdomain.edu>.
## Troubleshooting
If you're having trouble with HTTPS, looking at the [traefik proxy logs](troubleshooting-logs-traefik) might help.

112
docs/howto/admin/https.rst
View File

@@ -1,112 +0,0 @@
.. _howto/admin/https:
============
Enable HTTPS
============
Every JupyterHub deployment should enable HTTPS!
HTTPS encrypts traffic so that usernames, passwords and your data are
communicated securely. sensitive bits of information are communicated
securely. The Littlest JupyterHub supports automatically configuring HTTPS
via `Let's Encrypt <https://letsencrypt.org>`_, or setting it up
:ref:`manually <howto/admin/https/manual>` with your own TLS key and
certificate. Unless you have a strong reason to use the manual method,
you should use the :ref:`Let's Encrypt <howto/admin/https/letsencrypt>`
method.
.. note::
You *must* have a domain name set up to point to the IP address on
which TLJH is accessible before you can set up HTTPS.
To do that, you would have to log in to the website of your registrar
and go to the DNS records section. The interface will look like something
similar to this:
.. image:: ../../images/dns.png
:alt: Adding an entry to the DNS records
.. _howto/admin/https/letsencrypt:
Automatic HTTPS with Let's Encrypt
==================================
.. note::
If the machine you are running on is not reachable from the internet -
for example, if it is a machine internal to your organization that
is cut off from the internet - you can not use this method. Please
set up a DNS entry and HTTPS :ref:`manually <howto/admin/https/manual>`.
To enable HTTPS via letsencrypt::
sudo tljh-config set https.enabled true
sudo tljh-config set https.letsencrypt.email you@example.com
sudo tljh-config add-item https.letsencrypt.domains yourhub.yourdomain.edu
where ``you@example.com`` is your email address and ``yourhub.yourdomain.edu``
is the domain where your hub will be running.
Once you have loaded this, your config should look like::
sudo tljh-config show
.. sourcecode:: yaml
https:
enabled: true
letsencrypt:
email: you@example.com
domains:
- yourhub.yourdomain.edu
Finally, you can reload the proxy to load the new configuration::
sudo tljh-config reload proxy
At this point, the proxy should negotiate with Let's Encrypt to set up a
trusted HTTPS certificate for you. It may take a moment for the proxy to
negotiate with Let's Encrypt to get your certificates, after which you can
access your Hub securely at https://yourhub.yourdomain.edu.
These certificates are valid for 3 months. The proxy will automatically
renew them for you before they expire.
.. _howto/admin/https/manual:
Manual HTTPS with existing key and certificate
==============================================
You may already have an SSL key and certificate.
If so, you can tell your deployment to use these files::
sudo tljh-config set https.enabled true
sudo tljh-config set https.tls.key /etc/mycerts/mydomain.key
sudo tljh-config set https.tls.cert /etc/mycerts/mydomain.cert
Once you have loaded this, your config should look like::
sudo tljh-config show
.. sourcecode:: yaml
https:
enabled: true
tls:
key: /etc/mycerts/mydomain.key
cert: /etc/mycerts/mydomain.cert
Finally, you can reload the proxy to load the new configuration::
sudo tljh-config reload proxy
and now access your Hub securely at https://yourhub.yourdomain.edu.
Troubleshooting
===============
If you're having trouble with HTTPS, looking at the :ref:`traefik
proxy logs <troubleshooting/logs/traefik>` might help.

13
docs/howto/admin/nbresuse.rst → docs/howto/admin/nbresuse.md
View File

@@ -1,15 +1,14 @@
.. _howto/admin/nbresuse:
(howto-admin-nbresuse)=
=======================
Check your memory usage
=======================
# Check your memory usage
The `jupyter-resource-usage <https://github.com/jupyter-server/jupyter-resource-usage>`_ extension is part of
The [jupyter-resource-usage](https://github.com/jupyter-server/jupyter-resource-usage) extension is part of
the default installation, and tells you how much memory your user is using
right now, and what the memory limit for your user is. It is shown in the
top right corner of the notebook interface. Note that this is memory usage
for everything your user is running through the Jupyter notebook interface,
not just the specific notebook it is shown on.
.. image:: ../../images/nbresuse.png
:alt: Memory limit / usage shown with jupyter-resource-usage
```{image} ../../images/nbresuse.png
:alt: Memory limit / usage shown with jupyter-resource-usage
```

52
docs/howto/admin/resize.rst → docs/howto/admin/resize.md
View File

@@ -1,60 +1,58 @@
.. _howto/admin/resize:
(howto-admin-resize)=
=================================================
Resize the resources available to your JupyterHub
=================================================
# Resize the resources available to your JupyterHub
As you are using your JupyterHub, you may need to increase or decrease
the amount of resources allocated to your TLJH install. The kinds of resources that can be
allocated, as well as the process to do so, will depend on the provider / interface for your
VM. We recommend consulting the installation page for your provider for more information. This
page covers the steps your should take on your JupyterHub *after* you've reallocated resources on
page covers the steps your should take on your JupyterHub _after_ you've reallocated resources on
the cloud provider of your choice.
Currently there are instructions to resize your resources on the following providers:
* :ref:`Digital Ocean <howto/providers/digitalocean/resize>`.
- [Digital Ocean](howto-providers-digitalocean-resize)
Once resources have been reallocated, you must tell TLJH to make use of these resources,
and verify that the resources have become available.
Verifying a Resize
==================
## Verifying a Resize
#. Once you have resized your server, tell the JupyterHub to make use of
1. Once you have resized your server, tell the JupyterHub to make use of
these new resources. To accomplish this, follow the instructions in
:ref:`topic/tljh-config` to set new memory or CPU limits and reload the hub. This can be completed
[](/topic/tljh-config) to set new memory or CPU limits and reload the hub. This can be completed
using the terminal in the JupyterHub (or via SSH-ing into your VM and using this terminal).
#. TLJH configuration options can be verified by viewing the tljh-config output.
2. TLJH configuration options can be verified by viewing the tljh-config output.
.. code-block:: bash
sudo tljh-config show
```bash
sudo tljh-config show
```
Double-check that your changes are reflected in the output.
#. **To verify changes to memory**, confirm that it worked by starting
3. **To verify changes to memory**, confirm that it worked by starting
a new server (if you had one previously running, click "Control Panel -> Stop My Server" to
shut down your active server first), opening a notebook, and checking the value of the
`jupyter-resource-usage <https://github.com/jupyter-server/jupyter-resource-usage>`_ extension in the upper-right.
[jupyter-resource-usage](https://github.com/jupyter-server/jupyter-resource-usage) extension in the upper-right.
.. image:: ../../images/nbresuse.png
:alt: jupyter-resource-usage demonstration
```{image} ../../images/nbresuse.png
:alt: jupyter-resource-usage demonstration
```
#. **To verify changes to CPU**, use the ``nproc`` from a terminal.
4. **To verify changes to CPU**, use the `nproc` from a terminal.
This command displays the number of available cores, and should be equal to the
number of cores you selected in your provider's interface.
.. code-block:: bash
```bash
nproc --all
```
nproc --all
#. **To verify currently-available disk space**, use the ``df`` command in a terminal. This shows
how much disk space is available. The ``-hT`` argument allows us to have this printed in a human readable
5. **To verify currently-available disk space**, use the `df` command in a terminal. This shows
how much disk space is available. The `-hT` argument allows us to have this printed in a human readable
format, and condenses the output to show one storage volume. Note that currently you cannot
change the disk space on a per-user basis.
.. code-block:: bash
df -hT /home
```bash
df -hT /home
```

55
docs/howto/admin/resource-estimation.rst → docs/howto/admin/resource-estimation.md
View File

@@ -1,85 +1,76 @@
.. _howto/admin/resource-estimation:
(howto-admin-resource-estimation)=
===================================
Estimate Memory / CPU / Disk needed
===================================
# Estimate Memory / CPU / Disk needed
This page helps you estimate how much Memory / CPU / Disk the server you install
The Littlest JupyterHub on should have. These are just guidelines to help
with estimation - your actual needs will vary.
Memory
======
## Memory
Memory is usually the biggest determinant of server size in most JupyterHub
installations. At minimum, your server must have at least **1GB** of RAM
for TLJH to install.
.. math::
$$
Recommended\, Memory =
(Max\, concurrent\, users \times Max\, mem\, per\, user) + 128MB
$$
Recommended\, Memory =
(Max\, concurrent\, users \times Max\, mem\, per\, user) + 128MB
The ``128MB`` is overhead for TLJH and related services. **Server Memory Recommended**
The `128MB` is overhead for TLJH and related services. **Server Memory Recommended**
is the amount of Memory (RAM) the server you acquire should have - we recommend
erring on the side of 'more Memory'. The other terms are explained below.
Maximum concurrent users
------------------------
### Maximum concurrent users
Even if your class has 100 students, most of them will not be using the JupyterHub
actively at a single given moment. At 2am on a normal night, maybe you'll have 10 students
using it. At 2am before a final, maybe you'll have 60 students using it. Maybe
you'll have a lab session with all 100 of your students using it at the same time.
The *maximum* number of users actively using the JupyterHub at any given time determines
The _maximum_ number of users actively using the JupyterHub at any given time determines
how much memory your server will need. You'll get better at estimating this number
over time. We generally recommend between 40-60% of your total class size to start with.
Maximum memory allowed per user
-------------------------------
### Maximum memory allowed per user
Depending on what kind of work your users are doing, they will use different amounts
of memory. The easiest way to determine this is to run through a typical user
workflow yourself, and measure how much memory is used. You can use :ref:`howto/admin/nbresuse`
workflow yourself, and measure how much memory is used. You can use [](/howto/admin/nbresuse)
to determine how much memory your user is using.
A good rule of thumb is to take the maximum amount of memory you used during
your session, and add 20-40% headroom for users to 'play around'. This is the
maximum amount of memory that should be given to each user.
If users use *more* than this alloted amount of memory, their notebook kernel will *restart*.
If users use _more_ than this alloted amount of memory, their notebook kernel will _restart_.
CPU
===
## CPU
CPU estimation is more forgiving than Memory estimation. If there isn't
enough CPU for your users, their computation becomes very slow - but does not
stop, unlike with RAM.
.. math::
$$
Recommended\, CPU = (Max\, concurrent\, users \times Max\, CPU\, usage\, per\, user) + 20\%
$$
Recommended\, CPU = (Max\, concurrent\, users \times Max\, CPU\, usage\, per\, user) + 20\%
The ``20%`` is overhead for TLJH and related services. This is around 20% of a
The `20%` is overhead for TLJH and related services. This is around 20% of a
single modern CPU. This, of course, is just an estimate. We recommend using
the same process used to estimate Memory required for estimating CPU required.
You cannot use jupyter-resource-usage for this, but you should carry out normal workflow and
investigate the CPU usage on the machine.
Disk space
==========
## Disk space
Unlike Memory & CPU, disk space is predicated on **total** number of users,
rather than **maximum concurrent** users.
.. math::
$$
Recommended\, Disk\, Size = (Total\, users \times Max\, disk\, usage\, per\, user) + 2GB
$$
Recommended\, Disk\, Size = (Total\, users \times Max\, disk\, usage\, per\, user) + 2GB
Resizing your server
====================
## Resizing your server
Lots of 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 -

82
docs/howto/admin/systemd.md Normal file
View File

@@ -0,0 +1,82 @@
(howto-admin-systemd)=
# Customizing `systemd` services
By default, TLJH configures two `systemd` services to run JupyterHub and Traefik.
These services come with a default set of settings, which are specified in
[jupyterhub.service](https://github.com/jupyterhub/the-littlest-jupyterhub/blob/HEAD/tljh/systemd-units/jupyterhub.service) and
[traefik.service](https://github.com/jupyterhub/the-littlest-jupyterhub/blob/HEAD/tljh/systemd-units/traefik.service).
They look like the following:
```bash
[Unit]
Requires=traefik.service
After=traefik.service
[Service]
User=root
Restart=always
WorkingDirectory=/opt/tljh/state
PrivateTmp=yes
PrivateDevices=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
Environment=TLJH_INSTALL_PREFIX=/opt/tljh
ExecStart=/opt/tljh/hub/bin/python3 -m jupyterhub.app -f jupyterhub_config.py --upgrade-db
[Install]
WantedBy=multi-user.target
```
However in some cases, admins might want to have better control on these settings.
For example when mounting shared volumes over the network using [Samba](<https://en.wikipedia.org/wiki/Samba_(software)>),
these namespacing settings might be a bit too strict and prevent users from accessing the shared volumes.
## Overriding settings with `override.conf`
To override the `jupyterhub` settings, it is possible to provide a custom `/etc/systemd/system/jupyterhub.service.d/override.conf` file.
Here is an example for the content of the file:
```bash
[Service]
PrivateTmp=no
PrivateDevices=no
ProtectKernelTunables=no
ProtectKernelModules=no
```
This example should be useful in the case of mounting volumes using Samba and sharing them with the JupyterHub users.
You might also want to provide your own options, which are listed in the
[systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.exec.html).
Then make sure to reload the daemon and the `jupyterhub` service:
```bash
sudo systemctl daemon-reload
sudo systemctl restart jupyterhub
```
Then check the status with:
```bash
sudo systemctl status jupyterhub
```
The output should look like the following:
```{image} ../../images/admin/jupyterhub-systemd-status.png
:alt: Checking the status of the JupyterHub systemd service
```
To override the `traefik` settings, create a new file under `/etc/systemd/system/traefik.service.d/override.conf`
and follow the same steps.
## References
If you would like to learn more about the `systemd` security features, check out these references:
- [List of systemd settings](https://www.freedesktop.org/software/systemd/man/systemd.exec.html)
- [Mastering systemd: Securing and sandboxing applications and services](https://www.redhat.com/sysadmin/mastering-systemd)

88
docs/howto/admin/systemd.rst
View File

@@ -1,88 +0,0 @@
.. _howto/admin/systemd:
================================
Customizing ``systemd`` services
================================
By default, TLJH configures two ``systemd`` services to run JupyterHub and Traefik.
These services come with a default set of settings, which are specified in
`jupyterhub.service <https://github.com/jupyterhub/the-littlest-jupyterhub/blob/HEAD/tljh/systemd-units/jupyterhub.service>`_ and
`traefik.service <https://github.com/jupyterhub/the-littlest-jupyterhub/blob/HEAD/tljh/systemd-units/traefik.service>`_.
They look like the following:
.. code-block:: bash
[Unit]
Requires=traefik.service
After=traefik.service
[Service]
User=root
Restart=always
WorkingDirectory=/opt/tljh/state
PrivateTmp=yes
PrivateDevices=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
Environment=TLJH_INSTALL_PREFIX=/opt/tljh
ExecStart=/opt/tljh/hub/bin/python3 -m jupyterhub.app -f jupyterhub_config.py --upgrade-db
[Install]
WantedBy=multi-user.target
However in some cases, admins might want to have better control on these settings.
For example when mounting shared volumes over the network using `Samba <https://en.wikipedia.org/wiki/Samba_(software)>`_,
these namespacing settings might be a bit too strict and prevent users from accessing the shared volumes.
Overriding settings with ``override.conf``
==========================================
To override the ``jupyterhub`` settings, it is possible to provide a custom ``/etc/systemd/system/jupyterhub.service.d/override.conf`` file.
Here is an example for the content of the file:
.. code-block:: bash
[Service]
PrivateTmp=no
PrivateDevices=no
ProtectKernelTunables=no
ProtectKernelModules=no
This example should be useful in the case of mounting volumes using Samba and sharing them with the JupyterHub users.
You might also want to provide your own options, which are listed in the
`systemd documentation <https://www.freedesktop.org/software/systemd/man/systemd.exec.html>`_.
Then make sure to reload the daemon and the ``jupyterhub`` service:
.. code-block:: bash
sudo systemctl daemon-reload
sudo systemctl restart jupyterhub
Then check the status with:
.. code-block:: bash
sudo systemctl status jupyterhub
The output should look like the following:
.. image:: ../../images/admin/jupyterhub-systemd-status.png
:alt: Checking the status of the JupyterHub systemd service
To override the ``traefik`` settings, create a new file under ``/etc/systemd/system/traefik.service.d/override.conf``
and follow the same steps.
References
==========
If you would like to learn more about the ``systemd`` security features, check out these references:
- `List of systemd settings <https://www.freedesktop.org/software/systemd/man/systemd.exec.html>`_
- `Mastering systemd: Securing and sandboxing applications and services <https://www.redhat.com/sysadmin/mastering-systemd>`_

128
docs/howto/auth/awscognito.md Normal file
View File

@@ -0,0 +1,128 @@
(howto-auth-awscognito)=
# Authenticate using AWS Cognito
The **AWS Cognito Authenticator** lets users log into your JupyterHub using
cognito user pools. To do so, you'll first need to register and configure a
cognito user pool and app, and then provide information about this
application to your `tljh` configuration.
## Create an AWS Cognito application
1. Create a user pool [Getting Started with User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html).
When you have completed creating a user pool, app, and domain you should have the following settings available to you:
- **App client id**: From the App client page
- **App client secret** From the App client page
- **Callback URL** This should be the domain you are hosting you server on:
```
http(s)://<my-tljh-ip-address>/hub/oauth_callback
```
- **Signout URL**: This is the landing page for a user when they are not logged on:
```
http(s)://<my-tljh-ip-address>
```
> - **Auth Domain** Create an auth domain e.g. \<my_jupyter_hub>:
>
> ```
> https://<<my_jupyter_hub>.auth.eu-west-1.amazoncognito.com
> ```
## Install and configure an AWS EC2 Instance with userdata
By adding following script to the ec2 instance user data you should be
able to configure the instance automatically, replace relevant placeholders:
```bash
#!/bin/bash
##############################################
# Ensure tljh is up to date
##############################################
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin insightadmin
##############################################
# Setup AWS Cognito OAuthenticator
##############################################
echo > /opt/tljh/config/jupyterhub_config.d/awscognito.py <<EOF
c.GenericOAuthenticator.client_id = "[your app client ID]"
c.GenericOAuthenticator.client_secret = "[your app client secret]"
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
# these are always the same
c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_key = "username"
c.GenericOAuthenticator.userdata_method = "POST"
EOF
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
tljh-config reload
```
## Manual configuration to use the AWS Cognito OAuthenticator
AWS Cognito is configured as a generic OAuth provider.
Using your preferred editor create the config file:
```
/opt/tljh/config/jupyterhub_config.d/awscognito.py
```
substituting the relevant variables:
```python
c.GenericOAuthenticator.client_id = "[your app ID]"
c.GenericOAuthenticator.client_secret = "[your app Password]"
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
# these are always the same
c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_key = "username"
c.GenericOAuthenticator.userdata_method = "POST"
```
We'll use the `tljh-config` tool to configure your JupyterHub's authentication.
For more information on `tljh-config`, see [](/topic/tljh-config).
1. Tell your JupyterHub to use the GenericOAuthenticator for authentication:
```
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
```
2. Restart your JupyterHub so that new users see these changes:
```
sudo tljh-config reload
```
## Confirm that the new authenticator works
1. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
2. Go to your JupyterHub URL.
3. You should see an AWS Cognito login button:
4. You will likely have to create a new user (sign up) and then you should be directed to the
Jupyter interface used in this JupyterHub.
5. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in [](/howto/auth/firstuse).

122
docs/howto/auth/awscognito.rst
View File

@@ -1,122 +0,0 @@
.. _howto/auth/awscognito:
==============================
Authenticate using AWS Cognito
==============================
The **AWS Cognito Authenticator** lets users log into your JupyterHub using
cognito user pools. To do so, you'll first need to register and configure a
cognito user pool and app, and then provide information about this
application to your ``tljh`` configuration.
Create an AWS Cognito application
=========================================
#. Create a user pool `Getting Started with User Pool <https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html>`_.
When you have completed creating a user pool, app, and domain you should have the following settings available to you:
* **App client id**: From the App client page
* **App client secret** From the App client page
* **Callback URL** This should be the domain you are hosting you server on::
http(s)://<my-tljh-ip-address>/hub/oauth_callback
* **Signout URL**: This is the landing page for a user when they are not logged on::
http(s)://<my-tljh-ip-address>
* **Auth Domain** Create an auth domain e.g. <my_jupyter_hub>::
https://<<my_jupyter_hub>.auth.eu-west-1.amazoncognito.com
Install and configure an AWS EC2 Instance with userdata
=======================================================
By adding following script to the ec2 instance user data you should be
able to configure the instance automatically, replace relevant placeholders::
#!/bin/bash
##############################################
# Ensure tljh is up to date
##############################################
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin insightadmin
##############################################
# Setup AWS Cognito OAuthenticator
##############################################
echo > /opt/tljh/config/jupyterhub_config.d/awscognito.py <<EOF
c.GenericOAuthenticator.client_id = "[your app client ID]"
c.GenericOAuthenticator.client_secret = "[your app client secret]"
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
# these are always the same
c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_key = "username"
c.GenericOAuthenticator.userdata_method = "POST"
EOF
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
tljh-config reload
Manual configuration to use the AWS Cognito OAuthenticator
==========================================================
AWS Cognito is configured as a generic OAuth provider.
Using your preferred editor create the config file::
/opt/tljh/config/jupyterhub_config.d/awscognito.py
substituting the relevant variables::
c.GenericOAuthenticator.client_id = "[your app ID]"
c.GenericOAuthenticator.client_secret = "[your app Password]"
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
# these are always the same
c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_key = "username"
c.GenericOAuthenticator.userdata_method = "POST"
We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
#. Tell your JupyterHub to use the GenericOAuthenticator for authentication::
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
#. Restart your JupyterHub so that new users see these changes::
sudo tljh-config reload
Confirm that the new authenticator works
========================================
#. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
#. Go to your JupyterHub URL.
#. You should see an AWS Cognito login button:
#. You will likely have to create a new user (sign up) and then you should be directed to the
Jupyter interface used in this JupyterHub.
#. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`.

47
docs/howto/auth/dummy.md Normal file
View File

@@ -0,0 +1,47 @@
(howto-auth-dummy)=
# Authenticate _any_ user with a single shared password
The **Dummy Authenticator** lets _any_ user log in with the given password.
This authenticator is **extremely insecure**, so do not use it if you can
avoid it.
## Enabling the authenticator
1. Always use DummyAuthenticator with a password. You can communicate this
password to all your users via an out of band mechanism (like writing on
a whiteboard). Once you have selected a password, configure TLJH to use
the password by executing the following from an admin console.
```bash
sudo tljh-config set auth.DummyAuthenticator.password <password>
```
Remember to replace `<password>` with the password you choose.
2. Enable the authenticator and reload config to apply configuration:
```bash
sudo tljh-config set auth.type dummy
```
```bash
sudo tljh-config reload
```
Users who are currently logged in will continue to be logged in. When they
log out and try to log back in, they will be asked to provide a username and
password.
## Changing the password
The password used by DummyAuthenticator can be changed with the following
commands:
```bash
tljh-config set auth.DummyAuthenticator.password <new-password>
```
```bash
tljh-config reload
```

51
docs/howto/auth/dummy.rst
View File

@@ -1,51 +0,0 @@
.. _howto/auth/dummy:
=====================================================
Authenticate *any* user with a single shared password
=====================================================
The **Dummy Authenticator** lets *any* user log in with the given password.
This authenticator is **extremely insecure**, so do not use it if you can
avoid it.
Enabling the authenticator
==========================
1. Always use DummyAuthenticator with a password. You can communicate this
password to all your users via an out of band mechanism (like writing on
a whiteboard). Once you have selected a password, configure TLJH to use
the password by executing the following from an admin console.
.. code-block:: bash
sudo tljh-config set auth.DummyAuthenticator.password <password>
Remember to replace ``<password>`` with the password you choose.
2. Enable the authenticator and reload config to apply configuration:
.. code-block:: bash
sudo tljh-config set auth.type dummy
.. code-block:: bash
sudo tljh-config reload
Users who are currently logged in will continue to be logged in. When they
log out and try to log back in, they will be asked to provide a username and
password.
Changing the password
=====================
The password used by DummyAuthenticator can be changed with the following
commands:
.. code-block:: bash
tljh-config set auth.DummyAuthenticator.password <new-password>
.. code-block:: bash
tljh-config reload

79
docs/howto/auth/firstuse.md Normal file
View File

@@ -0,0 +1,79 @@
(howto-auth-firstuse)=
# Let users choose a password when they first log in
The **First Use Authenticator** lets users choose their own password.
Upon their first log-in attempt, whatever password they use will be stored
as their password for subsequent log in attempts. This is
the default authenticator that ships with TLJH.
## Enabling the authenticator
:::{note}
the FirstUseAuthenticator is enabled by default in TLJH.
:::
Enable the authenticator and reload config to apply the configuration:
```bash
sudo tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
sudo tljh-config reload
```
Users who are currently logged in will continue to be logged in. When they
log out and try to log back in, they will be asked to provide a username and
password.
## Users changing their own password
Users can change their password by first logging into their account and then visiting
the url `<your_server_ip>/hub/auth/change-password`.
## Allowing anyone to log in to your JupyterHub
By default, you need to manually create user accounts before they will be able
to log in to your JupyterHub. If you wish to allow **any** user to access
the JupyterHub, run the following command.
```bash
tljh-config set auth.FirstUseAuthenticator.create_users true
tljh-config reload
```
## Resetting user password
The admin can reset user passwords by _deleting_ the user from the JupyterHub admin
page. This logs the user out, but does **not** remove any of their data or
home directories. The user can then set a new password by logging in again with
their new password.
1. As an admin user, open the **Control Panel** by clicking the control panel
button on the top right of your JupyterHub.
```{image} ../../images/control-panel-button.png
:alt: Control panel button in notebook, top right
```
2. In the control panel, open the **Admin** link in the top left.
```{image} ../../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
```
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
3. **Delete** the user whose password needs resetting. Remember this **does not**
delete their data or home directory.
```{image} ../../images/auth/firstuse/delete-user.png
:alt: Delete user button for each user
```
If there is a confirmation dialog, confirm the deletion. This will also log the
user out if they were currently running.
4. Re-create the user whose password needs resetting within that same dialog.
5. Ask the user to log in again with their new password as usual. This will be their
new password going forward.

81
docs/howto/auth/firstuse.rst
View File

@@ -1,81 +0,0 @@
.. _howto/auth/firstuse:
==================================================
Let users choose a password when they first log in
==================================================
The **First Use Authenticator** lets users choose their own password.
Upon their first log-in attempt, whatever password they use will be stored
as their password for subsequent log in attempts. This is
the default authenticator that ships with TLJH.
Enabling the authenticator
==========================
.. note:: the FirstUseAuthenticator is enabled by default in TLJH.
#. Enable the authenticator and reload config to apply the configuration:
.. code-block:: bash
sudo tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
sudo tljh-config reload
Users who are currently logged in will continue to be logged in. When they
log out and try to log back in, they will be asked to provide a username and
password.
Users changing their own password
=================================
Users can change their password by first logging into their account and then visiting
the url ``<your_server_ip>/hub/auth/change-password``.
Allowing anyone to log in to your JupyterHub
============================================
By default, you need to manually create user accounts before they will be able
to log in to your JupyterHub. If you wish to allow **any** user to access
the JupyterHub, run the following command.
.. code-block:: bash
tljh-config set auth.FirstUseAuthenticator.create_users true
tljh-config reload
Resetting user password
=======================
The admin can reset user passwords by *deleting* the user from the JupyterHub admin
page. This logs the user out, but does **not** remove any of their data or
home directories. The user can then set a new password by logging in again with
their new password.
#. As an admin user, open the **Control Panel** by clicking the control panel
button on the top right of your JupyterHub.
.. image:: ../../images/control-panel-button.png
:alt: Control panel button in notebook, top right
#. In the control panel, open the **Admin** link in the top left.
.. image:: ../../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
#. **Delete** the user whose password needs resetting. Remember this **does not**
delete their data or home directory.
.. image:: ../../images/auth/firstuse/delete-user.png
:alt: Delete user button for each user
If there is a confirmation dialog, confirm the deletion. This will also log the
user out if they were currently running.
#. Re-create the user whose password needs resetting within that same dialog.
#. Ask the user to log in again with their new password as usual. This will be their
new password going forward.

108
docs/howto/auth/github.md Normal file
View File

@@ -0,0 +1,108 @@
(howto-auth-github)=
# Authenticate using GitHub Usernames
The **GitHub Authenticator** lets users log into your JupyterHub using their
GitHub user ID / password. To do so, you'll first need to register an
application with GitHub, and then provide information about this
application to your `tljh` configuration.
:::{note}
You'll need a GitHub account in order to complete these steps.
:::
## Step 1: Create a GitHub application
1. Go to the [GitHub OAuth app creation page](https://github.com/settings/applications/new).
- **Application name**: Choose a descriptive application name (e.g. `tljh`)
- **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. `` http(s)://<my-tljh-url>` ``.
- **Application description**: Use any description that you like.
- **Authorization callback URL**: Insert text with the following form:
```
http(s)://<my-tljh-ip-address>/hub/oauth_callback
```
- When you're done filling in the page, it should look something like this:
> ```{image} ../../images/auth/github/create_application.png
> :alt: Create a GitHub OAuth application
> ```
2. Click "Register application". You'll be taken to a page with the registered application details.
3. Copy the **Client ID** and **Client Secret** from the application details
page. You will use these later to configure your JupyterHub authenticator.
```{image} ../../images/auth/github/client_id_secret.png
:alt: Your client ID and secret
```
:::{important}
If you are using a virtual machine from a cloud provider and
**stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
IP address** to it. In this case, **you must update your GitHub application information**
with the new IP address.
:::
## Configure your JupyterHub to use the GitHub Oauthenticator
We'll use the `tljh-config` tool to configure your JupyterHub's authentication.
For more information on `tljh-config`, see [](/topic/tljh-config).
1. Log in as an administrator account to your JupyterHub.
2. Open a terminal window.
```{image} ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
```
3. Configure the GitHub OAuthenticator to use your client ID, client secret and callback URL with the following commands:
```
sudo tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
```
```
sudo tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
```
```
sudo tljh-config set auth.GitHubOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
```
4. Tell your JupyterHub to _use_ the GitHub OAuthenticator for authentication:
```
sudo tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
```
5. Restart your JupyterHub so that new users see these changes:
```
sudo tljh-config reload
```
## Confirm that the new authenticator works
1. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
2. Go to your JupyterHub URL.
3. You should see a GitHub login button like below:
```{image} ../../images/auth/github/login_button.png
:alt: The GitHub authenticator login button.
```
4. After you log in with your GitHub credentials, you should be directed to the
Jupyter interface used in this JupyterHub.
5. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in [](/howto/auth/firstuse).

93
docs/howto/auth/github.rst
View File

@@ -1,93 +0,0 @@
.. _howto/auth/github:
===================================
Authenticate using GitHub Usernames
===================================
The **GitHub Authenticator** lets users log into your JupyterHub using their
GitHub user ID / password. To do so, you'll first need to register an
application with GitHub, and then provide information about this
application to your ``tljh`` configuration.
.. note::
You'll need a GitHub account in order to complete these steps.
Step 1: Create a GitHub application
===================================
#. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
* **Application name**: Choose a descriptive application name (e.g. ``tljh``)
* **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http(s)://<my-tljh-url>```.
* **Application description**: Use any description that you like.
* **Authorization callback URL**: Insert text with the following form::
http(s)://<my-tljh-ip-address>/hub/oauth_callback
* When you're done filling in the page, it should look something like this:
.. image:: ../../images/auth/github/create_application.png
:alt: Create a GitHub OAuth application
#. Click "Register application". You'll be taken to a page with the registered application details.
#. Copy the **Client ID** and **Client Secret** from the application details
page. You will use these later to configure your JupyterHub authenticator.
.. image:: ../../images/auth/github/client_id_secret.png
:alt: Your client ID and secret
.. important::
If you are using a virtual machine from a cloud provider and
**stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
IP address** to it. In this case, **you must update your GitHub application information**
with the new IP address.
Configure your JupyterHub to use the GitHub Oauthenticator
==========================================================
We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
#. Log in as an administrator account to your JupyterHub.
#. Open a terminal window.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. Configure the GitHub OAuthenticator to use your client ID, client secret and callback URL with the following commands::
sudo tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
::
sudo tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
::
sudo tljh-config set auth.GitHubOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
sudo tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
#. Restart your JupyterHub so that new users see these changes::
sudo tljh-config reload
Confirm that the new authenticator works
========================================
#. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
#. Go to your JupyterHub URL.
#. You should see a GitHub login button like below:
.. image:: ../../images/auth/github/login_button.png
:alt: The GitHub authenticator login button.
#. After you log in with your GitHub credentials, you should be directed to the
Jupyter interface used in this JupyterHub.
#. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`.

133
docs/howto/auth/google.md Normal file
View File

@@ -0,0 +1,133 @@
(howto-auth-google)=
# Authenticate using Google
The **Google Authenticator** lets users log into your JupyterHub using their
Google user ID / password. To do so, you'll first need to register an
application with Google, and then provide information about this
application to your `tljh` configuration.
See [Google's documentation](https://developers.google.com/identity/protocols/OAuth2)
on how to create OAUth 2.0 client credentials.
:::{note}
You'll need a Google account in order to complete these steps.
:::
## Step 1: Create a Google project
Go to [Google Developers Console](https://console.developers.google.com)
and create a new project:
```{image} ../../images/auth/google/create_new_project.png
:alt: Create a Google project
```
## Step 2: Set up a Google OAuth client ID and secret
1. After creating and selecting the project:
- Go to the credentials menu:
```{image} ../../images/auth/google/credentials_button.png
:alt: Credentials menu
```
- Click "Create credentials" and from the dropdown menu select **"OAuth client ID"**:
```{image} ../../images/auth/google/create_credentials.png
:alt: Generate credentials
```
- You will have to fill a form with:
- **Application type**: Choose _Web application_
- **Name**: A descriptive name for your OAuth client ID (e.g. `tljh-client`)
- **Authorized JavaScript origins**: Use the IP address or URL of your JupyterHub. e.g. `http(s)://<my-tljh-url>`.
- **Authorized redirect URIs**: Insert text with the following form:
```
http(s)://<my-tljh-ip-address>/hub/oauth_callback
```
- When you're done filling in the page, it should look something like this (ideally without the red warnings):
```{image} ../../images/auth/google/create_oauth_client_id.png
:alt: Create a Google OAuth client ID
```
2. Click "Create". You'll be taken to a page with the registered application details.
3. Copy the **Client ID** and **Client Secret** from the application details
page. You will use these later to configure your JupyterHub authenticator.
```{image} ../../images/auth/google/client_id_secret.png
:alt: Your client ID and secret
```
:::{important}
If you are using a virtual machine from a cloud provider and
**stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
IP address** to it. In this case, **you must update your Google application information**
with the new IP address.
:::
## Configure your JupyterHub to use the Google Oauthenticator
We'll use the `tljh-config` tool to configure your JupyterHub's authentication.
For more information on `tljh-config`, see [](/topic/tljh-config).
1. Log in as an administrator account to your JupyterHub.
2. Open a terminal window.
```{image} ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
```
3. Configure the Google OAuthenticator to use your client ID, client secret and callback URL with the following commands:
```
sudo tljh-config set auth.GoogleOAuthenticator.client_id '<my-tljh-client-id>'
```
```
sudo tljh-config set auth.GoogleOAuthenticator.client_secret '<my-tljh-client-secret>'
```
```
sudo tljh-config set auth.GoogleOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
```
4. Tell your JupyterHub to _use_ the Google OAuthenticator for authentication:
```
sudo tljh-config set auth.type oauthenticator.google.GoogleOAuthenticator
```
5. Restart your JupyterHub so that new users see these changes:
```
sudo tljh-config reload
```
## Confirm that the new authenticator works
1. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
2. Go to your JupyterHub URL.
3. You should see a Google login button like below:
```{image} ../../images/auth/google/login_button.png
:alt: The Google authenticator login button.
```
4. After you log in with your Google credentials, you should be directed to the
Jupyter interface used in this JupyterHub.
5. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in [](/howto/auth/firstuse).

119
docs/howto/auth/google.rst
View File

@@ -1,119 +0,0 @@
.. _howto/auth/google:
=========================
Authenticate using Google
=========================
The **Google Authenticator** lets users log into your JupyterHub using their
Google user ID / password. To do so, you'll first need to register an
application with Google, and then provide information about this
application to your ``tljh`` configuration.
See `Google's documentation <https://developers.google.com/identity/protocols/OAuth2>`_
on how to create OAUth 2.0 client credentials.
.. note::
You'll need a Google account in order to complete these steps.
Step 1: Create a Google project
===============================
Go to `Google Developers Console <https://console.developers.google.com>`_
and create a new project:
.. image:: ../../images/auth/google/create_new_project.png
:alt: Create a Google project
Step 2: Set up a Google OAuth client ID and secret
==================================================
1. After creating and selecting the project:
* Go to the credentials menu:
.. image:: ../../images/auth/google/credentials_button.png
:alt: Credentials menu
* Click "Create credentials" and from the dropdown menu select **"OAuth client ID"**:
.. image:: ../../images/auth/google/create_credentials.png
:alt: Generate credentials
* You will have to fill a form with:
* **Application type**: Choose *Web application*
* **Name**: A descriptive name for your OAuth client ID (e.g. ``tljh-client``)
* **Authorized JavaScript origins**: Use the IP address or URL of your JupyterHub. e.g. ``http(s)://<my-tljh-url>``.
* **Authorized redirect URIs**: Insert text with the following form::
http(s)://<my-tljh-ip-address>/hub/oauth_callback
* When you're done filling in the page, it should look something like this (ideally without the red warnings):
.. image:: ../../images/auth/google/create_oauth_client_id.png
:alt: Create a Google OAuth client ID
2. Click "Create". You'll be taken to a page with the registered application details.
3. Copy the **Client ID** and **Client Secret** from the application details
page. You will use these later to configure your JupyterHub authenticator.
.. image:: ../../images/auth/google/client_id_secret.png
:alt: Your client ID and secret
.. important::
If you are using a virtual machine from a cloud provider and
**stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
IP address** to it. In this case, **you must update your Google application information**
with the new IP address.
Configure your JupyterHub to use the Google Oauthenticator
==========================================================
We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
#. Log in as an administrator account to your JupyterHub.
#. Open a terminal window.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. Configure the Google OAuthenticator to use your client ID, client secret and callback URL with the following commands::
sudo tljh-config set auth.GoogleOAuthenticator.client_id '<my-tljh-client-id>'
::
sudo tljh-config set auth.GoogleOAuthenticator.client_secret '<my-tljh-client-secret>'
::
sudo tljh-config set auth.GoogleOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
#. Tell your JupyterHub to *use* the Google OAuthenticator for authentication::
sudo tljh-config set auth.type oauthenticator.google.GoogleOAuthenticator
#. Restart your JupyterHub so that new users see these changes::
sudo tljh-config reload
Confirm that the new authenticator works
========================================
#. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
#. Go to your JupyterHub URL.
#. You should see a Google login button like below:
.. image:: ../../images/auth/google/login_button.png
:alt: The Google authenticator login button.
#. After you log in with your Google credentials, you should be directed to the
Jupyter interface used in this JupyterHub.
#. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`.

33
docs/howto/auth/nativeauth.md Normal file
View File

@@ -0,0 +1,33 @@
(howto-auth-nativeauth)=
# Let users sign up with a username and password
The **Native Authenticator** lets users signup for creating a new username
and password.
When they signup, they won't be able to login until they are authorized by an
admin. Users that are characterized as admin have to signup as well, but they
will be authorized automatically.
## Enabling the authenticator
Enable the authenticator and reload config to apply the configuration:
```bash
sudo tljh-config set auth.type nativeauthenticator.NativeAuthenticator
sudo tljh-config reload
```
## Allowing all users to be authorized after signup
By default, all users created on signup don't have authorization to login.
If you wish to allow **any** user to access
the JupyterHub just after the signup, run the following command:
```bash
tljh-config set auth.NativeAuthenticator.open_signup true
tljh-config reload
```
## Optional features
More optional features are available on the `authenticator documentation <https://native-authenticator.readthedocs.io/en/latest/>`

40
docs/howto/auth/nativeauth.rst
View File

@@ -1,40 +0,0 @@
.. _howto/auth/nativeauth:
==============================================
Let users sign up with a username and password
==============================================
The **Native Authenticator** lets users signup for creating a new username
and password.
When they signup, they won't be able to login until they are authorized by an
admin. Users that are characterized as admin have to signup as well, but they
will be authorized automatically.
Enabling the authenticator
==========================
Enable the authenticator and reload config to apply the configuration:
.. code-block:: bash
sudo tljh-config set auth.type nativeauthenticator.NativeAuthenticator
sudo tljh-config reload
Allowing all users to be authorized after signup
================================================
By default, all users created on signup don't have authorization to login.
If you wish to allow **any** user to access
the JupyterHub just after the signup, run the following command:
.. code-block:: bash
tljh-config set auth.NativeAuthenticator.open_signup true
tljh-config reload
Optional features
=================
More optional features are available on the `authenticator documentation <https://native-authenticator.readthedocs.io/en/latest/>`

100
docs/howto/content/add-data.md Normal file
View File

@@ -0,0 +1,100 @@
(howto-content-add-data)=
# Adding data to the JupyterHub
This section covers how to add data to your JupyterHub either from the internet
or from your own machine. To learn how to **share data** that is already
on your JupyterHub, see [](/howto/content/share-data).
:::{note}
When you add data using the methods on this page, you will **only add it
to your user directory**. This is not a place that is accessible to others.
For information on sharing this data with users on the JupyterHub, see
[](/howto/content/share-data).
:::
## Adding data from your local machine
The easiest way to add data to your JupyterHub is to use the "Upload" user
interface. To do so, follow these steps:
1. First, navigate to the Jupyter Notebook interface home page. You can do this
by going to the URL `<my-hub-url>/user/<my-username>/tree`.
2. Click the "Upload" button to open the file chooser window.
```{image} ../../images/content/upload-button.png
:alt: The upload button in Jupyter.
```
3. Choose the file you wish to upload. You may select multiple files if you
wish.
4. Click "Upload" for each file that you wish to upload.
```{image} ../../images/content/file-upload-buttons.png
:alt: Multiple file upload buttons.
```
5. Wait for the progress bar to finish for each file. These files will now
be on your JupyterHub, your home user's home directory.
To learn how to **share** this data with new users on the JupyterHub,
see [](/howto/content/share-data).
## Downloading data from the command line
If the data of interest is on the internet, you may also use code in order
to download it to your JupyterHub. There are several ways of doing this, so
we'll cover the simplest approach using the unix tool `wget`.
1. Log in to your JupyterHub and open a terminal window.
```{image} ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
```
2. Use `wget` to download the file to your current directory in the terminal.
```bash
wget <MY-FILE-URL>
```
### Example: Downloading the [gapminder](https://www.gapminder.org/) dataset.
In this example we'll download the [gapminder](https://www.gapminder.org/)
dataset, which contains information about country GDP and live expectancy over
time. You can download it from your browser [at this link](https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip).
1. Log in to your JupyterHub and open a terminal window.
```{image} ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
```
2. Use `wget` to download the gapminder dataset to your current directory in
the terminal.
```bash
wget https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip
```
3. This is a **zip** file, so we'll need to download a unix tool called "unzip"
in order to unzip it.
```bash
sudo apt install unzip
```
4. Finally, unzip the file:
```bash
unzip python-novice-gapminder-data.zip
```
5. Confirm that your data was unzipped. It could be in a folder called `data/`.
To learn how to **share** this data with new users on the JupyterHub,
see [](/howto/content/share-data).
% TODO: Downloading data with the "download" module in Python? https://github.com/choldgraf/download

97
docs/howto/content/add-data.rst
View File

@@ -1,97 +0,0 @@
.. _howto/content/add-data:
=============================
Adding data to the JupyterHub
=============================
This section covers how to add data to your JupyterHub either from the internet
or from your own machine. To learn how to **share data** that is already
on your JupyterHub, see :ref:`howto/content/share-data`.
.. note::
When you add data using the methods on this page, you will **only add it
to your user directory**. This is not a place that is accessible to others.
For information on sharing this data with users on the JupyterHub, see
:ref:`howto/content/share-data`.
Adding data from your local machine
===================================
The easiest way to add data to your JupyterHub is to use the "Upload" user
interface. To do so, follow these steps:
#. First, navigate to the Jupyter Notebook interface home page. You can do this
by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
#. Click the "Upload" button to open the file chooser window.
.. image:: ../../images/content/upload-button.png
:alt: The upload button in Jupyter.
#. Choose the file you wish to upload. You may select multiple files if you
wish.
#. Click "Upload" for each file that you wish to upload.
.. image:: ../../images/content/file-upload-buttons.png
:alt: Multiple file upload buttons.
#. Wait for the progress bar to finish for each file. These files will now
be on your JupyterHub, your home user's home directory.
To learn how to **share** this data with new users on the JupyterHub,
see :ref:`howto/content/share-data`.
Downloading data from the command line
======================================
If the data of interest is on the internet, you may also use code in order
to download it to your JupyterHub. There are several ways of doing this, so
we'll cover the simplest approach using the unix tool ``wget``.
#. Log in to your JupyterHub and open a terminal window.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. Use ``wget`` to download the file to your current directory in the terminal.
.. code-block:: bash
wget <MY-FILE-URL>
Example: Downloading the `gapminder <https://www.gapminder.org/>`_ dataset.
---------------------------------------------------------------------------
In this example we'll download the `gapminder <https://www.gapminder.org/>`_
dataset, which contains information about country GDP and live expectancy over
time. You can download it from your browser `at this link <https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip>`_.
#. Log in to your JupyterHub and open a terminal window.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. Use ``wget`` to download the gapminder dataset to your current directory in
the terminal.
.. code-block:: bash
wget https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip
#. This is a **zip** file, so we'll need to download a unix tool called "unzip"
in order to unzip it.
.. code-block:: bash
sudo apt install unzip
#. Finally, unzip the file:
.. code-block:: bash
unzip python-novice-gapminder-data.zip
#. Confirm that your data was unzipped. It could be in a folder called ``data/``.
To learn how to **share** this data with new users on the JupyterHub,
see :ref:`howto/content/share-data`.
.. TODO: Downloading data with the "download" module in Python? https://github.com/choldgraf/download

41
docs/howto/content/nbgitpuller.rst → docs/howto/content/nbgitpuller.md
View File

@@ -1,11 +1,8 @@
.. _howto/content/nbgitpuller:
(howto-content-nbgitpuller)=
================================================
Distributing materials to users with nbgitpuller
================================================
# Distributing materials to users with nbgitpuller
Goal
====
## Goal
A very common need when using JupyterHub is to easily
distribute study materials / lab notebooks to students.
@@ -29,38 +26,34 @@ This tutorial will walk you through the process of creating a magic
nbgitpuller link that users of your JupyterHub can click to fetch the latest
version of materials from a git repo.
Pre-requisites
==============
## Pre-requisites
1. A JupyterHub set up with The Littlest JupyterHub
2. A git repository containing materials to distribute
Step 1: Generate nbgitpuller link
=================================
## Step 1: Generate nbgitpuller link
The quickest way to generate a link is to use `nbgitpuller.link
<https://jupyterhub.github.io/nbgitpuller/link.html>`_, but other options exist as described in the
`nbgitpuller project's documentation
<https://jupyterhub.github.io/nbgitpuller/use.html>`_.
The quickest way to generate a link is to use [nbgitpuller.link](https://jupyterhub.github.io/nbgitpuller/link.html), but other options exist as described in the
[nbgitpuller project's documentation](https://jupyterhub.github.io/nbgitpuller/use.html).
Step 2: Users click on the nbgitpuller link
===========================================
## Step 2: Users click on the nbgitpuller link
#. Send the link to your users in some way - email, slack, post a
shortened version (with `bit.ly <https://bit.ly>`_ maybe) on the wall, or
put it on your syllabus page (like `UC Berkeley's data8 does <http://data8.org/sp18/>`_).
1. Send the link to your users in some way - email, slack, post a
shortened version (with [bit.ly](https://bit.ly) maybe) on the wall, or
put it on your syllabus page (like [UC Berkeley's data8 does](http://data8.org/sp18/)).
Whatever works for you :)
#. When users click the link, they will be asked to log in to the hub
2. When users click the link, they will be asked to log in to the hub
if they have not already.
#. Users will see a progress bar as the git repository is fetched & any
3. Users will see a progress bar as the git repository is fetched & any
automatic merging required is performed.
.. image:: ../../images/nbgitpuller/pull-progress.png
:alt: Progress bar with git repository being pulled
```{image} ../../images/nbgitpuller/pull-progress.png
:alt: Progress bar with git repository being pulled
```
#. Users will now be redirected to the notebook specified in the URL!
4. Users will now be redirected to the notebook specified in the URL!
This workflow lets users land directly in the notebook you specified
without having to understand much about git or the JupyterHub interface.

137
docs/howto/content/share-data.md Normal file
View File

@@ -0,0 +1,137 @@
(howto-content-share-data)=
# Share data with your users
There are a few options for sharing data with your users, this page covers
a few useful patterns.
## Option 1: Distributing data with `nbgitpuller`
For small datasets, the simplest way to share data with your users is via
`nbgitpuller` links. In this case, users click on your link and the dataset
contained in the link's target repository is downloaded to the user's home
directory. Note that a copy of the dataset will be made for each user.
For information on creating and sharing `nbgitpuller` links, see
[](/howto/content/nbgitpuller).
## Option 2: Create a read-only shared folder for data
If your data is large or you don't want copies of it to exist, you can create
a read-only shared folder that users have access to. To do this, follow these
steps:
1. **Log** in to your JupyterHub as an **administrator user**.
2. **Create a terminal session** with your JupyterHub interface.
```{image} ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
```
3. **Create a folder** where your data will live. We recommend placing shared
data in `/srv`. The following command creates two folders (`/srv/data` and
`/srv/data/my_shared_data_folder`).
```bash
sudo mkdir -p /srv/data/my_shared_data_folder
```
4. **Download the data** into this folder. See [](/howto/content/add-data) for
details on how to do this.
5. All users now have read access to the data in this folder.
### Add a link to the shared folder in the user home directory
Optionally, you may also **create a symbolic link to the shared data folder**
that you created above in each **new user's** home directory.
To do this, you can use the server's **user skeleton directory** (`/etc/skel`).
Anything that is placed in this directory will also
show up in a new user's home directory.
To create a link to the shared folder in the user skeleton directory,
follow these steps:
1. `cd` into the skeleton directory:
```bash
cd /etc/skel
```
2. **Create a symbolic link** to the data folder
```bash
sudo ln -s /srv/data/my_shared_data_folder my_shared_data_folder
```
3. **Confirm that this worked** by logging in as a new user. You can do this
by opening a new "incognito" browser window and accessing your JupyterHub.
After you log in as a **new user**, the folder should appear in your new
user home directory.
From now on, when a new user account is created, their home directory will
have this symbolic link (and any other files in `/etc/skel`) in their home
directory. This will have **no effect on the directories of existing
users**.
## Option 3: Create a directory for users to share Notebooks and other files
You may want a place for users to share files with each other rather than
only having administrators share files with users (Option 2). In this
configuration, any user can put files into `/srv/scratch` that other users
can read. However, only the user that created the file can edit the file.
One way for users to share or "publish" Notebooks in a JupyterHub environment
is to create a shared directory. Any user can create files in the directory,
but only the creator may edit that file afterwards.
For instance, in a Hub with three users, User A develops a Notebook in their
`/home` directory. When it is ready to share, User A copies it to the
`shared` directory. At that time, User B and User C can see User A's
Notebook and run it themselves (or view it in a Dashboard layout
such as `voila` or `panel` if that is running in the Hub), but User B
and User C cannot edit the Notebook. Only User A can make changes.
1. **Log** in to your JupyterHub as an **administrator user**.
2. **Create a terminal session** with your JupyterHub interface.
```{image} ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
```
3. **Create a folder** where your data will live. We recommend placing shared
data in `/srv`. The following command creates a directory `/srv/scratch`
```bash
sudo mkdir -p /srv/scratch
```
4. **Change group ownership** of the new folder
```bash
sudo chown root:jupyterhub-users /srv/scratch
```
5. **Change default permissions to use group**. The default permissions for new
sub-directories uses the global umask (`drwxr-sr-x`), the `chmod g+s` tells
new files to use the default permissions for the group `jupyterhub-users`
(`rw-r--r--`)
```bash
sudo chmod 777 /srv/scratch
sudo chmod g+s /srv/scratch
```
6. **Create a symbolic link** to the scratch folder in users home directories
```bash
sudo ln -s /srv/scratch /etc/skel/scratch
```
:::{note}
The TLJH Plugin at <https://github.com/kafonek/tljh-shared-directory> installs `voila` and sets up the directories as specified above.
Include `--plugin git+https://github.com/kafonek/tljh-shared-directory` in your deployment startup script to install it.
:::

139
docs/howto/content/share-data.rst
View File

@@ -1,139 +0,0 @@
.. _howto/content/share-data:
==========================
Share data with your users
==========================
There are a few options for sharing data with your users, this page covers
a few useful patterns.
Option 1: Distributing data with `nbgitpuller`
==============================================
For small datasets, the simplest way to share data with your users is via
``nbgitpuller`` links. In this case, users click on your link and the dataset
contained in the link's target repository is downloaded to the user's home
directory. Note that a copy of the dataset will be made for each user.
For information on creating and sharing ``nbgitpuller`` links, see
:ref:`howto/content/nbgitpuller`.
Option 2: Create a read-only shared folder for data
===================================================
If your data is large or you don't want copies of it to exist, you can create
a read-only shared folder that users have access to. To do this, follow these
steps:
#. **Log** in to your JupyterHub as an **administrator user**.
#. **Create a terminal session** with your JupyterHub interface.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. **Create a folder** where your data will live. We recommend placing shared
data in ``/srv``. The following command creates two folders (``/srv/data`` and
``/srv/data/my_shared_data_folder``).
.. code-block:: bash
sudo mkdir -p /srv/data/my_shared_data_folder
#. **Download the data** into this folder. See :ref:`howto/content/add-data` for
details on how to do this.
#. All users now have read access to the data in this folder.
Add a link to the shared folder in the user home directory
----------------------------------------------------------
Optionally, you may also **create a symbolic link to the shared data folder**
that you created above in each **new user's** home directory.
To do this, you can use the server's **user skeleton directory** (``/etc/skel``).
Anything that is placed in this directory will also
show up in a new user's home directory.
To create a link to the shared folder in the user skeleton directory,
follow these steps:
#. ``cd`` into the skeleton directory:
.. code-block:: bash
cd /etc/skel
#. **Create a symbolic link** to the data folder
.. code-block:: bash
sudo ln -s /srv/data/my_shared_data_folder my_shared_data_folder
#. **Confirm that this worked** by logging in as a new user. You can do this
by opening a new "incognito" browser window and accessing your JupyterHub.
After you log in as a **new user**, the folder should appear in your new
user home directory.
From now on, when a new user account is created, their home directory will
have this symbolic link (and any other files in ``/etc/skel``) in their home
directory. This will have **no effect on the directories of existing
users**.
Option 3: Create a directory for users to share Notebooks and other files
=========================================================================
You may want a place for users to share files with each other rather than
only having administrators share files with users (Option 2). In this
configuration, any user can put files into ``/srv/scratch`` that other users
can read. However, only the user that created the file can edit the file.
One way for users to share or "publish" Notebooks in a JupyterHub environment
is to create a shared directory. Any user can create files in the directory,
but only the creator may edit that file afterwards.
For instance, in a Hub with three users, User A develops a Notebook in their
``/home`` directory. When it is ready to share, User A copies it to the
`shared` directory. At that time, User B and User C can see User A's
Notebook and run it themselves (or view it in a Dashboard layout
such as ``voila`` or ``panel`` if that is running in the Hub), but User B
and User C cannot edit the Notebook. Only User A can make changes.
#. **Log** in to your JupyterHub as an **administrator user**.
#. **Create a terminal session** with your JupyterHub interface.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. **Create a folder** where your data will live. We recommend placing shared
data in ``/srv``. The following command creates a directory ``/srv/scratch``
.. code-block:: bash
sudo mkdir -p /srv/scratch
#. **Change group ownership** of the new folder
.. code-block:: bash
sudo chown root:jupyterhub-users /srv/scratch
#. **Change default permissions to use group**. The default permissions for new
sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells
new files to use the default permissions for the group ``jupyterhub-users``
(``rw-r--r--``)
.. code-block:: bash
sudo chmod 777 /srv/scratch
sudo chmod g+s /srv/scratch
#. **Create a symbolic link** to the scratch folder in users home directories
.. code-block:: bash
sudo ln -s /srv/scratch /etc/skel/scratch
.. note::
The TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above.
Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script to install it.

56
docs/howto/env/notebook-interfaces.rst vendored
View File

@@ -1,56 +0,0 @@
.. _howto/env/notebook_interfaces:
=======================================
Change default User Interface for users
=======================================
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.
#. To launch **JupyterLab** when users log in, run the following in an admin console:
.. code-block:: yaml
sudo tljh-config set user_environment.default_app jupyterlab
#. Alternatively, to launch **nteract** when users log in, run the following in the admin console:
.. code-block:: yaml
sudo tljh-config set user_environment.default_app nteract
#. Apply the changes by restarting JupyterHub. This should not disrupt current users.
.. code-block:: yaml
sudo tljh-config reload hub
If this causes problems, check the :ref:`troubleshoot_logs_jupyterhub` for clues
on what went wrong.
Users might have to restart their servers from control panel to get the new interface.

10
docs/howto/env/server-resources.rst vendored
View File

@@ -1,10 +0,0 @@
.. _howto/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 :ref:`tljh-set-user-limits`. For information
on **resizing** the environment available to users *after* you've created your
JupyterHub, see :ref:`howto/admin/resize`.

209
docs/howto/env/user-environment.rst vendored
View File

@@ -1,209 +0,0 @@
.. _howto/env/user_environment:
==================================
Install conda, pip or apt packages
==================================
: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 rights <howto/admin/admin-users>` can install packages
easily.
.. _howto/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.
.. image:: ../../images/notebook/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``.
.. _howto/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.
.. image:: ../../images/notebook/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``.
.. _howto/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.
.. image:: ../../images/notebook/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 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:
.. 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
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 :ref:`installation guide <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:
.. code-block:: 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):
.. code-block:: bash
pip freeze > pip_pkgs.txt
3. Update all conda installed packages in the environment:
.. code-block:: bash
sudo PATH=${PATH} conda update --all
4. Update Python version:
.. code-block:: bash
sudo PATH=${PATH} conda install python=3.7
5. Install the pip packages previously saved:
.. code-block:: bash
pip install -r pip_pkgs.txt

67
docs/howto/index.md Normal file
View File

@@ -0,0 +1,67 @@
# How-To Guides
How-To guides answer the question 'How do I...?' for a lot of topics.
## Content and data
```{toctree}
:caption: Content and data
:titlesonly: true
content/nbgitpuller
content/add-data
content/share-data
```
## The user environment
```{toctree}
:caption: The user environment
:titlesonly: true
env/user-environment
env/notebook-interfaces
env/server-resources
```
## Authentication
We have a special set of How-To Guides on using various forms of authentication
with your JupyterHub. For more information on Authentication, see
[](/topic/authenticator-configuration)
```{toctree}
:titlesonly: true
auth/dummy
auth/github
auth/google
auth/awscognito
auth/firstuse
auth/nativeauth
```
## Administration and security
```{toctree}
:caption: Administration and security
:titlesonly: true
admin/admin-users
admin/resource-estimation
admin/resize
admin/nbresuse
admin/https
admin/enable-extensions
admin/systemd
```
## Cloud provider configuration
```{toctree}
:caption: Cloud provider configuration
:titlesonly: true
providers/digitalocean
providers/azure
```

68
docs/howto/index.rst
View File

@@ -1,68 +0,0 @@
How-To Guides
=============
How-To guides answer the question 'How do I...?' for a lot of topics.
Content and data
----------------
.. toctree::
:titlesonly:
:caption: Content and data
content/nbgitpuller
content/add-data
content/share-data
The user environment
--------------------
.. toctree::
:titlesonly:
:caption: The user environment
env/user-environment
env/notebook-interfaces
env/server-resources
Authentication
--------------
We have a special set of How-To Guides on using various forms of authentication
with your JupyterHub. For more information on Authentication, see
:ref:`topic/authenticator-configuration`
.. toctree::
:titlesonly:
auth/dummy
auth/github
auth/google
auth/awscognito
auth/firstuse
auth/nativeauth
Administration and security
---------------------------
.. toctree::
:titlesonly:
:caption: Administration and security
admin/admin-users
admin/resource-estimation
admin/resize
admin/nbresuse
admin/https
admin/enable-extensions
admin/systemd
Cloud provider configuration
----------------------------
.. toctree::
:titlesonly:
:caption: Cloud provider configuration
providers/digitalocean
providers/azure

38
docs/howto/providers/azure.md Normal file
View File

@@ -0,0 +1,38 @@
(howto-providers-azure)=
# Perform common Microsoft Azure configuration tasks
This page lists various common tasks you can perform on your
[Microsoft Azure virtual machine](https://azure.microsoft.com/services/virtual-machines/?WT.mc_id=TLJH-github-taallard).
(howto-providers-azure-resize)=
## Deleting or stopping your virtual machine
After you have finished using your TLJH you might wanto to either Stop or completely delete the Virtual Machine to avoid incurring in subsequent costs.
The difference between these two approaches is that **Stop** will keep the VM resources (e.g. storage and network) but will effectively stop any compute / runtime activities.
If you choose to delete the VM then all the resources associated with it will be wiped out.
To do either of this:
- Go to "Virtual Machines" on the left hand panel
- Click on your machine name
- Click on "Stop" to stop the machine temporarily, or "Delete" to delete it permanently.
> ```{image} ../../images/providers/azure/delete-vm.png
> :alt: Delete vm
> ```
:::{note}
It is important to mention that even if you stop the machine you will still be charged for the use of the data disk.
:::
If you no longer need any of your resources you can delete the entire resource group.
- Go to "Reosurce groups" on the left hand panel
- Click on your resource group
- Click on "Delete resource group" you will then be asked to confirm the operation. This operation will take between 5 and 10 minutes.

36
docs/howto/providers/azure.rst
View File

@@ -1,36 +0,0 @@
.. _howto/providers/azure:
==================================================
Perform common Microsoft Azure configuration tasks
==================================================
This page lists various common tasks you can perform on your
`Microsoft Azure virtual machine <https://azure.microsoft.com/services/virtual-machines/?WT.mc_id=TLJH-github-taallard>`_.
.. _howto/providers/azure/resize:
Deleting or stopping your virtual machine
===========================================
After you have finished using your TLJH you might wanto to either Stop or completely delete the Virtual Machine to avoid incurring in subsequent costs.
The difference between these two approaches is that **Stop** will keep the VM resources (e.g. storage and network) but will effectively stop any compute / runtime activities.
If you choose to delete the VM then all the resources associated with it will be wiped out.
To do either of this:
* Go to "Virtual Machines" on the left hand panel
* Click on your machine name
* Click on "Stop" to stop the machine temporarily, or "Delete" to delete it permanently.
.. image:: ../../images/providers/azure/delete-vm.png
:alt: Delete vm
.. note:: It is important to mention that even if you stop the machine you will still be charged for the use of the data disk.
If you no longer need any of your resources you can delete the entire resource group.
* Go to "Reosurce groups" on the left hand panel
* Click on your resource group
* Click on "Delete resource group" you will then be asked to confirm the operation. This operation will take between 5 and 10 minutes.

42
docs/howto/providers/digitalocean.md Normal file
View File

@@ -0,0 +1,42 @@
(howto-providers-digitalocean)=
# Perform common Digital Ocean configuration tasks
This page lists various common tasks you can perform on your
Digital Ocean virtual machine.
(howto-providers-digitalocean-resize)=
## Resizing your droplet
As you use your JupyterHub, you may find that you need more memory,
disk space, or CPUs. Digital Ocean servers can be resized in the
"Resize Droplet" panel. These instructions take you through the process.
1. First, click on the name of your newly-created
Droplet to enter its configuration page.
2. Next, **turn off your Droplet**. This allows DigitalOcean to make
modifications to your VM. This will shut down your JupyterHub (temporarily).
```{image} ../../images/providers/digitalocean/power-off.png
:alt: Power off your Droplet
:width: 200px
```
3. Once your Droplet has been turned off, click "Resize",
which will take you to a menu with options to resize your VM.
```{image} ../../images/providers/digitalocean/resize-droplet.png
:alt: Resize panel of digital ocean
```
4. Decide what kinds of resources you'd like to resize, then click on a new VM
type in the list below. Finally, click "Resize". This may take a few moments!
5. Once your Droplet is resized, **turn your Droplet back on**. This makes your JupyterHub
available to the world once again. This will take a few moments to complete.
Now that you've resized your Droplet, you may want to change the resources available
to your users. Further information on making more resources available to
users and verifying resource availability can be found in [](/howto/admin/resize).

43
docs/howto/providers/digitalocean.rst
View File

@@ -1,43 +0,0 @@
.. _howto/providers/digitalocean:
================================================
Perform common Digital Ocean configuration tasks
================================================
This page lists various common tasks you can perform on your
Digital Ocean virtual machine.
.. _howto/providers/digitalocean/resize:
Resizing your droplet
=====================
As you use your JupyterHub, you may find that you need more memory,
disk space, or CPUs. Digital Ocean servers can be resized in the
"Resize Droplet" panel. These instructions take you through the process.
#. First, click on the name of your newly-created
Droplet to enter its configuration page.
#. Next, **turn off your Droplet**. This allows DigitalOcean to make
modifications to your VM. This will shut down your JupyterHub (temporarily).
.. image:: ../../images/providers/digitalocean/power-off.png
:alt: Power off your Droplet
:width: 200px
#. Once your Droplet has been turned off, click "Resize",
which will take you to a menu with options to resize your VM.
.. image:: ../../images/providers/digitalocean/resize-droplet.png
:alt: Resize panel of digital ocean
#. Decide what kinds of resources you'd like to resize, then click on a new VM
type in the list below. Finally, click "Resize". This may take a few moments!
#. Once your Droplet is resized, **turn your Droplet back on**. This makes your JupyterHub
available to the world once again. This will take a few moments to complete.
Now that you've resized your Droplet, you may want to change the resources available
to your users. Further information on making more resources available to
users and verifying resource availability can be found in :ref:`howto/admin/resize`.

73
docs/index.rst → docs/index.md
View File

@@ -1,21 +1,16 @@
=======================
The Littlest JupyterHub
=======================
# The Littlest JupyterHub
A simple `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_ distribution for
A simple [JupyterHub](https://github.com/jupyterhub/jupyterhub) distribution for
a small (0-100) number of users on a single server. We recommend reading
:ref:`topic/whentouse` to determine if this is the right tool for you.
[](/topic/whentouse) to determine if this is the right tool for you.
Development Status
==================
## Development Status
This project is currently in **beta** state. Folks have been using installations
of TLJH for more than a year now to great success. While we try hard not to, we
might still make breaking changes that have no clear upgrade pathway.
Installation
============
## Installation
The Littlest JupyterHub (TLJH) can run on any server that is running **Debian 11** or **Ubuntu 20.04** or **22.04** on an amd64 or arm64 CPU architecture.
We aim to support 'stable' and Long-Term Support (LTS) versions.
@@ -27,58 +22,58 @@ We have a bunch of tutorials to get you started.
on it. These are **recommended** if you do not have much experience setting up
servers.
.. toctree::
:titlesonly:
:maxdepth: 2
```{toctree}
:maxdepth: 2
:titlesonly: true
install/index
install/index
```
Once you are ready to run your server for real,
it's a good idea to proceed directly to :doc:`howto/admin/https`.
it's a good idea to proceed directly to {doc}`howto/admin/https`.
How-To Guides
=============
## How-To Guides
How-To guides answer the question 'How do I...?' for a lot of topics.
.. toctree::
:maxdepth: 2
```{toctree}
:maxdepth: 2
howto/index
howto/index
```
Topic Guides
============
## Topic Guides
Topic guides provide in-depth explanations of specific topics.
.. toctree::
:titlesonly:
:maxdepth: 2
```{toctree}
:maxdepth: 2
:titlesonly: true
topic/index
topic/index
```
Troubleshooting
===============
## Troubleshooting
In time, all systems have issues that need to be debugged. Troubleshooting
guides help you find what is broken & hopefully fix it.
.. toctree::
:titlesonly:
:maxdepth: 2
```{toctree}
:maxdepth: 2
:titlesonly: true
troubleshooting/index
troubleshooting/index
```
Contributing
============
## Contributing
We want you to contribute to TLJH in the ways that are most useful
and exciting to you. This section contains documentation helpful
to people contributing in various ways.
.. toctree::
:titlesonly:
:maxdepth: 2
```{toctree}
:maxdepth: 2
:titlesonly: true
contributing/index
contributing/index
```

60
docs/install/add_packages.txt
View File

@@ -1,30 +1,30 @@
The **User Environment** is a conda environment that is shared by all users
in the JupyterHub. Libraries installed in this environment are immediately
available to all users. Admin users can install packages in this environment
with ``sudo -E``.
#. Log in as an admin user and open a Terminal in your Jupyter Notebook.
.. image:: ../images/notebook/new-terminal-button.png
:alt: New Terminal button under New menu
#. 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 gdal
The ``sudo -E`` is very important!
#. Install `there <https://pypi.org/project/there>`_ with ``pip``
.. code-block:: bash
sudo -E pip install there
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.
The **User Environment** is a conda environment that is shared by all users
in the JupyterHub. Libraries installed in this environment are immediately
available to all users. Admin users can install packages in this environment
with `sudo -E`.
1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
```{image} ../images/notebook/new-terminal-button.png
:alt: New Terminal button under New menu
```
2. Install [gdal](https://anaconda.org/conda-forge/gdal) from [conda-forge](https://conda-forge.org/).
```bash
sudo -E conda install -c conda-forge gdal
```
The `sudo -E` is very important!
3. Install [there](https://pypi.org/project/there) with `pip`
```bash
sudo -E pip install there
```
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.

82
docs/install/add_users.txt
View File

@@ -1,39 +1,43 @@
Most administration & configuration of the JupyterHub can be done from the
web UI directly. Let's add a few users who can log in!
#. Open the **Control Panel** by clicking the control panel button on the top
right of your JupyterHub.
.. image:: ../images/control-panel-button.png
:alt: Control panel button in notebook, top right
#. In the control panel, open the **Admin** link in the top left.
.. image:: ../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
#. Click the **Add Users** button.
.. image:: ../images/admin/add-users-button.png
:alt: Add Users button in the admin page
A **Add Users** dialog box opens up.
#. Type the names of users you want to add to this JupyterHub in the dialog box,
one per line.
.. image:: ../images/admin/add-users-dialog.png
:alt: Adding users with add users dialog
You can tick the **Admin** checkbox if you want to give admin rights to all
these users too.
#. Click the **Add Users** button in the dialog box. Your users are now added
to the JupyterHub! When they log in for the first time, they can set their
password - and use it to log in again in the future.
Congratulations, you now have a multi user JupyterHub that you can add arbitrary
users to!
Most administration & configuration of the JupyterHub can be done from the
web UI directly. Let's add a few users who can log in!
1. Open the **Control Panel** by clicking the control panel button on the top
right of your JupyterHub.
```{image} ../images/control-panel-button.png
:alt: Control panel button in notebook, top right
```
2. In the control panel, open the **Admin** link in the top left.
```{image} ../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
```
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
3. Click the **Add Users** button.
```{image} ../images/admin/add-users-button.png
:alt: Add Users button in the admin page
```
A **Add Users** dialog box opens up.
4. Type the names of users you want to add to this JupyterHub in the dialog box,
one per line.
```{image} ../images/admin/add-users-dialog.png
:alt: Adding users with add users dialog
```
You can tick the **Admin** checkbox if you want to give admin rights to all
these users too.
5. Click the **Add Users** button in the dialog box. Your users are now added
to the JupyterHub! When they log in for the first time, they can set their
password - and use it to log in again in the future.
Congratulations, you now have a multi user JupyterHub that you can add arbitrary
users to!

279
docs/install/amazon.md Normal file
View File

@@ -0,0 +1,279 @@
(install-amazon)=
# Installing on Amazon Web Services
## Goal
To have a JupyterHub with admin users and a user environment with conda / pip packages.
## Prerequisites
1. An Amazon Web Services account.
If asked to choose a default region, choose the one closest to the majority
of your users.
## Step 1: Installing The Littlest JupyterHub
Let's create the server on which we can run JupyterHub.
1. Go to [Amazon Web Services](https://aws.amazon.com/) and click the gold
button 'Sign In to the Console' in the upper right. Log in with your Amazon Web
Services account.
If you need to adjust your region from your default, there is a drop-down
menu between your name and the **Support** menu on the far right of the dark
navigation bar across the top of the window. Adjust the region to match the
closest one to the majority of your users.
2. On the screen listing all the available services, pick **EC2** under **Compute**
on the left side at the top of the first column.
```{image} ../images/providers/amazon/compute_services.png
:alt: Select EC2
```
This will take you to the **EC2 Management Console**.
3. From the navigation menu listing on the far left side of the **EC2 Management
Console**, choose **Instances** under the light gray **INSTANCES** sub-heading.
```{image} ../images/providers/amazon/instances_from_console.png
:alt: Select Instances from console
```
4. In the main window of the **EC2 Management Console**, towards the top left,
click on the bright blue **Launch Instance** button.
```{image} ../images/providers/amazon/launch_instance_button.png
:alt: Click launch instance
```
This will start the 'launch instance wizard' process. This lets you customize
the kind of server you want, the resources it will have and its name.
5. On the page **Step 1: Choose an Amazon Machine Image (AMI)** you are going
to pick the base image your remote server will have. The view will
default to the 'Quick-start' tab selected and just a few down the page, select
**Ubuntu Server 22.04 LTS (HVM), SSD Volume Type - ami-XXXXXXXXXXXXXXXXX**,
leaving `64-bit (x86)` toggled.
```{image} ../images/providers/amazon/select_ubuntu_18.png
:alt: Click Ubuntu server 22.04
```
The `ami` alpha-numeric at the end references the specific Amazon machine
image, ignore this as Amazon updates them routinely. The
**Ubuntu Server 22.04 LTS (HVM)** is the important part.
6. After selecting the AMI, you'll be at **Step 2: Choose an Instance Type**.
There will be a long listing of the types and numbers of CPUs that Amazon
offers. Select the one you want and then select the button
`Next: Configure Instance Details` in the lower right corner.
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
how much Memory / CPU your server needs.
We recommend you use a server with at least 2GB of RAM, such as a **t3.small**.
However, if you need to minimise costs you can use a server with **1GB** RAM such as a **t2.micro**, but performance will be limited.
You may wish to consult the listing [here](https://www.ec2instances.info/)
because it shows cost per hour. The **On Demand** price is the pertinent cost.
`GPU graphics` and `GPU compute` products are also available around half way down the page
7. Under **Step 3: Configure Instance Details**, scroll to the bottom of the page
and toggle the arrow next to **Advanced Details**. Scroll down to 'User data'. Copy
the text below, and paste it into the **User data** text box. Replace
`<admin-user-name>` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
configure it. **Remember to add your username**!
```bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
```
```{image} ../images/providers/amazon/script_in_user_data.png
:alt: Install JupyterHub with the script in the User data textbox
```
:::{note}
See [](/topic/installer-actions) for a detailed description and
[](/topic/customizing-installer) for other options that can be used.
:::
8. Under **Step 4: Add Storage**, you can change the **size** and **type of your
disk by adjusting the value in \*\*Size (GiB)** and selecting **Volume Type**.
```{image} ../images/providers/amazon/change_size_type.png
:alt: Selecting disk size and type
```
Check out [](/howto/admin/resource-estimation) to help pick
how much Disk space your server needs.
Hover over the encircled `i` next to **Volume Type** for an explanation of
each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is
recommended for most workloads. With `Provisioned IOPS SSD (io1)` being the
highest-performance SSD volume. Magnetic (standard) is a previous generation
volume and not suited for a hub for multi-users.
When finished, click **Next: Add Tags** in the bottom right corner.
9. Under **Step 5: Add Tags**, click **Add Tag** and enter **Name** under the
**Key** field. In the **Value** field in the **Name** row, give your new
server a memorable name that identifies what purpose this JupyterHub will be
used for.
```{image} ../images/providers/amazon/name_hub.png
:alt: Use tags to name the hub.
```
10. Under **Step 6: Configure Security Group**, you'll set the firewall rules
that control the traffic for your instance. Specifically you'll want to add
rules to allow both **HTTP Traffic** and **HTTPS Traffic**. For
advanced troubleshooting, it will be helpful to set rules so you can use
SSH to connect (port 22).
If you have never used your Amazon account before, you'll have to select
**Create a new security group**. You should give it a disitnguishing name
under **Security group name**
such as `ssh_web` for future reference. If you have, one from before you can
select it and adjust it to have the rules you need, if you prefer.
The rules will default to include `SSH`. Leave that there, and then click on
the **Add Rule** button. Under **Type** for the new rule, change the field
to **HTTP**. The other boxes will get filled in appropritely. Again, click on
the **Add Rule** button. This time under **Type** for the new rule, change
the field to **HTTPS**.
The warning is there to remind you this opens things up to some degree but
this is necessary in order to let your users connect. However, this warning
is a good reminder that you should monitor your server to insure it is
available for users who may need it.
```{image} ../images/providers/amazon/set_security_groups.png
:alt: Allow HTTP & HTTPS traffic to your server
```
11. When the security rules are set, click on the blue button in the bottom
right **Review and Launch**. This will give you a chance to review things
because very soon you'll be launching and start paying for any resources you
use.
Note that you'll see two HTTP listings and two HTTPS listings under
**Security Groups** even though you only made one for each. This is normal &
necessary to match both IPv4 & IPv6 types of IP addresses.
When you are happy, press the blue **Launch** button in the bottom right
corner to nearly conclude your journey through the instance launch wizard.
```{image} ../images/providers/amazon/finally_launch.png
:alt: Launch your server
```
12. In the dialog box that pops up as the last step before launching is
triggered, you need to choose what to do about an identifying key pair and
acknowledge your choice in order to proceed. If you already have a key pair you
can select to associate it with this instance, otherwise you need to
**Create a new key pair**. Choosing to `Proceed without a key pair` is not
recommended as you'll have no way to access your server via SSH if anything
goes wrong with the Jupyterhub and have no way to recover files via download.
Download and keep the key pair file unless you are associating one you already
have.
```{image} ../images/providers/amazon/create_key_pair.png
:alt: Associate key pair
```
13. With the key pair associated, click the **Launch instances** button to
start creating the server that'll run TLJH.
```{image} ../images/providers/amazon/launch_now.png
:alt: Trigger actual launch
```
14. Following the launch initiation, you'll be taken to a **Launch Status**
notification screen. You can see more information about the details if you
click on the alphanumeric link to the launching instance following the text,
"`The following instance launches have been initiated:`".
```{image} ../images/providers/amazon/launch_status_screen.png
:alt: Launch status notice
```
15. That link will take you back to the **EC2 Management Console** with settings
that will limit the view in the console to just that instance. (Delete the
filter in the search bar if you want to see any other instances you may
have.) At first the server will be starting up, and then when the
**Instance state** is green the server is running.
```{image} ../images/providers/amazon/running_server.png
:alt: Server is running.
```
If you already have instances running in your account, the screen will look
different if you disable that filter. But you want to pay attention to the
row with the name of the server you made.
16. In a few seconds your server will be created, and you can see the
**Public IP** used to access it in the panel at the bottom of the console.
If it isn't displayed, click on the row for that instance in the console. It
will look like a pattern similar to **12.30.230.127**.
```{image} ../images/providers/amazon/public_ip.png
:alt: public IP
```
17. The Littlest JupyterHub is now installing in the background on your new
server. It takes around 10 minutes for this installation to complete.
18. Check if the installation is complete by copying the **Public IP**
of your server, and trying to access it from within a browser. If it has been
10 minutes, paste the public IP into the URL bar of your browser and hit
return to try to connect.
Accessing the JupyterHub will fail until the installation is complete,
so be patient. The next step below this one shows the login window you are
expecting to see when trying the URL and things work.
While waiting until the appropriate time to try, another way to check if
things are churning away, is to open the **System Log**. To do this, go to
the **EC2 Management Console** & highlight the instance by clicking on that
row and then right-click **Monitor and troubleshoot** > **Get system log**.
19. When the Jupyterhub creation process finishes and the hub is ready to show
the login, the **System Log** should look similar to the image below. Scroll to
the bottom of your output from the previous step.
Note the line **Starting TLJH installer**, you may also see **Started jupyterhub.service**
```{image} ../images/providers/amazon/completed_system_log.png
:alt: Completed system log
```
20. When the installation is complete, it should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
21. Login using the **admin user name** you used in step 7, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
22. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```

269
docs/install/amazon.rst
View File

@@ -1,269 +0,0 @@
.. _install/amazon:
=================================
Installing on Amazon Web Services
=================================
Goal
====
To have a JupyterHub with admin users and a user environment with conda / pip packages.
Prerequisites
=============
#. An Amazon Web Services account.
If asked to choose a default region, choose the one closest to the majority
of your users.
Step 1: Installing The Littlest JupyterHub
==========================================
Let's create the server on which we can run JupyterHub.
#. Go to `Amazon Web Services <https://aws.amazon.com/>`_ and click the gold
button 'Sign In to the Console' in the upper right. Log in with your Amazon Web
Services account.
If you need to adjust your region from your default, there is a drop-down
menu between your name and the **Support** menu on the far right of the dark
navigation bar across the top of the window. Adjust the region to match the
closest one to the majority of your users.
#. On the screen listing all the available services, pick **EC2** under **Compute**
on the left side at the top of the first column.
.. image:: ../images/providers/amazon/compute_services.png
:alt: Select EC2
This will take you to the **EC2 Management Console**.
#. From the navigation menu listing on the far left side of the **EC2 Management
Console**, choose **Instances** under the light gray **INSTANCES** sub-heading.
.. image:: ../images/providers/amazon/instances_from_console.png
:alt: Select Instances from console
#. In the main window of the **EC2 Management Console**, towards the top left,
click on the bright blue **Launch Instance** button.
.. image:: ../images/providers/amazon/launch_instance_button.png
:alt: Click launch instance
This will start the 'launch instance wizard' process. This lets you customize
the kind of server you want, the resources it will have and its name.
#. On the page **Step 1: Choose an Amazon Machine Image (AMI)** you are going
to pick the base image your remote server will have. The view will
default to the 'Quick-start' tab selected and just a few down the page, select
**Ubuntu Server 22.04 LTS (HVM), SSD Volume Type - ami-XXXXXXXXXXXXXXXXX**,
leaving `64-bit (x86)` toggled.
.. image:: ../images/providers/amazon/select_ubuntu_18.png
:alt: Click Ubuntu server 22.04
The `ami` alpha-numeric at the end references the specific Amazon machine
image, ignore this as Amazon updates them routinely. The
**Ubuntu Server 22.04 LTS (HVM)** is the important part.
#. After selecting the AMI, you'll be at **Step 2: Choose an Instance Type**.
There will be a long listing of the types and numbers of CPUs that Amazon
offers. Select the one you want and then select the button
`Next: Configure Instance Details` in the lower right corner.
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
how much Memory / CPU your server needs.
We recommend you use a server with at least 2GB of RAM, such as a **t3.small**.
However, if you need to minimise costs you can use a server with **1GB** RAM such as a **t2.micro**, but performance will be limited.
You may wish to consult the listing `here <https://www.ec2instances.info/>`_
because it shows cost per hour. The **On Demand** price is the pertinent cost.
``GPU graphics`` and ``GPU compute`` products are also available around half way down the page
#. Under **Step 3: Configure Instance Details**, scroll to the bottom of the page
and toggle the arrow next to **Advanced Details**. Scroll down to 'User data'. Copy
the text below, and paste it into the **User data** text box. Replace
``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
configure it. **Remember to add your username**!
.. code-block:: bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
.. image:: ../images/providers/amazon/script_in_user_data.png
:alt: Install JupyterHub with the script in the User data textbox
.. note::
See :ref:`topic/installer-actions` for a detailed description and
:ref:`topic/customizing-installer` for other options that can be used.
#. Under **Step 4: Add Storage**, you can change the **size** and **type of your
disk by adjusting the value in **Size (GiB)** and selecting **Volume Type**.
.. image:: ../images/providers/amazon/change_size_type.png
:alt: Selecting disk size and type
Check out :ref:`howto/admin/resource-estimation` to help pick
how much Disk space your server needs.
Hover over the encircled `i` next to **Volume Type** for an explanation of
each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is
recommended for most workloads. With `Provisioned IOPS SSD (io1)` being the
highest-performance SSD volume. Magnetic (standard) is a previous generation
volume and not suited for a hub for multi-users.
When finished, click **Next: Add Tags** in the bottom right corner.
#. Under **Step 5: Add Tags**, click **Add Tag** and enter **Name** under the
**Key** field. In the **Value** field in the **Name** row, give your new
server a memorable name that identifies what purpose this JupyterHub will be
used for.
.. image:: ../images/providers/amazon/name_hub.png
:alt: Use tags to name the hub.
#. Under **Step 6: Configure Security Group**, you'll set the firewall rules
that control the traffic for your instance. Specifically you'll want to add
rules to allow both **HTTP Traffic** and **HTTPS Traffic**. For
advanced troubleshooting, it will be helpful to set rules so you can use
SSH to connect (port 22).
If you have never used your Amazon account before, you'll have to select
**Create a new security group**. You should give it a disitnguishing name
under **Security group name**
such as `ssh_web` for future reference. If you have, one from before you can
select it and adjust it to have the rules you need, if you prefer.
The rules will default to include `SSH`. Leave that there, and then click on
the **Add Rule** button. Under **Type** for the new rule, change the field
to **HTTP**. The other boxes will get filled in appropritely. Again, click on
the **Add Rule** button. This time under **Type** for the new rule, change
the field to **HTTPS**.
The warning is there to remind you this opens things up to some degree but
this is necessary in order to let your users connect. However, this warning
is a good reminder that you should monitor your server to insure it is
available for users who may need it.
.. image:: ../images/providers/amazon/set_security_groups.png
:alt: Allow HTTP & HTTPS traffic to your server
#. When the security rules are set, click on the blue button in the bottom
right **Review and Launch**. This will give you a chance to review things
because very soon you'll be launching and start paying for any resources you
use.
Note that you'll see two HTTP listings and two HTTPS listings under
**Security Groups** even though you only made one for each. This is normal &
necessary to match both IPv4 & IPv6 types of IP addresses.
When you are happy, press the blue **Launch** button in the bottom right
corner to nearly conclude your journey through the instance launch wizard.
.. image:: ../images/providers/amazon/finally_launch.png
:alt: Launch your server
#. In the dialog box that pops up as the last step before launching is
triggered, you need to choose what to do about an identifying key pair and
acknowledge your choice in order to proceed. If you already have a key pair you
can select to associate it with this instance, otherwise you need to
**Create a new key pair**. Choosing to `Proceed without a key pair` is not
recommended as you'll have no way to access your server via SSH if anything
goes wrong with the Jupyterhub and have no way to recover files via download.
Download and keep the key pair file unless you are associating one you already
have.
.. image:: ../images/providers/amazon/create_key_pair.png
:alt: Associate key pair
#. With the key pair associated, click the **Launch instances** button to
start creating the server that'll run TLJH.
.. image:: ../images/providers/amazon/launch_now.png
:alt: Trigger actual launch
#. Following the launch initiation, you'll be taken to a **Launch Status**
notification screen. You can see more information about the details if you
click on the alphanumeric link to the launching instance following the text,
"`The following instance launches have been initiated:`".
.. image:: ../images/providers/amazon/launch_status_screen.png
:alt: Launch status notice
#. That link will take you back to the **EC2 Management Console** with settings
that will limit the view in the console to just that instance. (Delete the
filter in the search bar if you want to see any other instances you may
have.) At first the server will be starting up, and then when the
**Instance state** is green the server is running.
.. image:: ../images/providers/amazon/running_server.png
:alt: Server is running.
If you already have instances running in your account, the screen will look
different if you disable that filter. But you want to pay attention to the
row with the name of the server you made.
#. In a few seconds your server will be created, and you can see the
**Public IP** used to access it in the panel at the bottom of the console.
If it isn't displayed, click on the row for that instance in the console. It
will look like a pattern similar to **12.30.230.127**.
.. image:: ../images/providers/amazon/public_ip.png
:alt: public IP
#. The Littlest JupyterHub is now installing in the background on your new
server. It takes around 10 minutes for this installation to complete.
#. Check if the installation is complete by copying the **Public IP**
of your server, and trying to access it from within a browser. If it has been
10 minutes, paste the public IP into the URL bar of your browser and hit
return to try to connect.
Accessing the JupyterHub will fail until the installation is complete,
so be patient. The next step below this one shows the login window you are
expecting to see when trying the URL and things work.
While waiting until the appropriate time to try, another way to check if
things are churning away, is to open the **System Log**. To do this, go to
the **EC2 Management Console** & highlight the instance by clicking on that
row and then right-click **Monitor and troubleshoot** > **Get system log**.
#. When the Jupyterhub creation process finishes and the hub is ready to show
the login, the **System Log** should look similar to the image below. Scroll to
the bottom of your output from the previous step.
Note the line **Starting TLJH installer**, you may also see **Started jupyterhub.service**
.. image:: ../images/providers/amazon/completed_system_log.png
:alt: Completed system log
#. When the installation is complete, it should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 7, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
#. Congratulations, you have a running working JupyterHub!
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt

226
docs/install/azure.md Normal file
View File

@@ -0,0 +1,226 @@
(install-azure)=
# Installing on Azure
## Goal
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want to be installed running on
[Microsoft Azure](https://azure.microsoft.com).
This tutorial leads you step-by-step for you to manually deploy your own JupyterHub on Azure cloud.
:::{note}
✨ The `Deploy to Azure button` project allows you to deploy your own JupyterHub with minimal manual configuration steps. The deploy to Azure button allows you to have a vanilla configuration in just one-click and by assigning some variables.
Check it out at [https://github.com/trallard/TLJH-azure-button](https://github.com/trallard/TLJH-azure-button).
:::
## Prerequisites
- A Microsoft Azure account.
- To get started you can get a free account which includes 150 dollars worth of Azure credits ([get a free account here](https://azure.microsoft.com/en-us/free//?wt.mc_id=TLJH-github-taallard))
These instructions cover how to set up a Virtual Machine
on Microsoft Azure. For subsequent information about creating
your JupyterHub and configuring it, see [The Littlest JupyterHub guide](https://the-littlest-jupyterhub.readthedocs.io/en/latest/).
## Step 1: Installing The Littlest JupyterHub
We start by creating the Virtual Machine in which we can run TLJH (The Littlest JupyterHub).
1. Go to [Azure portal](https://portal.azure.com/) and login with your Azure account.
2. Expand the left-hand panel by clicking on the ">>" button on the top left corner of your dashboard. Find the Virtual Machines tab and click on it.
```{image} ../images/providers/azure/azure-vms.png
:alt: Virtual machines on Azure portal
```
3. Click **+ add** to create a new Virtual Machine
```{image} ../images/providers/azure/add-vm.png
:alt: Add a new virtual machine
```
4. Select **Create VM from Marketplace** in the next screen.
A new screen with all the options for Virtual Machines in Azure will displayed.
```{image} ../images/providers/azure/create-vm.png
:alt: Create VM from the marketplace
```
5. **Choose an Ubuntu server for your VM**:
- Click `Ubuntu Server 22.04 LTS.`
- Make sure `Resource Manager` is selected in the next screen and click **Create**
```{image} ../images/providers/azure/ubuntu-vm.png
:alt: Ubuntu VM
```
6. Customise the Virtual Machine basics:
- **Subscription**. Choose the "Free Trial" if this is what you're using. Otherwise, choose a different plan. This is the billing account that will be charged.
- **Resource group**. Resource groups let you keep your Azure tools/resources together in an availability region (e.g. WestEurope). If you already have one you'd like to use it select that resource.
:::{note}
If you have never created a Resource Group, click on **Create new**
:::
```{image} ../images/providers/azure/new-rg.png
:alt: Create a new resource group
```
- **Name**. Use a descriptive name for your virtual machine (note that you cannot use spaces or special characters).
- **Region**. Choose a location near where you expect your users to be located.
- **Availability options**. Choose "No infrastructure redundancy required".
- **Image**. Make sure "Ubuntu Server 22.04 LTS" is selected (from the previous step).
- **Authentication type**. Change authentication type to "password".
- **Username**. Choose a memorable username, this will be your "root" user, and you'll need it later on.
- **Password**. Type in a password, this will be used later for admin access so make sure it is something memorable.
```{image} ../images/providers/azure/password-vm.png
:alt: Add password to VM
```
- **Login with Azure Active Directory**. Choose "Off" (usually the default)
- **Inbound port rules**. Leave the defaults for now, and we will update these later on in the Network configuration step.
7. Before clicking on "Next" we need to select the RAM size for the image.
- For this we need to make sure we have enough RAM to accommodate your users. For example, if each user needs 2GB of RAM, and you have 10 total users, you need at least 20GB of RAM on the machine. It's also good to have a few GB of "buffer" RAM beyond what you think you'll need.
- Click on **Change size** (see image below)
```{image} ../images/providers/azure/size-vm.png
:alt: Choose vm size
```
:::{note}
For more information about estimating memory, CPU and disk needs check [The memory section in the TLJH documentation](https://tljh.jupyter.org/en/latest/howto/admin/resource-estimation.html)
:::
- Select a suitable image (to check available images and prices in your region [click on this link](https://azuremarketplace.microsoft.com/en-gb/marketplace/apps/Canonical.UbuntuServer?tab=PlansAndPrice/?wt.mc_id=TLJH-github-taallard)).
8. Disks (Storage):
- **Disk options**: select the OS disk type there are options for SDD and HDD. **SSD persistent disk** gives you a faster but more expensive disk than HDD.
- **Data disk**. Click on create and attach a new disk. Select an appropriate type and size and click ok.
- Click "Next".
```{image} ../images/providers/azure/create-disk.png
:alt: Create and attach disk
```
```{image} ../images/providers/azure/disk-vm.png
:alt: Choose a disk size
```
9. Networking
- **Virtual network**. Leave the default values selected.
- **Subnet**. Leave the default values selected.
- **Public IP address**.Leave the default values selected. This will make your server accessible from a browser.
- **Network Security Group**. Choose "Basic"
- **Public inbound ports**. Check **HTTP**, **HTTPS**, and **SSH**.
```{image} ../images/providers/azure/networking-vm.png
:alt: Choose networking ports
```
10. Management
- Monitoring
- **Boot diagnostics**. Choose "On".
- **OS guest diagnostics**. Choose "Off".
- **Diagnostics storage account**. Leave as the default.
- Auto-Shutdown
- **Enable auto-shutdown**. Choose "Off".
- Backup
- **Backup**. Choose "Off".
- System assigned managed identity. Select "Off".
```{image} ../images/providers/azure/backup-vm.png
:alt: Choose VM Backup
```
11. Advanced settings
- **Extensions**. Make sure there are no extensions listed
- **Cloud init**. We are going to use this section to install TLJH directly into our Virtual Machine.
Copy the code snippet below:
```bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
```
where the `username` is the root username you chose for your Virtual Machine.
```{image} ../images/providers/azure/cloudinit-vm.png
:alt: Install TLJH
```
:::{note}
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
[](/topic/customizing-installer) documents other options that can be passed to the installer.
:::
12. Check the summary and confirm the creation of your Virtual Machine.
13. Check that the creation of your Virtual Machine worked.
- Wait for the virtual machine to be created. This might take about 5-10 minutes.
- After completion, you should see a similar screen to the one below:
```{image} ../images/providers/azure/deployed-vm.png
:alt: Deployed VM
```
14. Note that the Littlest JupyterHub should be installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
15. Click on the **Go to resource button**
```{image} ../images/providers/azure/goto-vm.png
:alt: Go to VM
```
16. Check if the installation is completed by **copying** the **Public IP address** of your virtual machine, and trying to access it with a browser.
```{image} ../images/providers/azure/ip-vm.png
:alt: Public IP address
```
Note that accessing the JupyterHub will fail until the installation is complete, so be patient.
17. When the installation is complete, it should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
18. Login using the **admin user name** you used in step 6, and a password. Use a strong password & note it down somewhere, since this will be the password for the admin user account from now on.
19. Congratulations, you have a running working JupyterHub! 🎉
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```

192
docs/install/azure.rst
View File

@@ -1,192 +0,0 @@
.. _install/azure:
====================
Installing on Azure
====================
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want to be installed running on
`Microsoft Azure <https://azure.microsoft.com>`_.
This tutorial leads you step-by-step for you to manually deploy your own JupyterHub on Azure cloud.
.. note:: ✨ The ``Deploy to Azure button`` project allows you to deploy your own JupyterHub with minimal manual configuration steps. The deploy to Azure button allows you to have a vanilla configuration in just one-click and by assigning some variables.
Check it out at `https://github.com/trallard/TLJH-azure-button <https://github.com/trallard/TLJH-azure-button>`_.
Prerequisites
==============
* A Microsoft Azure account.
* To get started you can get a free account which includes 150 dollars worth of Azure credits (`get a free account here <https://azure.microsoft.com/en-us/free//?wt.mc_id=TLJH-github-taallard>`_)
These instructions cover how to set up a Virtual Machine
on Microsoft Azure. For subsequent information about creating
your JupyterHub and configuring it, see `The Littlest JupyterHub guide <https://the-littlest-jupyterhub.readthedocs.io/en/latest/>`_.
Step 1: Installing The Littlest JupyterHub
==========================================
We start by creating the Virtual Machine in which we can run TLJH (The Littlest JupyterHub).
#. Go to `Azure portal <https://portal.azure.com/>`_ and login with your Azure account.
#. Expand the left-hand panel by clicking on the ">>" button on the top left corner of your dashboard. Find the Virtual Machines tab and click on it.
.. image:: ../images/providers/azure/azure-vms.png
:alt: Virtual machines on Azure portal
#. Click **+ add** to create a new Virtual Machine
.. image:: ../images/providers/azure/add-vm.png
:alt: Add a new virtual machine
#. Select **Create VM from Marketplace** in the next screen.
A new screen with all the options for Virtual Machines in Azure will displayed.
.. image:: ../images/providers/azure/create-vm.png
:alt: Create VM from the marketplace
#. **Choose an Ubuntu server for your VM**:
* Click `Ubuntu Server 22.04 LTS.`
* Make sure `Resource Manager` is selected in the next screen and click **Create**
.. image:: ../images/providers/azure/ubuntu-vm.png
:alt: Ubuntu VM
#. Customise the Virtual Machine basics:
* **Subscription**. Choose the "Free Trial" if this is what you're using. Otherwise, choose a different plan. This is the billing account that will be charged.
* **Resource group**. Resource groups let you keep your Azure tools/resources together in an availability region (e.g. WestEurope). If you already have one you'd like to use it select that resource.
.. note:: If you have never created a Resource Group, click on **Create new**
.. image:: ../images/providers/azure/new-rg.png
:alt: Create a new resource group
* **Name**. Use a descriptive name for your virtual machine (note that you cannot use spaces or special characters).
* **Region**. Choose a location near where you expect your users to be located.
* **Availability options**. Choose "No infrastructure redundancy required".
* **Image**. Make sure "Ubuntu Server 22.04 LTS" is selected (from the previous step).
* **Authentication type**. Change authentication type to "password".
* **Username**. Choose a memorable username, this will be your "root" user, and you'll need it later on.
* **Password**. Type in a password, this will be used later for admin access so make sure it is something memorable.
.. image:: ../images/providers/azure/password-vm.png
:alt: Add password to VM
* **Login with Azure Active Directory**. Choose "Off" (usually the default)
* **Inbound port rules**. Leave the defaults for now, and we will update these later on in the Network configuration step.
#. Before clicking on "Next" we need to select the RAM size for the image.
* For this we need to make sure we have enough RAM to accommodate your users. For example, if each user needs 2GB of RAM, and you have 10 total users, you need at least 20GB of RAM on the machine. It's also good to have a few GB of "buffer" RAM beyond what you think you'll need.
* Click on **Change size** (see image below)
.. image:: ../images/providers/azure/size-vm.png
:alt: Choose vm size
.. note:: For more information about estimating memory, CPU and disk needs check `The memory section in the TLJH documentation <https://tljh.jupyter.org/en/latest/howto/admin/resource-estimation.html>`_
* Select a suitable image (to check available images and prices in your region `click on this link <https://azuremarketplace.microsoft.com/en-gb/marketplace/apps/Canonical.UbuntuServer?tab=PlansAndPrice/?wt.mc_id=TLJH-github-taallard>`_).
#. Disks (Storage):
* **Disk options**: select the OS disk type there are options for SDD and HDD. **SSD persistent disk** gives you a faster but more expensive disk than HDD.
* **Data disk**. Click on create and attach a new disk. Select an appropriate type and size and click ok.
* Click "Next".
.. image:: ../images/providers/azure/create-disk.png
:alt: Create and attach disk
.. image:: ../images/providers/azure/disk-vm.png
:alt: Choose a disk size
#. Networking
* **Virtual network**. Leave the default values selected.
* **Subnet**. Leave the default values selected.
* **Public IP address**.Leave the default values selected. This will make your server accessible from a browser.
* **Network Security Group**. Choose "Basic"
* **Public inbound ports**. Check **HTTP**, **HTTPS**, and **SSH**.
.. image:: ../images/providers/azure/networking-vm.png
:alt: Choose networking ports
#. Management
* Monitoring
* **Boot diagnostics**. Choose "On".
* **OS guest diagnostics**. Choose "Off".
* **Diagnostics storage account**. Leave as the default.
* Auto-Shutdown
* **Enable auto-shutdown**. Choose "Off".
* Backup
* **Backup**. Choose "Off".
* System assigned managed identity Select "Off"
.. image:: ../images/providers/azure/backup-vm.png
:alt: Choose VM Backup
#. Advanced settings
* **Extensions**. Make sure there are no extensions listed
* **Cloud init**. We are going to use this section to install TLJH directly into our Virtual Machine.
Copy the code snippet below:
.. code:: bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
where the ``username`` is the root username you chose for your Virtual Machine.
.. image:: ../images/providers/azure/cloudinit-vm.png
:alt: Install TLJH
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
#. Check the summary and confirm the creation of your Virtual Machine.
#. Check that the creation of your Virtual Machine worked.
* Wait for the virtual machine to be created. This might take about 5-10 minutes.
* After completion, you should see a similar screen to the one below:
.. image:: ../images/providers/azure/deployed-vm.png
:alt: Deployed VM
#. Note that the Littlest JupyterHub should be installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
#. Click on the **Go to resource button**
.. image:: ../images/providers/azure/goto-vm.png
:alt: Go to VM
#. Check if the installation is completed by **copying** the **Public IP address** of your virtual machine, and trying to access it with a browser.
.. image:: ../images/providers/azure/ip-vm.png
:alt: Public IP address
Note that accessing the JupyterHub will fail until the installation is complete, so be patient.
#. When the installation is complete, it should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 6, and a password. Use a strong password & note it down somewhere, since this will be the password for the admin user account from now on.
#. Congratulations, you have a running working JupyterHub! 🎉
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt

95
docs/install/custom-server.md Normal file
View File

@@ -0,0 +1,95 @@
(install-custom)=
# Installing on your own server
Follow this guide if your cloud provider doesn't have a direct tutorial, or
you are setting this up on a bare metal server.
:::{warning}
Do **not** install TLJH directly on your laptop or personal computer!
It will most likely open up exploitable security holes when run directly
on your personal computer.
:::
:::{note}
Running TLJH _inside_ a docker container is not supported, since we depend
on systemd. If you want to run TLJH locally for development, see
[](/contributing/dev-setup).
:::
## Goal
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
a server you have access to.
## Pre-requisites
1. Some familiarity with the command line.
2. A server running Ubuntu 20.04+ where you have root access (Ubuntu 22.04 LTS recommended).
3. At least **1GB** of RAM on your server.
4. Ability to `ssh` into the server & run commands from the prompt.
5. An **IP address** where the server can be reached from the browsers of your target audience.
If you run into issues, look at the specific [troubleshooting guide](/troubleshooting/providers/custom)
for custom server installations.
## Step 1: Installing The Littlest JupyterHub
1. Using a terminal program, SSH into your server. This should give you a prompt where you can
type commands.
2. Make sure you have `python3`, `python3-dev`, `curl` and `git` installed.
```
sudo apt install python3 python3-dev git curl
```
3. Copy the text below, and paste it into the terminal. Replace
`<admin-user-name>` with the name of the first **admin user** for this
JupyterHub. Choose any name you like (don't forget to remove the brackets!).
This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
```bash
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>
```
:::{note}
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
[](/topic/customizing-installer) documents other options that can be passed to the installer.
:::
4. Press `Enter` to start the installation process. This will take 5-10 minutes,
and will say `Done!` when the installation process is complete.
5. Copy the **Public IP** of your server, and try accessing `http://<public-ip>` from
your browser. If everything went well, this should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
6. Login using the **admin user name** you used in step 3. You can choose any
password that you wish. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
7. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```
## Step 4: Setup HTTPS
Once you are ready to run your server for real, and have a domain, it's a good
idea to proceed directly to [](/howto/admin/https).

99
docs/install/custom-server.rst
View File

@@ -1,99 +0,0 @@
.. _install/custom:
=============================
Installing on your own server
=============================
Follow this guide if your cloud provider doesn't have a direct tutorial, or
you are setting this up on a bare metal server.
.. warning::
Do **not** install TLJH directly on your laptop or personal computer!
It will most likely open up exploitable security holes when run directly
on your personal computer.
.. note::
Running TLJH *inside* a docker container is not supported, since we depend
on systemd. If you want to run TLJH locally for development, see
:ref:`contributing/dev-setup`.
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
a server you have access to.
Pre-requisites
==============
#. Some familiarity with the command line.
#. A server running Ubuntu 20.04+ where you have root access (Ubuntu 22.04 LTS recommended).
#. At least **1GB** of RAM on your server.
#. Ability to ``ssh`` into the server & run commands from the prompt.
#. An **IP address** where the server can be reached from the browsers of your target audience.
If you run into issues, look at the specific :ref:`troubleshooting guide <troubleshooting/providers/custom>`
for custom server installations.
Step 1: Installing The Littlest JupyterHub
==========================================
#. Using a terminal program, SSH into your server. This should give you a prompt where you can
type commands.
#. Make sure you have ``python3``, ``python3-dev``, ``curl`` and ``git`` installed.
.. code::
sudo apt install python3 python3-dev git curl
#. Copy the text below, and paste it into the terminal. Replace
``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. Choose any name you like (don't forget to remove the brackets!).
This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
#. Press ``Enter`` to start the installation process. This will take 5-10 minutes,
and will say ``Done!`` when the installation process is complete.
#. Copy the **Public IP** of your server, and try accessing ``http://<public-ip>`` from
your browser. If everything went well, this should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 3. You can choose any
password that you wish. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
#. Congratulations, you have a running working JupyterHub!
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt
Step 4: Setup HTTPS
===================
Once you are ready to run your server for real, and have a domain, it's a good
idea to proceed directly to :ref:`howto/admin/https`.

123
docs/install/digitalocean.md Normal file
View File

@@ -0,0 +1,123 @@
(insatll-digitalocean)=
# Installing on Digital Ocean
## Goal
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
[DigitalOcean](https://digitalocean.com).
## Pre-requisites
1. A DigitalOcean account with a payment method attached.
## Step 1: Installing The Littlest JupyterHub
Let's create the server on which we can run JupyterHub.
1. Log in to [DigitalOcean](https://digitalocean.com). You might need to
attach a credit card or other payment method to your account before you
can proceed with the tutorial.
2. Click the **Create** button on the top right, and select **Droplets** from
the dropdown menu. DigitalOcean calls servers **droplets**.
```{image} ../images/providers/digitalocean/create-menu.png
:alt: Dropdown menu on clicking 'create' in top right corner
```
This takes you to a page titled **Create Droplets** that lets you configure
your server.
3. Under **Choose an image**, select **22.04 x64** under **Ubuntu**.
```{image} ../images/providers/digitalocean/select-image.png
:alt: Select 22.04 x64 image under Ubuntu
```
4. Under **Choose a size**, select the size of the server you want. The default
(4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server
later if you need.
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
how much Memory, CPU & disk space your server needs.
5. Scroll down to **Select additional options**, and select **User data**.
```{image} ../images/providers/digitalocean/additional-options.png
:alt: Turn on User Data in additional options
```
This opens up a textbox where you can enter a script that will be run
when the server is created. We will use this to set up The Littlest JupyterHub
on this server.
6. Copy the text below, and paste it into the user data text box. Replace
`<admin-user-name>` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
```bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
```
:::{note}
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
[](/topic/customizing-installer) documents other options that can be passed to the installer.
:::
7. Under the **Finalize and create** section, enter a `hostname` that descriptively
identifies this server for you.
```{image} ../images/providers/digitalocean/hostname.png
:alt: Select suitable hostname for your server
```
8. Click the **Create** button! You will be taken to a different screen,
where you can see progress of your server being created.
```{image} ../images/providers/digitalocean/server-create-wait.png
:alt: Server being created
```
9. In a few seconds your server will be created, and you can see the **public IP**
used to access it.
```{image} ../images/providers/digitalocean/server-create-done.png
:alt: Server finished creating, public IP available
```
10. The Littlest JupyterHub is now installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
11. Check if the installation is complete by copying the **public ip**
of your server, and trying to access it with a browser. This will fail until
the installation is complete, so be patient.
12. When the installation is complete, it should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
13. Login using the **admin user name** you used in step 6, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
14. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```

119
docs/install/digitalocean.rst
View File

@@ -1,119 +0,0 @@
.. _insatll/digitalocean:
===========================
Installing on Digital Ocean
===========================
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
`DigitalOcean <https://digitalocean.com>`_.
Pre-requisites
==============
#. A DigitalOcean account with a payment method attached.
Step 1: Installing The Littlest JupyterHub
==========================================
Let's create the server on which we can run JupyterHub.
#. Log in to `DigitalOcean <https://digitalocean.com>`_. You might need to
attach a credit card or other payment method to your account before you
can proceed with the tutorial.
#. Click the **Create** button on the top right, and select **Droplets** from
the dropdown menu. DigitalOcean calls servers **droplets**.
.. image:: ../images/providers/digitalocean/create-menu.png
:alt: Dropdown menu on clicking 'create' in top right corner
This takes you to a page titled **Create Droplets** that lets you configure
your server.
#. Under **Choose an image**, select **22.04 x64** under **Ubuntu**.
.. image:: ../images/providers/digitalocean/select-image.png
:alt: Select 22.04 x64 image under Ubuntu
#. Under **Choose a size**, select the size of the server you want. The default
(4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server
later if you need.
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
how much Memory, CPU & disk space your server needs.
#. Scroll down to **Select additional options**, and select **User data**.
.. image:: ../images/providers/digitalocean/additional-options.png
:alt: Turn on User Data in additional options
This opens up a textbox where you can enter a script that will be run
when the server is created. We will use this to set up The Littlest JupyterHub
on this server.
#. Copy the text below, and paste it into the user data text box. Replace
``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
.. code-block:: bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
#. Under the **Finalize and create** section, enter a ``hostname`` that descriptively
identifies this server for you.
.. image:: ../images/providers/digitalocean/hostname.png
:alt: Select suitable hostname for your server
#. Click the **Create** button! You will be taken to a different screen,
where you can see progress of your server being created.
.. image:: ../images/providers/digitalocean/server-create-wait.png
:alt: Server being created
#. In a few seconds your server will be created, and you can see the **public IP**
used to access it.
.. image:: ../images/providers/digitalocean/server-create-done.png
:alt: Server finished creating, public IP available
#. The Littlest JupyterHub is now installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
#. Check if the installation is complete by copying the **public ip**
of your server, and trying to access it with a browser. This will fail until
the installation is complete, so be patient.
#. When the installation is complete, it should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 6, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
#. Congratulations, you have a running working JupyterHub!
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt

219
docs/install/google.md Normal file
View File

@@ -0,0 +1,219 @@
(install-google)=
# Installing on Google Cloud
## Goal
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
[Google Cloud](https://cloud.google.com/).
## Prerequisites
1. A Google Cloud account. You might use the free credits for trying it out!
## Step 1: Installing The Littlest JupyterHub
Let's create the server on which we can run JupyterHub.
1. Log in to [Google Cloud Console](https://console.cloud.google.com) with
your Google Account.
2. Open the navigation menu by clicking the button with three lines on the top
left corner of the page.
```{image} ../images/providers/google/left-menu-button.png
:alt: Button to open the menu
```
This opens a menu with all the cloud products Google Cloud offers.
3. Under **Compute Engine**, select **VM Instances**.
```{image} ../images/providers/google/vm-instances-menu.png
:alt: Navigation Menu -> Compute Engine -> VM Instances
```
4. If you are using Google Cloud for the first time, you might have to
enable billing. Google will present a screen asking you to enable billing
to proceed. Click the **Enable Billing** button and follow any prompts
that appear.
```{image} ../images/providers/google/enable-billing.png
:alt: Enable billing if needed.
```
It might take a few minutes for your account to be set up.
5. Once Compute Engine is ready, click the **Create** button to start
creating the server that'll run TLJH.
```{image} ../images/providers/google/create-vm-first.png
:alt: Create VM page when using it for the first time.
```
If you already have VMs running in your project, the screen will look
different. But you can find the **Create** button still!
6. This shows you a page titled **Create an instance**. This lets you customize
the kind of server you want, the resources it will have & what it'll be called.
7. Under **Name**, give it a memorable name that identifies what purpose this
JupyterHub will be used for.
8. **Region** specifies the physical location where this server will be hosted.
Generally, pick something close to where most of your users are. Note that
it might increase the cost of your server in some cases!
9. For **Zone**, pick any of the options. Leaving the default as is is fine.
10. Under **Machine** type, select the amount of CPU / RAM / GPU you want for your
server. You need at least **1GB** of RAM.
You can select a preset combination in the default **basic view**.
```{image} ../images/providers/google/machine-type-basic.png
:alt: Select a preset VM type
```
If you want to add **GPUs**, you should click the **Customize** button &
use the **Advanced View**. You need to request [a quota increase](https://cloud.google.com/compute/quotas#gpus)
before you can use GPUs.
```{image} ../images/providers/google/machine-type-advanced.png
:alt: Select a customized VM size
```
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
how much Memory / CPU your server needs.
11. Under **Boot Disk**, click the **Change** button. This lets us change the
operating system and the size of your disk.
```{image} ../images/providers/google/boot-disk-button.png
:alt: Changing Boot Disk & disk size
```
This should open a **Boot disk** popup.
12. Select **Ubuntu 22.04 LTS** from the list of operating system images.
```{image} ../images/providers/google/boot-disk-ubuntu.png
:alt: Selecting Ubuntu 22.04 for OS
```
13. You can also change the **type** and **size** of your disk at the bottom
of this popup.
```{image} ../images/providers/google/boot-disk-size.png
:alt: Selecting Boot disk type & size
```
**Standard persistent disk** type gives you a slower but cheaper disk, similar
to a hard drive. **SSD persistent disk** gives you a faster but more expensive
disk, similar to an SSD.
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
how much Disk space your server needs.
14. Click the **Select** button to dismiss the Boot disk popup and go back to the
Create an instance screen.
15. Under **Identity and API access**, select **No service account** for the
**Service account** field. This prevents your JupyterHub users from automatically
accessing other cloud services, increasing security.
```{image} ../images/providers/google/no-service-account.png
:alt: Disable service accounts for the server
```
16. Under **Firewall**, check both **Allow HTTP Traffic** and **Allow HTTPS Traffic**
checkboxes.
```{image} ../images/providers/google/firewall.png
:alt: Allow HTTP & HTTPS traffic to your server
```
17. Click the **Management, disks, networking, SSH keys** link to expand more
options.
```{image} ../images/providers/google/management-button.png
:alt: Expand management options by clicking link.
```
This displays a lot of advanced options, but we'll be only using one of them.
18. Copy the text below, and paste it into the **Startup script** text box. Replace
`<admin-user-name>` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
```bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
```
```{image} ../images/providers/google/startup-script.png
:alt: Install JupyterHub with the Startup script textbox
```
:::{note}
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
[](/topic/customizing-installer) documents other options that can be passed to the installer.
:::
19. Click the **Create** button at the bottom to start your server!
```{image} ../images/providers/google/create-vm-button.png
:alt: Launch an Instance / Advanced Options dialog box
```
20. We'll be sent to the **VM instances** page, where we can see that our server
is being created.
```{image} ../images/providers/google/vm-creating.png
:alt: Spinner with vm creating
```
21. In a few seconds your server will be created, and you can see the **External IP**
used to access it.
```{image} ../images/providers/google/vm-created.png
:alt: VM created, external IP available
```
22. The Littlest JupyterHub is now installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
23. Check if the installation is complete by **copying** the **External IP**
of your server, and trying to access it with a browser. Do **not click** on the
IP - this will open the link with HTTPS, and will not work.
Accessing the JupyterHub will also fail until the installation is complete,
so be patient.
24. When the installation is complete, it should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
25. Login using the **admin user name** you used in step 6, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
26. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```

205
docs/install/google.rst
View File

@@ -1,205 +0,0 @@
.. _install/google:
==========================
Installing on Google Cloud
==========================
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
`Google Cloud <https://cloud.google.com/>`_.
Prerequisites
=============
#. A Google Cloud account. You might use the free credits for trying it out!
Step 1: Installing The Littlest JupyterHub
==========================================
Let's create the server on which we can run JupyterHub.
#. Log in to `Google Cloud Console <https://console.cloud.google.com>`_ with
your Google Account.
#. Open the navigation menu by clicking the button with three lines on the top
left corner of the page.
.. image:: ../images/providers/google/left-menu-button.png
:alt: Button to open the menu
This opens a menu with all the cloud products Google Cloud offers.
#. Under **Compute Engine**, select **VM Instances**.
.. image:: ../images/providers/google/vm-instances-menu.png
:alt: Navigation Menu -> Compute Engine -> VM Instances
#. If you are using Google Cloud for the first time, you might have to
enable billing. Google will present a screen asking you to enable billing
to proceed. Click the **Enable Billing** button and follow any prompts
that appear.
.. image:: ../images/providers/google/enable-billing.png
:alt: Enable billing if needed.
It might take a few minutes for your account to be set up.
#. Once Compute Engine is ready, click the **Create** button to start
creating the server that'll run TLJH.
.. image:: ../images/providers/google/create-vm-first.png
:alt: Create VM page when using it for the first time.
If you already have VMs running in your project, the screen will look
different. But you can find the **Create** button still!
#. This shows you a page titled **Create an instance**. This lets you customize
the kind of server you want, the resources it will have & what it'll be called.
#. Under **Name**, give it a memorable name that identifies what purpose this
JupyterHub will be used for.
#. **Region** specifies the physical location where this server will be hosted.
Generally, pick something close to where most of your users are. Note that
it might increase the cost of your server in some cases!
#. For **Zone**, pick any of the options. Leaving the default as is is fine.
#. Under **Machine** type, select the amount of CPU / RAM / GPU you want for your
server. You need at least **1GB** of RAM.
You can select a preset combination in the default **basic view**.
.. image:: ../images/providers/google/machine-type-basic.png
:alt: Select a preset VM type
If you want to add **GPUs**, you should click the **Customize** button &
use the **Advanced View**. You need to request `a quota increase <https://cloud.google.com/compute/quotas#gpus>`_
before you can use GPUs.
.. image:: ../images/providers/google/machine-type-advanced.png
:alt: Select a customized VM size
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
how much Memory / CPU your server needs.
#. Under **Boot Disk**, click the **Change** button. This lets us change the
operating system and the size of your disk.
.. image:: ../images/providers/google/boot-disk-button.png
:alt: Changing Boot Disk & disk size
This should open a **Boot disk** popup.
#. Select **Ubuntu 22.04 LTS** from the list of operating system images.
.. image:: ../images/providers/google/boot-disk-ubuntu.png
:alt: Selecting Ubuntu 22.04 for OS
#. You can also change the **type** and **size** of your disk at the bottom
of this popup.
.. image:: ../images/providers/google/boot-disk-size.png
:alt: Selecting Boot disk type & size
**Standard persistent disk** type gives you a slower but cheaper disk, similar
to a hard drive. **SSD persistent disk** gives you a faster but more expensive
disk, similar to an SSD.
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
how much Disk space your server needs.
#. Click the **Select** button to dismiss the Boot disk popup and go back to the
Create an instance screen.
#. Under **Identity and API access**, select **No service account** for the
**Service account** field. This prevents your JupyterHub users from automatically
accessing other cloud services, increasing security.
.. image:: ../images/providers/google/no-service-account.png
:alt: Disable service accounts for the server
#. Under **Firewall**, check both **Allow HTTP Traffic** and **Allow HTTPS Traffic**
checkboxes.
.. image:: ../images/providers/google/firewall.png
:alt: Allow HTTP & HTTPS traffic to your server
#. Click the **Management, disks, networking, SSH keys** link to expand more
options.
.. image:: ../images/providers/google/management-button.png
:alt: Expand management options by clicking link.
This displays a lot of advanced options, but we'll be only using one of them.
#. Copy the text below, and paste it into the **Startup script** text box. Replace
``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
.. code-block:: bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
.. image:: ../images/providers/google/startup-script.png
:alt: Install JupyterHub with the Startup script textbox
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
#. Click the **Create** button at the bottom to start your server!
.. image:: ../images/providers/google/create-vm-button.png
:alt: Launch an Instance / Advanced Options dialog box
#. We'll be sent to the **VM instances** page, where we can see that our server
is being created.
.. image:: ../images/providers/google/vm-creating.png
:alt: Spinner with vm creating
#. In a few seconds your server will be created, and you can see the **External IP**
used to access it.
.. image:: ../images/providers/google/vm-created.png
:alt: VM created, external IP available
#. The Littlest JupyterHub is now installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
#. Check if the installation is complete by **copying** the **External IP**
of your server, and trying to access it with a browser. Do **not click** on the
IP - this will open the link with HTTPS, and will not work.
Accessing the JupyterHub will also fail until the installation is complete,
so be patient.
#. When the installation is complete, it should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 6, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
#. Congratulations, you have a running working JupyterHub!
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt

25
docs/install/index.rst → docs/install/index.md
View File

@@ -1,8 +1,6 @@
.. _install/installing:
(install-installing)=
==========
Installing
==========
# Installing
The Littlest JupyterHub (TLJH) can run on any server that is running **Debian 11** or **Ubuntu 20.04** or **22.04** on a amd64 or arm64 CPU architecture.
Earlier versions of Ubuntu and Debian are not supported, nor are other Linux distributions.
@@ -12,13 +10,14 @@ Tutorials to create a new server from scratch on a cloud provider & run TLJH
on it. These are **recommended** if you do not have much experience setting up
servers.
.. toctree::
:titlesonly:
```{toctree}
:titlesonly: true
digitalocean
ovh
jetstream
google
amazon
azure
custom-server
digitalocean
ovh
jetstream
google
amazon
azure
custom-server
```

152
docs/install/jetstream.md Normal file
View File

@@ -0,0 +1,152 @@
(install-jetstream)=
# Installing on Jetstream
## Goal
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
[Jetstream](https://jetstream-cloud.org/).
## Prerequisites
1. A Jetstream account with an XSEDE allocation; for more information,
see the [Jetstream Allocations help page](http://wiki.jetstream-cloud.org/Jetstream+Allocations).
## Step 1: Installing The Littlest JupyterHub
Let's create the server on which we can run JupyterHub.
1. Log in to [the Jetstream portal](https://use.jetstream-cloud.org/). You need an allocation
to launch instances.
2. Select the **Launch New Instance** option to get going.
```{image} ../images/providers/jetstream/launch-instance-first-button.png
:alt: Launch new instance button with description.
```
This takes you to a page with a list of base images you can choose for your
server.
3. Under **Image Search**, search for **Ubuntu 22.04**, and select the
**Ubuntu 22.04 Devel and Docker** image.
```{image} ../images/providers/jetstream/select-image.png
:alt: Select Ubuntu 22.04 x64 image from image list
```
4. Once selected, you will see more information about this image. Click the
**Launch** button on the top right.
```{image} ../images/providers/jetstream/launch-instance-second-button.png
:alt: Launch selected image with Launch button on top right
```
5. A dialog titled **Launch an Instance / Basic Options** pops up, with various
options for configuring your instance.
```{image} ../images/providers/jetstream/launch-instance-dialog.png
:alt: Launch an Instance / Basic Options dialog box
```
1. Give your server a descriptive **Instance Name**.
2. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
Make sure your instance has at least **1GB** of RAM.
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
how much Memory, CPU & disk space your server needs.
3. If you have multiple allocations, make sure you are 'charging' this server
to the correct allocation.
6. Click the **Advanced Options** link in the bottom left of the popup. This
lets us configure what the server should do when it starts up. We will use
this to install The Littlest JupyterHub.
A dialog titled **Launch an Instance / Advanced Options** should pop up.
```{image} ../images/providers/jetstream/add-deployment-script-dialog.png
:alt: Dialog box allowing you to add a new script.
```
7. Click the **Create New Script** button. This will open up another dialog
box!
```{image} ../images/providers/jetstream/create-script-dialog.png
:alt: Launch an Instance / Advanced Options dialog box
```
8. Under **Input Type**, select **Raw Text**. This should make a text box titled
**Raw Text** visible on the right side of the dialog box.
Copy the text below, and paste it into the **Raw Text** text box. Replace
`<admin-user-name>` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
```bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
```
:::{note}
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
[](/topic/customizing-installer) documents other options that can be passed to the installer.
:::
9. Under **Execution Strategy Type**, select **Run script on first boot**.
10. Under **Deployment Type**, select **Wait for script to complete**.
11. Click the **Save and Add Script** button on the bottom right. This should hide
the dialog box.
12. Click the **Continue to Launch** button on the bottom right. This should put you
back in the **Launch an Instance / Basic Options** dialog box again.
13. Click the **Launch Instance** button on the bottom right. This should turn it
into a spinner, and your server is getting created!
```{image} ../images/providers/jetstream/launching-spinner.png
:alt: Launch button turns into a spinner
```
14. You'll now be shown a dashboard with all your servers and their states. The
server you just launched will progress through various stages of set up,
and you can see the progress here.
```{image} ../images/providers/jetstream/deployment-in-progress.png
:alt: Instances dashboard showing deployment in progress.
```
15. It will take about ten minutes for your server to come up. The status will
say **Active** and the progress bar will be a solid green. At this point,
your JupyterHub is ready for use!
16. Copy the **IP Address** of your server, and try accessing it from a web
browser. It should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
17. Login using the **admin user name** you used in step 8, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
18. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```

145
docs/install/jetstream.rst
View File

@@ -1,145 +0,0 @@
.. _install/jetstream:
=======================
Installing on Jetstream
=======================
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
`Jetstream <https://jetstream-cloud.org/>`_.
Prerequisites
=============
#. A Jetstream account with an XSEDE allocation; for more information,
see the `Jetstream Allocations help page <http://wiki.jetstream-cloud.org/Jetstream+Allocations>`_.
Step 1: Installing The Littlest JupyterHub
==========================================
Let's create the server on which we can run JupyterHub.
#. Log in to `the Jetstream portal <https://use.jetstream-cloud.org/>`_. You need an allocation
to launch instances.
#. Select the **Launch New Instance** option to get going.
.. image:: ../images/providers/jetstream/launch-instance-first-button.png
:alt: Launch new instance button with description.
This takes you to a page with a list of base images you can choose for your
server.
#. Under **Image Search**, search for **Ubuntu 22.04**, and select the
**Ubuntu 22.04 Devel and Docker** image.
.. image:: ../images/providers/jetstream/select-image.png
:alt: Select Ubuntu 22.04 x64 image from image list
#. Once selected, you will see more information about this image. Click the
**Launch** button on the top right.
.. image:: ../images/providers/jetstream/launch-instance-second-button.png
:alt: Launch selected image with Launch button on top right
#. A dialog titled **Launch an Instance / Basic Options** pops up, with various
options for configuring your instance.
.. image:: ../images/providers/jetstream/launch-instance-dialog.png
:alt: Launch an Instance / Basic Options dialog box
#. Give your server a descriptive **Instance Name**.
#. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
Make sure your instance has at least **1GB** of RAM.
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
how much Memory, CPU & disk space your server needs.
#. If you have multiple allocations, make sure you are 'charging' this server
to the correct allocation.
#. Click the **Advanced Options** link in the bottom left of the popup. This
lets us configure what the server should do when it starts up. We will use
this to install The Littlest JupyterHub.
A dialog titled **Launch an Instance / Advanced Options** should pop up.
.. image:: ../images/providers/jetstream/add-deployment-script-dialog.png
:alt: Dialog box allowing you to add a new script.
#. Click the **Create New Script** button. This will open up another dialog
box!
.. image:: ../images/providers/jetstream/create-script-dialog.png
:alt: Launch an Instance / Advanced Options dialog box
#. Under **Input Type**, select **Raw Text**. This should make a text box titled
**Raw Text** visible on the right side of the dialog box.
Copy the text below, and paste it into the **Raw Text** text box. Replace
``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
.. code-block:: bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
#. Under **Execution Strategy Type**, select **Run script on first boot**.
#. Under **Deployment Type**, select **Wait for script to complete**.
#. Click the **Save and Add Script** button on the bottom right. This should hide
the dialog box.
#. Click the **Continue to Launch** button on the bottom right. This should put you
back in the **Launch an Instance / Basic Options** dialog box again.
#. Click the **Launch Instance** button on the bottom right. This should turn it
into a spinner, and your server is getting created!
.. image:: ../images/providers/jetstream/launching-spinner.png
:alt: Launch button turns into a spinner
#. You'll now be shown a dashboard with all your servers and their states. The
server you just launched will progress through various stages of set up,
and you can see the progress here.
.. image:: ../images/providers/jetstream/deployment-in-progress.png
:alt: Instances dashboard showing deployment in progress.
#. It will take about ten minutes for your server to come up. The status will
say **Active** and the progress bar will be a solid green. At this point,
your JupyterHub is ready for use!
#. Copy the **IP Address** of your server, and try accessing it from a web
browser. It should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 8, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
#. Congratulations, you have a running working JupyterHub!
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt

133
docs/install/ovh.md Normal file
View File

@@ -0,0 +1,133 @@
(install-ovh)=
# Installing on OVH
## Goal
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
[OVH](https://www.ovh.com).
## Pre-requisites
1. An OVH account.
## Step 1: Installing The Littlest JupyterHub
Let's create the server on which we can run JupyterHub.
1. Log in to the [OVH Control Panel](https://www.ovh.com/auth/).
2. Click the **Public Cloud** button in the navigation bar.
```{image} ../images/providers/ovh/public-cloud.png
:alt: Public Cloud entry in the navigation bar
```
3. If you don't have an OVH Stack, you can create one by clicking on the following button:
```{image} ../images/providers/ovh/create-ovh-stack.png
:alt: Button to create an OVH stack
```
4. Select a name for the project:
```{image} ../images/providers/ovh/project-name.png
:alt: Select a name for the project
```
5. If you don't have a payment method yet, select one and click on "Create my project":
```{image} ../images/providers/ovh/payment.png
:alt: Select a payment method
```
6. Using the **Public Cloud interface**, click on **Create an instance**:
```{image} ../images/providers/ovh/create-instance.png
:alt: Create a new instance
```
7. **Select a model** for the instance. A good start is the **S1-4** model under **Shared resources** which comes with 4GB RAM, 1 vCores and 20GB SSD.
8. **Select a region**.
9. Select **Ubuntu 22.04** as the image:
```{image} ../images/providers/ovh/distribution.png
:alt: Select Ubuntu 22.04 as the image
```
10. OVH requires setting an SSH key to be able to connect to the instance.
You can create a new SSH by following
[these instructions](https://help.github.com/en/enterprise/2.16/user/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
Be sure to copy the content of the `~/.ssh/id_rsa.pub` file, which corresponds to the **public part** of the SSH key.
11. Select **Configure your instance**, and select a name for the instance.
Under **Post-installation script**, copy the text below and paste it in the text box.
Replace `<admin-user-name>` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
```bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
```
:::{note}
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
[](/topic/customizing-installer) documents other options that can be passed to the installer.
:::
```{image} ../images/providers/ovh/configuration.png
:alt: Add post-installation script
```
12. Select a billing period: monthly or hourly.
13. Click the **Create an instance** button! You will be taken to a different screen,
where you can see progress of your server being created.
```{image} ../images/providers/ovh/create-instance.png
:alt: Select suitable hostname for your server
```
14. In a few seconds your server will be created, and you can see the **public IP**
used to access it.
```{image} ../images/providers/ovh/public-ip.png
:alt: Server finished creating, public IP available
```
15. The Littlest JupyterHub is now installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
16. Check if the installation is complete by copying the **public ip**
of your server, and trying to access it with a browser. This will fail until
the installation is complete, so be patient.
17. When the installation is complete, it should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
18. Login using the **admin user name** you used in step 6, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
19. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
```{include} add_users.txt
```
## Step 3: Install conda / pip packages for all users
```{include} add_packages.txt
```

127
docs/install/ovh.rst
View File

@@ -1,127 +0,0 @@
.. _install/ovh:
=================
Installing on OVH
=================
Goal
====
By the end of this tutorial, you should have a JupyterHub with some admin
users and a user environment with packages you want installed running on
`OVH <https://www.ovh.com>`_.
Pre-requisites
==============
#. An OVH account.
Step 1: Installing The Littlest JupyterHub
==========================================
Let's create the server on which we can run JupyterHub.
#. Log in to the `OVH Control Panel <https://www.ovh.com/auth/>`_.
#. Click the **Public Cloud** button in the navigation bar.
.. image:: ../images/providers/ovh/public-cloud.png
:alt: Public Cloud entry in the navigation bar
#. If you don't have an OVH Stack, you can create one by clicking on the following button:
.. image:: ../images/providers/ovh/create-ovh-stack.png
:alt: Button to create an OVH stack
#. Select a name for the project:
.. image:: ../images/providers/ovh/project-name.png
:alt: Select a name for the project
#. If you don't have a payment method yet, select one and click on "Create my project":
.. image:: ../images/providers/ovh/payment.png
:alt: Select a payment method
#. Using the **Public Cloud interface**, click on **Create an instance**:
.. image:: ../images/providers/ovh/create-instance.png
:alt: Create a new instance
#. **Select a model** for the instance. A good start is the **S1-4** model under **Shared resources** which comes with 4GB RAM, 1 vCores and 20GB SSD.
#. **Select a region**.
#. Select **Ubuntu 22.04** as the image:
.. image:: ../images/providers/ovh/distribution.png
:alt: Select Ubuntu 22.04 as the image
#. OVH requires setting an SSH key to be able to connect to the instance.
You can create a new SSH by following
`these instructions <https://help.github.com/en/enterprise/2.16/user/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_.
Be sure to copy the content of the ``~/.ssh/id_rsa.pub`` file, which corresponds to the **public part** of the SSH key.
#. Select **Configure your instance**, and select a name for the instance.
Under **Post-installation script**, copy the text below and paste it in the text box.
Replace ``<admin-user-name>`` with the name of the first **admin user** for this
JupyterHub. This admin user can log in after the JupyterHub is set up, and
can configure it to their needs. **Remember to add your username**!
.. code-block:: bash
#!/bin/bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin <admin-user-name>
.. note::
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
.. image:: ../images/providers/ovh/configuration.png
:alt: Add post-installation script
#. Select a billing period: monthly or hourly.
#. Click the **Create an instance** button! You will be taken to a different screen,
where you can see progress of your server being created.
.. image:: ../images/providers/ovh/create-instance.png
:alt: Select suitable hostname for your server
#. In a few seconds your server will be created, and you can see the **public IP**
used to access it.
.. image:: ../images/providers/ovh/public-ip.png
:alt: Server finished creating, public IP available
#. The Littlest JupyterHub is now installing in the background on your new server.
It takes around 5-10 minutes for this installation to complete.
#. Check if the installation is complete by copying the **public ip**
of your server, and trying to access it with a browser. This will fail until
the installation is complete, so be patient.
#. When the installation is complete, it should give you a JupyterHub login page.
.. image:: ../images/first-login.png
:alt: JupyterHub log-in page
#. Login using the **admin user name** you used in step 6, and a password. Use a
strong password & note it down somewhere, since this will be the password for
the admin user account from now on.
#. Congratulations, you have a running working JupyterHub!
Step 2: Adding more users
==========================
.. include:: add_users.txt
Step 3: Install conda / pip packages for all users
==================================================
.. include:: add_packages.txt

1
docs/requirements.txt
View File

@@ -1,3 +1,4 @@
myst-parser>=0.19
pydata-sphinx-theme
# Sphix 6.0.0 breaks pydata-sphinx-theme
# See pydata/pydata-sphinx-theme#1094

89
docs/topic/authenticator-configuration.md Normal file
View File

@@ -0,0 +1,89 @@
(topic-authenticator-configuration)=
# Configuring JupyterHub authenticators
Any [JupyterHub authenticator](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators)
can be used with TLJH. A number of them ship by default with TLJH:
1. [OAuthenticator](https://github.com/jupyterhub/oauthenticator) - Google, GitHub, CILogon,
GitLab, Globus, Mediawiki, auth0, generic OpenID connect (for KeyCloak, etc) and other
OAuth based authentication methods.
2. [LDAPAuthenticator](https://github.com/jupyterhub/ldapauthenticator) - LDAP & Active Directory.
3. [DummyAuthenticator](https://github.com/yuvipanda/jupyterhub-dummy-authenticator) - Any username,
one shared password. A [how-to guide on using DummyAuthenticator](howto-auth-dummy) is also
available.
4. [FirstUseAuthenticator](https://github.com/yuvipanda/jupyterhub-firstuseauthenticator) - Users set
their password when they log in for the first time. Default authenticator used in TLJH.
5. [TmpAuthenticator](https://github.com/jupyterhub/tmpauthenticator) - Opens the JupyterHub to the
world, makes a new user every time someone logs in.
6. [NativeAuthenticator](https://native-authenticator.readthedocs.io/en/latest/) - Allow users to signup, add password security verification and block users after failed attempts oflogin.
We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
everything, this guide shows you how to use any authenticator you want with JupyterHub by following
the authenticator's documentation.
## Setting authenticator properties
JupyterHub authenticators are customized by setting _traitlet properties_. In the authenticator's
documentation, you will find these are usually represented as:
```python
c.<AuthenticatorName>.<property-name> = <some-value>
```
You can set these with `tljh-config` with:
```bash
sudo tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
```
### Example
[LDAPAuthenticator's documentation](https://github.com/jupyterhub/ldapauthenticator#required-configuration)
lists the various configuration options you can set for LDAPAuthenticator.
When the documentation asks you to set `LDAPAuthenticator.server_address`
to some value, you can do that with the following command:
```bash
sudo tljh-config set auth.LDAPAuthenticator.server_address 'my-ldap-server'
```
Most authenticators require you set multiple configuration options before you can
enable them. Read the authenticator's documentation carefully for more information.
## Enabling the authenticator
Once you have configured the authenticator as you want, you should then
enable it. Usually, the documentation for the authenticator would ask you to add
something like the following to your `jupyterhub_config.py` to enable it:
```python
c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
```
You can accomplish the same with `tljh-config`:
```bash
sudo tljh-config set auth.type <fully-qualified-authenticator-name>
```
Once enabled, you need to reload JupyterHub for the config to take effect.
```bash
sudo tljh-config reload
```
Try logging in a separate incognito window to check if your configuration works. This
lets you preserve your terminal in case there were errors. If there are
errors, [](/troubleshooting/logs) should help you debug them.
### Example
From the [documentation](https://github.com/jupyterhub/ldapauthenticator#usage) for
LDAPAuthenticator, we see that the fully qualified name is `ldapauthenticator.LDAPAuthenticator`.
Assuming you have already configured it, the following commands enable LDAPAuthenticator.
```bash
sudo tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
sudo tljh-config reload
```

95
docs/topic/authenticator-configuration.rst
View File

@@ -1,95 +0,0 @@
.. _topic/authenticator-configuration:
=====================================
Configuring JupyterHub authenticators
=====================================
Any `JupyterHub authenticator <https://github.com/jupyterhub/jupyterhub/wiki/Authenticators>`_
can be used with TLJH. A number of them ship by default with TLJH:
#. `OAuthenticator <https://github.com/jupyterhub/oauthenticator>`_ - Google, GitHub, CILogon,
GitLab, Globus, Mediawiki, auth0, generic OpenID connect (for KeyCloak, etc) and other
OAuth based authentication methods.
#. `LDAPAuthenticator <https://github.com/jupyterhub/ldapauthenticator>`_ - LDAP & Active Directory.
#. `DummyAuthenticator <https://github.com/yuvipanda/jupyterhub-dummy-authenticator>`_ - Any username,
one shared password. A :ref:`how-to guide on using DummyAuthenticator <howto/auth/dummy>` is also
available.
#. `FirstUseAuthenticator <https://github.com/yuvipanda/jupyterhub-firstuseauthenticator>`_ - Users set
their password when they log in for the first time. Default authenticator used in TLJH.
#. `TmpAuthenticator <https://github.com/jupyterhub/tmpauthenticator>`_ - Opens the JupyterHub to the
world, makes a new user every time someone logs in.
#. `NativeAuthenticator <https://native-authenticator.readthedocs.io/en/latest/>`_ - Allow users to signup, add password security verification and block users after failed attempts oflogin.
We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
everything, this guide shows you how to use any authenticator you want with JupyterHub by following
the authenticator's documentation.
Setting authenticator properties
================================
JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's
documentation, you will find these are usually represented as:
.. code-block:: python
c.<AuthenticatorName>.<property-name> = <some-value>
You can set these with ``tljh-config`` with:
.. code-block:: bash
sudo tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
Example
-------
`LDAPAuthenticator's documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
lists the various configuration options you can set for LDAPAuthenticator.
When the documentation asks you to set ``LDAPAuthenticator.server_address``
to some value, you can do that with the following command:
.. code-block:: bash
sudo tljh-config set auth.LDAPAuthenticator.server_address 'my-ldap-server'
Most authenticators require you set multiple configuration options before you can
enable them. Read the authenticator's documentation carefully for more information.
Enabling the authenticator
==========================
Once you have configured the authenticator as you want, you should then
enable it. Usually, the documentation for the authenticator would ask you to add
something like the following to your ``jupyterhub_config.py`` to enable it:
.. code-block:: python
c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
You can accomplish the same with ``tljh-config``:
.. code-block:: bash
sudo tljh-config set auth.type <fully-qualified-authenticator-name>
Once enabled, you need to reload JupyterHub for the config to take effect.
.. code-block:: bash
sudo tljh-config reload
Try logging in a separate incognito window to check if your configuration works. This
lets you preserve your terminal in case there were errors. If there are
errors, :ref:`troubleshooting/logs` should help you debug them.
Example
-------
From the `documentation <https://github.com/jupyterhub/ldapauthenticator#usage>`_ for
LDAPAuthenticator, we see that the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
Assuming you have already configured it, the following commands enable LDAPAuthenticator.
.. code-block:: bash
sudo tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
sudo tljh-config reload

135
docs/topic/customizing-installer.md Normal file
View File

@@ -0,0 +1,135 @@
(topic-customizing-installer)=
# Customizing the Installer
The installer can be customized with commandline parameters. The default installer
is executed as:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
<parameters>
```
This page documents the various options you can pass as commandline parameters to the installer.
(topic-customizing-installer-admin)=
## Serving a temporary "TLJH is building" page
`--show-progress-page` serves a temporary "TLJH is building" progress page while TLJH is building.
```{image} ../images/tljh-is-building-page.gif
:alt: Temporary progress page while TLJH is building
```
- The page will be accessible at `http://<tljh-public-ip>/index.html` in your browser.
When TLJH installation is complete, the progress page page will stop and you will be able
to access TLJH as usually at `http://<tljh-public-ip>`.
- From the progress page, you will also be able to access the installation logs, by clicking the
**Logs** button or by going directly to `http://<tljh-public-ip>/logs` in your browser.
To update the logs, refresh the page.
:::{note}
The `http://<tljh-public-ip>/index.html` page refreshes itself automatically every 30s.
When JupyterHub starts, a JupyterHub 404 HTTP error message (_Jupyter has lots of moons, but this is not one..._)
will be shown instead of the progress page. This means JupyterHub was started succesfully and you can access it
either by clicking the `Control Panel` button or by going to `http://<tljh-public-ip>/` directly.
:::
For example, to enable the progress page and add the first _admin_ user, you would run:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin --show-progress-page
```
## Adding admin users
`--admin <username>:<password>` adds user `<username>` to JupyterHub as an admin user
and sets its password to be `<password>`.
Although it is not recommended, it is possible to only set the admin username at this point
and set the admin password after the installation.
Also, the `--admin` flag can be repeated multiple times. For example, to add `admin-user1`
and `admin-user2` as admins when installing, depending if you would like to set their passwords
during install you would:
- set `admin-user1` with password `password-user1` and `admin-user2` with `password-user2` using:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2:password-user2
```
- set `admin-user1` and `admin-user2` to be admins, without any passwords at this stage, using:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1 --admin admin-user2
```
- set `admin-user1` with password `password-user1` and `admin-user2` with no password at this stage using:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2
```
## Installing python packages in the user environment
`--user-requirements-txt-url <url-to-requirements.txt>` installs packages specified
in the `requirements.txt` located at the given URL into the user environment at install
time. This is very useful when you want to set up a hub with a particular user environment
in one go.
For example, to install the latest requirements to run UC Berkeley's data8 course
in your new hub, you would run:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--user-requirements-txt-url https://raw.githubusercontent.com/data-8/materials-sp18/HEAD/requirements.txt
```
The URL **must** point to a working requirements.txt. If there are any errors, the installation
will fail.
:::{note}
When pointing to a file on GitHub, make sure to use the 'Raw' version. It should point to
`raw.githubusercontent.com`, not `github.com`.
:::
## Installing TLJH plugins
The Littlest JupyterHub can install additional _plugins_ that provide additional
features. They are most commonly used to install a particular _stack_ - such as
the [PANGEO Stack](https://github.com/yuvipanda/tljh-pangeo) for earth sciences
research, a stack for a particular class, etc. You can find more information about
writing plugins and a list of existing plugins at [](/contributing/plugins).
`--plugin <plugin-to-install>` installs and activates a plugin. You can pass it
however many times you want. Since plugins are distributed as python packages,
`<plugin-to-install>` can be anything that can be passed to `pip install` -
`plugin-name-on-pypi==<version>` and `git+https://github.com/user/repo@tag`
are the most popular ones. Specifying a version or tag is highly recommended.
For example, to install the PANGEO Plugin version 0.1 (if version 0.1 existed)
in your new TLJH install, you would use:
```bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--plugin git+https://github.com/yuvipanda/tljh-pangeo@v0.1
```
Multiple plugins can be installed at once with: `--plugin <first-plugin-to-install> <second-plugin-to-install>`.
:::{note}
Plugins are extremely powerful and can do a large number of arbitrary things.
Only install plugins you trust.
:::

140
docs/topic/customizing-installer.rst
View File

@@ -1,140 +0,0 @@
.. _topic/customizing-installer:
=========================
Customizing the Installer
=========================
The installer can be customized with commandline parameters. The default installer
is executed as:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
<parameters>
This page documents the various options you can pass as commandline parameters to the installer.
.. _topic/customizing-installer/admin:
Serving a temporary "TLJH is building" page
===========================================
``--show-progress-page`` serves a temporary "TLJH is building" progress page while TLJH is building.
.. image:: ../images/tljh-is-building-page.gif
:alt: Temporary progress page while TLJH is building
* The page will be accessible at ``http://<tljh-public-ip>/index.html`` in your browser.
When TLJH installation is complete, the progress page page will stop and you will be able
to access TLJH as usually at ``http://<tljh-public-ip>``.
* From the progress page, you will also be able to access the installation logs, by clicking the
**Logs** button or by going directly to ``http://<tljh-public-ip>/logs`` in your browser.
To update the logs, refresh the page.
.. note::
The ``http://<tljh-public-ip>/index.html`` page refreshes itself automatically every 30s.
When JupyterHub starts, a JupyterHub 404 HTTP error message (*Jupyter has lots of moons, but this is not one...*)
will be shown instead of the progress page. This means JupyterHub was started succesfully and you can access it
either by clicking the `Control Panel` button or by going to ``http://<tljh-public-ip>/`` directly.
For example, to enable the progress page and add the first *admin* user, you would run:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin --show-progress-page
Adding admin users
===================
``--admin <username>:<password>`` adds user ``<username>`` to JupyterHub as an admin user
and sets its password to be ``<password>``.
Although it is not recommended, it is possible to only set the admin username at this point
and set the admin password after the installation.
Also, the ``--admin`` flag can be repeated multiple times. For example, to add ``admin-user1``
and ``admin-user2`` as admins when installing, depending if you would like to set their passwords
during install you would:
* set ``admin-user1`` with password ``password-user1`` and ``admin-user2`` with ``password-user2`` using:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2:password-user2
* set ``admin-user1`` and ``admin-user2`` to be admins, without any passwords at this stage, using:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1 --admin admin-user2
* set ``admin-user1`` with password ``password-user1`` and ``admin-user2`` with no password at this stage using:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--admin admin-user1:password-user1 --admin admin-user2
Installing python packages in the user environment
==================================================
``--user-requirements-txt-url <url-to-requirements.txt>`` installs packages specified
in the ``requirements.txt`` located at the given URL into the user environment at install
time. This is very useful when you want to set up a hub with a particular user environment
in one go.
For example, to install the latest requirements to run UC Berkeley's data8 course
in your new hub, you would run:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--user-requirements-txt-url https://raw.githubusercontent.com/data-8/materials-sp18/HEAD/requirements.txt
The URL **must** point to a working requirements.txt. If there are any errors, the installation
will fail.
.. note::
When pointing to a file on GitHub, make sure to use the 'Raw' version. It should point to
``raw.githubusercontent.com``, not ``github.com``.
Installing TLJH plugins
=======================
The Littlest JupyterHub can install additional *plugins* that provide additional
features. They are most commonly used to install a particular *stack* - such as
the `PANGEO Stack <https://github.com/yuvipanda/tljh-pangeo>`_ for earth sciences
research, a stack for a particular class, etc. You can find more information about
writing plugins and a list of existing plugins at :ref:`contributing/plugins`.
``--plugin <plugin-to-install>`` installs and activates a plugin. You can pass it
however many times you want. Since plugins are distributed as python packages,
``<plugin-to-install>`` can be anything that can be passed to ``pip install`` -
``plugin-name-on-pypi==<version>`` and ``git+https://github.com/user/repo@tag``
are the most popular ones. Specifying a version or tag is highly recommended.
For example, to install the PANGEO Plugin version 0.1 (if version 0.1 existed)
in your new TLJH install, you would use:
.. code-block:: bash
curl -L https://tljh.jupyter.org/bootstrap.py \
| sudo python3 - \
--plugin git+https://github.com/yuvipanda/tljh-pangeo@v0.1
Multiple plugins can be installed at once with: ``--plugin <first-plugin-to-install> <second-plugin-to-install>``.
.. note::
Plugins are extremely powerful and can do a large number of arbitrary things.
Only install plugins you trust.

91
docs/topic/escape-hatch.md Normal file
View File

@@ -0,0 +1,91 @@
(topic-escape-hatch)=
# Custom configuration snippets
The two main TLJH components are **JupyterHub** and **Traefik**.
- JupyterHub takes its configuration from the `jupyterhub_config.py` file.
- Traefik loads its:
- [static configuration](https://docs.traefik.io/v1.7/basics/#static-traefik-configuration)
from the `traefik.toml` file.
- [dynamic configuration](https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration)
from the `rules` directory.
The `jupyterhub_config.py` and `traefik.toml` files are created by TLJH during installation
and can be edited by the user only through `tljh-config`. The `rules` directory is also created
during install along with a `rules/rules.toml` file, to be used by JupyterHub to store the routing
table from users to their notebooks.
:::{note}
Any direct modification to these files is unsupported, and will cause hard to debug issues.
:::
But because sometimes TLJH needs to be customized in ways that are not officially
supported, an escape hatch has been introduced to allow easily extending the
configuration. Please follow the sections below for how to extend JupyterHub's
and Traefik's configuration outside of `tljh-config` scope.
## Extending `jupyterhub_config.py`
The `jupyterhub_config.d` directory lets you load multiple `jupyterhub_config.py`
snippets for your configuration.
- Any files in `/opt/tljh/config/jupyterhub_config.d` that end in `.py` will
be loaded in alphabetical order as python files to provide configuration for
JupyterHub.
- The configuration files can have any name, but they need to have the `.py`
extension and to respect this format.
- Any config that can go in a regular `jupyterhub_config.py` file is valid in
these files.
- They will be loaded _after_ any of the config options specified with `tljh-config`
are loaded.
Once you have created and defined your custom JupyterHub config file/s, just reload the
hub for the new configuration to take effect:
```bash
sudo tljh-config reload hub
```
## Extending `traefik.toml`
The `traefik_config.d` directory lets you load multiple `traefik.toml`
snippets for your configuration.
- Any files in `/opt/tljh/config/traefik_config.d` that end in `.toml` will be
loaded in alphabetical order to provide configuration for Traefik.
- The configuration files can have any name, but they need to have the `.toml`
extension and to respect this format.
- Any config that can go in a regular `traefik.toml` file is valid in these files.
- They will be loaded _after_ any of the config options specified with `tljh-config`
are loaded.
Once you have created and defined your custom Traefik config file/s, just reload the
proxy for the new configuration to take effect:
```bash
sudo tljh-config reload proxy
```
:::{warning}
This instructions might change when TLJH will switch to Traefik > 2.0
:::
## Extending `rules.toml`
`Traefik` is configured to load its routing table from the `/opt/tljh/state/rules`
directory. The existing `rules.toml` file inside this directory is used by
`jupyterhub-traefik-proxy` to add the JupyterHub routes from users to their notebook servers
and shouldn't be modified.
However, the routing table can be extended outside JupyterHub's scope using the `rules`
directory, by adding other dynamic configuration files with the desired routing rules.
:::{note}
Any files in `/opt/tljh/state/rules` that end in `.toml` will be hot reload by Traefik.
This means that there is no need to reload the proxy service for the rules to take effect.
:::
Checkout Traefik' docs about [dynamic configuration](https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration)
and how to provide dynamic configuration through
[multiple separated files](https://docs.traefik.io/v1.7/configuration/backends/file/#multiple-separated-files).

94
docs/topic/escape-hatch.rst
View File

@@ -1,94 +0,0 @@
.. _topic/escape-hatch:
=============================
Custom configuration snippets
=============================
The two main TLJH components are **JupyterHub** and **Traefik**.
* JupyterHub takes its configuration from the ``jupyterhub_config.py`` file.
* Traefik loads its:
* `static configuration <https://docs.traefik.io/v1.7/basics/#static-traefik-configuration>`_
from the ``traefik.toml`` file.
* `dynamic configuration <https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration>`_
from the ``rules`` directory.
The ``jupyterhub_config.py`` and ``traefik.toml`` files are created by TLJH during installation
and can be edited by the user only through ``tljh-config``. The ``rules`` directory is also created
during install along with a ``rules/rules.toml`` file, to be used by JupyterHub to store the routing
table from users to their notebooks.
.. note::
Any direct modification to these files is unsupported, and will cause hard to debug issues.
But because sometimes TLJH needs to be customized in ways that are not officially
supported, an escape hatch has been introduced to allow easily extending the
configuration. Please follow the sections below for how to extend JupyterHub's
and Traefik's configuration outside of ``tljh-config`` scope.
Extending ``jupyterhub_config.py``
==================================
The ``jupyterhub_config.d`` directory lets you load multiple ``jupyterhub_config.py``
snippets for your configuration.
* Any files in ``/opt/tljh/config/jupyterhub_config.d`` that end in ``.py`` will
be loaded in alphabetical order as python files to provide configuration for
JupyterHub.
* The configuration files can have any name, but they need to have the `.py`
extension and to respect this format.
* Any config that can go in a regular ``jupyterhub_config.py`` file is valid in
these files.
* They will be loaded *after* any of the config options specified with ``tljh-config``
are loaded.
Once you have created and defined your custom JupyterHub config file/s, just reload the
hub for the new configuration to take effect:
.. code-block:: bash
sudo tljh-config reload hub
Extending ``traefik.toml``
==========================
The ``traefik_config.d`` directory lets you load multiple ``traefik.toml``
snippets for your configuration.
* Any files in ``/opt/tljh/config/traefik_config.d`` that end in ``.toml`` will be
loaded in alphabetical order to provide configuration for Traefik.
* The configuration files can have any name, but they need to have the `.toml`
extension and to respect this format.
* Any config that can go in a regular ``traefik.toml`` file is valid in these files.
* They will be loaded *after* any of the config options specified with ``tljh-config``
are loaded.
Once you have created and defined your custom Traefik config file/s, just reload the
proxy for the new configuration to take effect:
.. code-block:: bash
sudo tljh-config reload proxy
.. warning:: This instructions might change when TLJH will switch to Traefik > 2.0
Extending ``rules.toml``
========================
``Traefik`` is configured to load its routing table from the ``/opt/tljh/state/rules``
directory. The existing ``rules.toml`` file inside this directory is used by
``jupyterhub-traefik-proxy`` to add the JupyterHub routes from users to their notebook servers
and shouldn't be modified.
However, the routing table can be extended outside JupyterHub's scope using the ``rules``
directory, by adding other dynamic configuration files with the desired routing rules.
.. note::
* Any files in ``/opt/tljh/state/rules`` that end in ``.toml`` will be hot reload by Traefik.
This means that there is no need to reload the proxy service for the rules to take effect.
Checkout Traefik' docs about `dynamic configuration <https://docs.traefik.io/v1.7/basics/#dynamic-traefik-configuration>`_
and how to provide dynamic configuration through
`multiple separated files <https://docs.traefik.io/v1.7/configuration/backends/file/#multiple-separated-files>`_.

106
docs/topic/idle-culler.rst → docs/topic/idle-culler.md
View File

@@ -1,8 +1,6 @@
.. _topic/idle-culler:
(topic-idle-culler)=
=============================
Culling idle notebook servers
=============================
# Culling idle notebook servers
The idle culler automatically shuts down user notebook servers when they have
not been used for a certain time period, in order to reduce the total resource
@@ -11,109 +9,103 @@ usage on your JupyterHub.
The notebook server monitors activity internally
and notifies JupyterHub of recent activity at certain time intervals (the activity interval).
If JupyterHub has not been notified of any activity after a certain period (the idle timeout),
the server is considered to be *inactive (idle)* and will be culled (shutdown).
the server is considered to be _inactive (idle)_ and will be culled (shutdown).
The `idle culler <https://github.com/jupyterhub/jupyterhub-idle-culler>`_ is a JupyterHub service that is installed and enabled by default in TLJH.
The [idle culler](https://github.com/jupyterhub/jupyterhub-idle-culler) is a JupyterHub service that is installed and enabled by default in TLJH.
It can be configured using tljh-config. For advanced use-cases, like purging old user data,
the idle culler configuration can be extended beyond tljh-config options, using custom
`jupyterhub_config.py snippets <https://tljh.jupyter.org/en/latest/topic/escape-hatch.html?highlight=escape-hatch#extending-jupyterhub-config-py>`__.
[jupyterhub_config.py snippets](https://tljh.jupyter.org/en/latest/topic/escape-hatch.html?highlight=escape-hatch#extending-jupyterhub-config-py).
Default settings
================
## Default settings
By default, JupyterHub will ping the user notebook servers every 60s to check their
status. Every server found to be idle for more than 10 minutes will be culled.
.. code-block:: python
services.cull.every = 60
services.cull.timeout = 600
```python
services.cull.every = 60
services.cull.timeout = 600
```
Because the servers don't have a maximum age set, an active server will not be shut down
regardless of how long it has been up and running.
.. code-block:: python
services.cull.max_age = 0
```python
services.cull.max_age = 0
```
If after the culling process, there are users with no active notebook servers, by default,
the users will not be culled alongside their notebooks and will continue to exist.
.. code-block:: python
```python
services.cull.users = False
```
services.cull.users = False
Configuring the idle culler
===========================
## Configuring the idle culler
The available configuration options are:
Idle timeout
------------
### Idle timeout
The idle timeout is the maximum time (in seconds) a server can be inactive before it
will be culled. The timeout can be configured using:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.timeout <max-idle-sec-before-server-is-culled>
sudo tljh-config reload
```
sudo tljh-config set services.cull.timeout <max-idle-sec-before-server-is-culled>
sudo tljh-config reload
### Idle check interval
Idle check interval
-------------------
The idle check interval represents how frequent (in seconds) the Hub will
check if there are any idle servers to cull. It can be configured using:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.every <number-of-sec-this-check-is-done>
sudo tljh-config reload
```
sudo tljh-config set services.cull.every <number-of-sec-this-check-is-done>
sudo tljh-config reload
### Maximum age
Maximum age
-----------
The maximum age sets the time (in seconds) a server should be running.
The servers that exceed the maximum age, will be culled even if they are active.
A maximum age of 0, will deactivate this option.
The maximum age can be configured using:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.max_age <server-max-age>
sudo tljh-config reload
```
sudo tljh-config set services.cull.max_age <server-max-age>
sudo tljh-config reload
### User culling
User culling
------------
In addition to servers, it is also possible to cull the users. This is usually
suited for temporary-user cases such as *tmpnb*.
suited for temporary-user cases such as _tmpnb_.
User culling can be activated using the following command:
.. code-block:: bash
```bash
sudo tljh-config set services.cull.users True
sudo tljh-config reload
```
sudo tljh-config set services.cull.users True
sudo tljh-config reload
### Concurrency
Concurrency
-----------
Deleting a lot of users at the same time can slow down the Hub.
The number of concurrent requests made to the Hub can be configured using:
.. code-block:: bash
sudo tljh-config set services.cull.concurrency <number-of-concurrent-hub-requests>
sudo tljh-config reload
```bash
sudo tljh-config set services.cull.concurrency <number-of-concurrent-hub-requests>
sudo tljh-config reload
```
Because TLJH it's used for a small number of users, the cases that may require to
modify the concurrency limit should be rare.
Disabling the idle culler
=========================
## Disabling the idle culler
The idle culling service is enabled by default. To disable it, use the following
command:
.. code-block:: bash
sudo tljh-config set services.cull.enabled False
sudo tljh-config reload
```bash
sudo tljh-config set services.cull.enabled False
sudo tljh-config reload
```

19
docs/topic/index.md Normal file
View File

@@ -0,0 +1,19 @@
# Topic Guides
Topic guides provide in-depth explanations of specific topics.
```{toctree}
:caption: Topic guides
:titlesonly: true
whentouse
requirements
security
customizing-installer
installer-actions
tljh-config
authenticator-configuration
escape-hatch
idle-culler
jupyterhub-configurator
```

20
docs/topic/index.rst
View File

@@ -1,20 +0,0 @@
============
Topic Guides
============
Topic guides provide in-depth explanations of specific topics.
.. toctree::
:titlesonly:
:caption: Topic guides
whentouse
requirements
security
customizing-installer
installer-actions
tljh-config
authenticator-configuration
escape-hatch
idle-culler
jupyterhub-configurator

218
docs/topic/installer-actions.md Normal file
View File

@@ -0,0 +1,218 @@
(topic-installer-actions)=
# What does the installer do?
This document details what exactly the installer does to the machine it is
run on.
## `apt` Packages installed
The packages `python3` and `python3-venv` are installed from the apt repositories.
## Hub environment
JupyterHub is run from a python3 virtual environment located in `/opt/tljh/hub`. It
uses the system's installed python and is owned by root. It also contains a binary install
of [traefik](http://traefik.io/). This virtual environment is completely managed by TLJH.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/hub
```
:::
## User environment
By default, a `mambaforge` conda environment is installed in `/opt/tljh/user`. This contains
the notebook interface used to launch all users, and the various packages available to all
users. The environment is owned by the `root` user. JupyterHub admins may use
to `sudo -E conda install` or `sudo -E pip install` packages into this environment.
This conda environment is added to `$PATH` for all users started with JupyterHub. If you
are using `ssh` instead, you can activate this environment by running the following:
```bash
source /opt/tljh/user/bin/activate
```
This should let you run various `conda` and `pip` commands. If you run into errors like
`Command 'conda' not found`, try prefixing your command with:
```bash
sudo env PATH=${PATH} <command>
```
By default, `sudo` does not respect any custom environments you have activated. The `env PATH=${PATH}`
'fixes' that.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/user
```
:::
## `tljh-config` symlink
We create a symlink from `/usr/bin/tljh-config` to `/opt/tljh/hub/bin/tljh-config`, so users
can run `sudo tljh-config <something>` from their terminal. While the user environment is added
to users' `$PATH` when they launch through JupyterHub, the hub environment is not. This makes it
hard to access the `tljh-config` command used to change most config parameters. Hence we symlink the
`tljh-config` command to `/usr/bin`, so it is directly accessible with `sudo tljh-config <command>`.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo unlink /usr/bin/tljh-config
```
:::
## `jupyterhub_config.d` directory for custom configuration snippets
Any files in /opt/tljh/config/jupyterhub_config.d that end in .py and are a valid
JupyterHub configuration will be loaded after any of the config options specified
with tljh-config are loaded.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/config
```
:::
## Systemd Units
TLJH places 2 systemd units on your computer. They all start on system startup.
1. `jupyterhub.service` - starts the JupyterHub service.
2. `traefik.service` - starts traefik proxy that manages HTTPS
In addition, each running Jupyter user gets their own systemd unit of the name `jupyter-<username>`.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
# stop the services
systemctl stop jupyterhub.service
systemctl stop traefik.service
systemctl stop jupyter-<username>
# disable the services
systemctl disable jupyterhub.service
systemctl disable traefik.service
# run this command for all the Jupyter users
systemctl disable jupyter-<username>
# remove the systemd unit
rm /etc/systemd/system/jupyterhub.service
rm /etc/systemd/system/traefik.service
# reset the state of all units
systemctl daemon-reload
systemctl reset-failed
```
:::
## State files
TLJH places 3 `jupyterhub.service` and 4 `traefik.service` state files in `/opt/tljh/state`.
These files save the state of JupyterHub and Traefik services and are meant
to be used and modified solely by these services.
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm -rf /opt/tljh/state
```
:::
## Progress page files
If you ran the TLJH installer with the `--show-progress-page` flag, then two files have been
added to your system to help serving the progress page:
- `/var/run/index.html` - the main progress page
- `/var/run/favicon.ico` - the JupyterHub icon
:::{note}
If you try to remove TLJH, revert this action using:
```bash
sudo rm /var/run/index.html
sudo rm /var/run/favicon.ico
```
:::
## User groups
TLJH creates two user groups when installed:
1. `jupyterhub-users` contains all users managed by this JupyterHub
2. `jupyterhub-admins` contains all users with admin rights managed by this JupyterHub.
When a new JupyterHub user logs in, a unix user is created for them. The unix user is always added
to the `jupyterhub-users` group. If the user is an admin, they are added to the `jupyterhub-admins`
group whenever they start / stop their notebook server.
If you uninstall TLJH, you should probably remove all user accounts associated with both these
user groups, and then remove the groups themselves. You might have to archive or delete the home
directories of these users under `/home/`.
:::{note}
If you try to remove TLJH, in order to remove a user and its home directory, use:
```bash
sudo userdel -r <user>
```
:::
Keep in mind that the files located in other parts of the file system
will have to be searched for and deleted manually.
:::{note}
To remove the user groups units:
```bash
sudo delgroup jupyterhub-users
sudo delgroup jupyterhub-admins
# remove jupyterhub-admins from the sudoers group
sudo rm /etc/sudoers.d/jupyterhub-admins
```
:::
## Passwordless `sudo` for JupyterHub admins
`/etc/sudoers.d/jupyterhub-admins` is created to provide passwordless sudo for all JupyterHub
admins. We also set it up to inherit `$PATH` with `sudo -E`, to more easily call `conda`,
`pip`, etc.
## Removing TLJH
If trying to wipe out a fresh TLJH installation, follow the instructions on how to revert
each specific modification the TLJH installer does to the system.
:::{note}
If using a VM, the recommended way to remove TLJH is destroying the VM and start fresh.
:::
:::{warning}
Completely uninstalling TLJH after it has been used is a difficult task because it's
highly coupled to how the system changed after it has been used and modified by the users.
Thus, we cannot provide instructions on how to proceed in this case.
:::

214
docs/topic/installer-actions.rst
View File

@@ -1,214 +0,0 @@
.. _topic/installer-actions:
===========================
What does the installer do?
===========================
This document details what exactly the installer does to the machine it is
run on.
``apt`` Packages installed
==========================
The packages ``python3`` and ``python3-venv`` are installed from the apt repositories.
Hub environment
===============
JupyterHub is run from a python3 virtual environment located in ``/opt/tljh/hub``. It
uses the system's installed python and is owned by root. It also contains a binary install
of `traefik <http://traefik.io/>`_. This virtual environment is completely managed by TLJH.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/hub
User environment
================
By default, a ``mambaforge`` conda environment is installed in ``/opt/tljh/user``. This contains
the notebook interface used to launch all users, and the various packages available to all
users. The environment is owned by the ``root`` user. JupyterHub admins may use
to ``sudo -E conda install`` or ``sudo -E pip install`` packages into this environment.
This conda environment is added to ``$PATH`` for all users started with JupyterHub. If you
are using ``ssh`` instead, you can activate this environment by running the following:
.. code-block:: bash
source /opt/tljh/user/bin/activate
This should let you run various ``conda`` and ``pip`` commands. If you run into errors like
``Command 'conda' not found``, try prefixing your command with:
.. code-block:: bash
sudo env PATH=${PATH} <command>
By default, ``sudo`` does not respect any custom environments you have activated. The ``env PATH=${PATH}``
'fixes' that.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/user
``tljh-config`` symlink
========================
We create a symlink from ``/usr/bin/tljh-config`` to ``/opt/tljh/hub/bin/tljh-config``, so users
can run ``sudo tljh-config <something>`` from their terminal. While the user environment is added
to users' ``$PATH`` when they launch through JupyterHub, the hub environment is not. This makes it
hard to access the ``tljh-config`` command used to change most config parameters. Hence we symlink the
``tljh-config`` command to ``/usr/bin``, so it is directly accessible with ``sudo tljh-config <command>``.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo unlink /usr/bin/tljh-config
``jupyterhub_config.d`` directory for custom configuration snippets
===================================================================
Any files in /opt/tljh/config/jupyterhub_config.d that end in .py and are a valid
JupyterHub configuration will be loaded after any of the config options specified
with tljh-config are loaded.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/config
Systemd Units
=============
TLJH places 2 systemd units on your computer. They all start on system startup.
#. ``jupyterhub.service`` - starts the JupyterHub service.
#. ``traefik.service`` - starts traefik proxy that manages HTTPS
In addition, each running Jupyter user gets their own systemd unit of the name ``jupyter-<username>``.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
# stop the services
systemctl stop jupyterhub.service
systemctl stop traefik.service
systemctl stop jupyter-<username>
# disable the services
systemctl disable jupyterhub.service
systemctl disable traefik.service
# run this command for all the Jupyter users
systemctl disable jupyter-<username>
# remove the systemd unit
rm /etc/systemd/system/jupyterhub.service
rm /etc/systemd/system/traefik.service
# reset the state of all units
systemctl daemon-reload
systemctl reset-failed
State files
===========
TLJH places 3 `jupyterhub.service` and 4 `traefik.service` state files in `/opt/tljh/state`.
These files save the state of JupyterHub and Traefik services and are meant
to be used and modified solely by these services.
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm -rf /opt/tljh/state
Progress page files
===================
If you ran the TLJH installer with the `--show-progress-page` flag, then two files have been
added to your system to help serving the progress page:
* ``/var/run/index.html`` - the main progress page
* ``/var/run/favicon.ico`` - the JupyterHub icon
.. note::
If you try to remove TLJH, revert this action using:
.. code-block:: bash
sudo rm /var/run/index.html
sudo rm /var/run/favicon.ico
User groups
===========
TLJH creates two user groups when installed:
#. ``jupyterhub-users`` contains all users managed by this JupyterHub
#. ``jupyterhub-admins`` contains all users with admin rights managed by this JupyterHub.
When a new JupyterHub user logs in, a unix user is created for them. The unix user is always added
to the ``jupyterhub-users`` group. If the user is an admin, they are added to the ``jupyterhub-admins``
group whenever they start / stop their notebook server.
If you uninstall TLJH, you should probably remove all user accounts associated with both these
user groups, and then remove the groups themselves. You might have to archive or delete the home
directories of these users under ``/home/``.
.. note::
If you try to remove TLJH, in order to remove a user and its home directory, use:
.. code-block:: bash
sudo userdel -r <user>
Keep in mind that the files located in other parts of the file system
will have to be searched for and deleted manually.
.. note::
To remove the user groups units:
.. code-block:: bash
sudo delgroup jupyterhub-users
sudo delgroup jupyterhub-admins
# remove jupyterhub-admins from the sudoers group
sudo rm /etc/sudoers.d/jupyterhub-admins
Passwordless ``sudo`` for JupyterHub admins
============================================
``/etc/sudoers.d/jupyterhub-admins`` is created to provide passwordless sudo for all JupyterHub
admins. We also set it up to inherit ``$PATH`` with ``sudo -E``, to more easily call ``conda``,
``pip``, etc.
Removing TLJH
=============
If trying to wipe out a fresh TLJH installation, follow the instructions on how to revert
each specific modification the TLJH installer does to the system.
.. note::
If using a VM, the recommended way to remove TLJH is destroying the VM and start fresh.
.. warning::
Completely uninstalling TLJH after it has been used is a difficult task because it's
highly coupled to how the system changed after it has been used and modified by the users.
Thus, we cannot provide instructions on how to proceed in this case.

21
docs/topic/jupyterhub-configurator.md Normal file
View File

@@ -0,0 +1,21 @@
(topic-jupyterhub-configurator)=
# JupyterHub Configurator
The [JupyterHub configurator](https://github.com/yuvipanda/jupyterhub-configurator) allows admins to change a subset of hub settings via a GUI.
## Enabling the configurator
Because the configurator is under continue development and it might change over time, it is disabled by default in TLJH.
If you want to experiment with it, it can be enabled using `tljh-config`:
```bash
sudo tljh-config set services.configurator.enabled True
sudo tljh-config reload
```
## Accessing the Configurator
After enabling the configurator using `tljh-config`, the service will only be available to hub admins, from within the control panel.
The configurator can be accessed from under `Services` in the top navigation bar. It will ask to authenticate, so it knows the user is an admin.
Once done, the configurator interface will be available.

25
docs/topic/jupyterhub-configurator.rst
View File

@@ -1,25 +0,0 @@
.. _topic/jupyterhub-configurator:
=======================
JupyterHub Configurator
=======================
The `JupyterHub configurator <https://github.com/yuvipanda/jupyterhub-configurator>`_ allows admins to change a subset of hub settings via a GUI.
Enabling the configurator
=========================
Because the configurator is under continue development and it might change over time, it is disabled by default in TLJH.
If you want to experiment with it, it can be enabled using ``tljh-config``:
.. code-block:: bash
sudo tljh-config set services.configurator.enabled True
sudo tljh-config reload
Accessing the Configurator
==========================
After enabling the configurator using ``tljh-config``, the service will only be available to hub admins, from within the control panel.
The configurator can be accessed from under ``Services`` in the top navigation bar. It will ask to authenticate, so it knows the user is an admin.
Once done, the configurator interface will be available.

23
docs/topic/requirements.md Normal file
View File

@@ -0,0 +1,23 @@
(requirements)=
# Server Requirements
## Operating System
We require using Ubuntu >=20.04 as the base operating system for your server.
## Root access
Full `root` access to this server is required. This might be via `sudo`
(recommended) or by direct access to `root` (not recommended!)
## External IP
An external IP allows users on the internet to reach your JupyterHub. Most
VPS / Cloud providers give you a public IP address along with your server. If
you are hosting on a physical machine somewhere, talk to your system administrators
about how to get HTTP traffic from the world into your server.
## CPU / Memory / Disk Space
See how to [](/howto/admin/resource-estimation)

29
docs/topic/requirements.rst
View File

@@ -1,29 +0,0 @@
.. _requirements:
===================
Server Requirements
===================
Operating System
================
We require using Ubuntu >=20.04 as the base operating system for your server.
Root access
===========
Full ``root`` access to this server is required. This might be via ``sudo``
(recommended) or by direct access to ``root`` (not recommended!)
External IP
===========
An external IP allows users on the internet to reach your JupyterHub. Most
VPS / Cloud providers give you a public IP address along with your server. If
you are hosting on a physical machine somewhere, talk to your system administrators
about how to get HTTP traffic from the world into your server.
CPU / Memory / Disk Space
=========================
See how to :ref:`howto/admin/resource-estimation`

61
docs/topic/security.rst → docs/topic/security.md
View File

@@ -1,80 +1,69 @@
=======================
Security Considerations
=======================
# Security Considerations
The Littlest JupyterHub is in beta state & should not be used in security
critical situations. We will try to keep things as secure as possible, but
sometimes trade security for massive gains in convenience. This page contains
information about the security model of The Littlest JupyterHub.
System user accounts
====================
## System user accounts
Each JupyterHub user gets their own Unix user account created when they
first start their server. This protects users from each other, gives them a
home directory at a well known location, and allows sharing based on file system
permissions.
#. The unix user account created for a JupyterHub user named ``<username>`` is
``jupyter-<username>``. This prefix helps prevent clashes with users that
already exist - otherwise a user named ``root`` can trivially gain full root
access to your server. If the username (including the ``jupyter-`` prefix)
1. The unix user account created for a JupyterHub user named `<username>` is
`jupyter-<username>`. This prefix helps prevent clashes with users that
already exist - otherwise a user named `root` can trivially gain full root
access to your server. If the username (including the `jupyter-` prefix)
is longer than 26 characters, it is truncated at 26 characters & a 5 charcter
hash is appeneded to it. This keeps usernames under the linux username limit
of 32 characters while also reducing chances of collision.
#. A home directory is created for the user under ``/home/jupyter-<username>``.
#. The default permission of the home directory is change with ``o-rwx`` (remove
2. A home directory is created for the user under `/home/jupyter-<username>`.
3. The default permission of the home directory is change with `o-rwx` (remove
non-group members the ability to read, write or list files and folders in the
Home directory).
#. No password is set for this unix system user by default. The password used
4. No password is set for this unix system user by default. The password used
to log in to JupyterHub (if using an authenticator that requires a password)
is not related to the unix user's password in any form.
5. All users created by The Littlest JupyterHub are added to the user group
`jupyterhub-users`.
#. All users created by The Littlest JupyterHub are added to the user group
``jupyterhub-users``.
## `sudo` access for admins
``sudo`` access for admins
==========================
JupyterHub admin users are added to the user group ``jupyterhub-admins``,
which is granted complete root access to the whole server with the ``sudo``
JupyterHub admin users are added to the user group `jupyterhub-admins`,
which is granted complete root access to the whole server with the `sudo`
command on the terminal. No password required.
This is a **lot** of power, and they can do pretty much anything they want to
the server - look at other people's work, modify it, break the server in cool &
funky ways, etc. This also means **if an admin's credentials are compromised
funky ways, etc. This also means **if an admin's credentials are compromised
(easy to guess password, password re-use, etc) the entire JupyterHub is compromised.**
Off-boarding users securely
===========================
## Off-boarding users securely
When you delete users from the JupyterHub admin console, their unix user accounts
are **not** removed. This means they might continue to have access to the server
even after you remove them from JupyterHub. Admins should manually remove the user
from the server & archive their home directories as needed. For example, the
following command deletes the unix user associated with the JupyterHub user ``yuvipanda``.
following command deletes the unix user associated with the JupyterHub user `yuvipanda`.
.. code-block:: bash
sudo userdel jupyter-yuvipanda
```bash
sudo userdel jupyter-yuvipanda
```
If the user removed from the server is an admin, extra care must be taken
since they could have modified the system earlier to continue giving them
access.
Per-user ``/tmp``
=================
## Per-user `/tmp`
``/tmp`` is shared by all users in most computing systems, and this has been
`/tmp` is shared by all users in most computing systems, and this has been
a consistent source of security issues. The Littlest JupyterHub gives each
user their own ephemeral ``/tmp`` using the `PrivateTmp <https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateTmp>`_
user their own ephemeral `/tmp` using the [PrivateTmp](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#PrivateTmp)
feature of systemd.
HTTPS
=====
## HTTPS
Any internet-facing JupyterHub should use HTTPS to secure its traffic. For
information on how to use HTTPS with your JupyterHub, see :ref:`howto/admin/https`.
information on how to use HTTPS with your JupyterHub, see [](/howto/admin/https).

246
docs/topic/tljh-config.md Normal file
View File

@@ -0,0 +1,246 @@
(topic-tljh-config)=
# Configuring TLJH with `tljh-config`
`tljh-config` is the commandline program used to make configuration
changes to TLJH.
## Running `tljh-config`
You can run `tljh-config` in two ways:
1. From inside a terminal in JupyterHub while logged in as an admin user.
This method is recommended.
2. By directly calling `/opt/tljh/hub/bin/tljh-config` as root when
logged in to the server via other means (such as SSH). This is an
advanced use case, and not covered much in this guide.
(tljh-set)=
## Set / Unset a configuration property
TLJH's configuration is organized in a nested tree structure. You can
set a particular property with the following command:
```bash
sudo tljh-config set <property-path> <value>
```
where:
1. `<property-path>` is a dot-separated path to the property you want
to set.
2. `<value>` is the value you want to set the property to.
For example, to set the password for the DummyAuthenticator, you
need to set the `auth.DummyAuthenticator.password` property. You would
do so with the following:
```bash
sudo tljh-config set auth.DummyAuthenticator.password mypassword
```
This can only set string and numerical properties, not lists.
To unset a configuration property you can use the following command:
```bash
sudo tljh-config unset <property-path>
```
Unsetting a configuration property removes the property from the configuration
file. If what you want is only to change the property's value, you should use
`set` and overwrite it with the desired value.
Some of the existing `<property-path>` are listed below by categories:
(tljh-base-url)=
### Base URL
> Use `base_url` to determine the base URL used by JupyterHub. This parameter will
> be passed straight to `c.JupyterHub.base_url`.
(tljh-set-auth)=
### Authentication
> Use `auth.type` to determine authenticator to use. All parameters
> in the config under `auth.{auth.type}` will be passed straight to the
> authenticators themselves.
(tljh-set-ports)=
### Ports
> Use `http.port` and `https.port` to set the ports that TLJH will listen on,
> which are 80 and 443 by default. However, if you change these, note that
> TLJH does a lot of other things to the system (with user accounts and sudo
> rules primarily) that might break security assumptions your other
> applications have, so use with extreme caution.
>
> ```bash
> sudo tljh-config set http.port 8080
> sudo tljh-config set https.port 8443
> sudo tljh-config reload proxy
> ```
(tljh-set-user-lists)=
### User Lists
- `users.allowed` takes in usernames to whitelist
- `users.banned` takes in usernames to blacklist
- `users.admin` takes in usernames to designate as admins
```bash
sudo tljh-config add-item users.allowed good-user_1
sudo tljh-config add-item users.allowed good-user_2
sudo tljh-config add-item users.banned bad-user_6
sudo tljh-config add-item users.admin admin-user_0
sudo tljh-config remove-item users.allowed good-user_2
```
(tljh-set-user-limits)=
### User Server Limits
- `limits.memory` Specifies the maximum memory that can be used by each
individual user. By default there is no memory limit. The limit can be
specified as an absolute byte value. You can use
the suffixes K, M, G or T to mean Kilobyte, Megabyte, Gigabyte or Terabyte
respectively. Setting it to `None` disables memory limits.
```bash
sudo tljh-config set limits.memory 4G
```
Even if you want individual users to use as much memory as possible,
it is still good practice to set a memory limit of 80-90% of total
physical memory. This prevents one user from being able to single
handedly take down the machine accidentally by OOMing it.
- `limits.cpu` A float representing the total CPU-cores each user can use.
By default there is no CPU limit.
1 represents one full CPU, 4 represents 4 full CPUs, 0.5 represents
half of one CPU, etc. This value is ultimately converted to a percentage and
rounded down to the nearest integer percentage,
i.e. 1.5 is converted to 150%, 0.125 is converted to 12%, etc.
Setting it to `None` disables CPU limits.
```bash
sudo tljh-config set limits.cpu 2
```
(tljh-set-user-env)=
### User Environment
> `user_environment.default_app` Set default application users are
> launched into. Currently can be set to the following values
> `jupyterlab` or `nteract`
>
> ```bash
> sudo tljh-config set user_environment.default_app jupyterlab
> ```
(tljh-set-extra-user-groups)=
## Extra User Groups
`users.extra_user_groups` is a configuration option that can be used
to automatically add a user to a specific group. By default, there are
no extra groups defined.
Users can be "paired" with the desired, **existing** groups using:
- `tljh-config set`, if only one user is to be added to the
desired group:
```bash
tljh-config set users.extra_user_groups.group1 user1
```
- `tljh-config add-item`, if multiple users are to be added to
the group:
```bash
tljh-config add-item users.extra_user_groups.group1 user1
tljh-config add-item users.extra_user_groups.group1 user2
```
(tljh-view-conf)=
## View current configuration
To see the current configuration, you can run the following command:
```bash
sudo tljh-config show
```
This will print the current configuration of your TLJH. This is very
useful when asking for support!
(tljh-reload-hub)=
## Reloading JupyterHub to apply configuration
After modifying the configuration, you need to reload JupyterHub for
it to take effect. You can do so with:
```bash
sudo tljh-config reload
```
This should not affect any running users. The JupyterHub will be
restarted and loaded with the new configuration.
(tljh-edit-yaml)=
## Advanced: `config.yaml`
`tljh-config` is a simple program that modifies the contents of the
`config.yaml` file located at `/opt/tljh/config/config.yaml`. `tljh-config`
is the recommended method of editing / viewing configuration since editing
YAML by hand in a terminal text editor is a large source of errors.
To learn more about the `tljh-config` usage, you can use the `--help` flag.
The `--help` flag can be used either directly, to get information about the
general usage of the command or after a positional argument. For example, using
it after an argument like `remove-item` gives information about this specific command.
```bash
sudo tljh-config --help
usage: tljh-config [-h] [--config-path CONFIG_PATH] {show,unset,set,add-item,remove-item,reload} ...
positional arguments:
{show,unset,set,add-item,remove-item,reload}
show Show current configuration
unset Unset a configuration property
set Set a configuration property
add-item Add a value to a list for a configuration property
remove-item Remove a value from a list for a configuration property
reload Reload a component to apply configuration change
optional arguments:
-h, --help show this help message and exit
--config-path CONFIG_PATH
Path to TLJH config.yaml file
```
```bash
sudo tljh-config remove-item --help
usage: tljh-config remove-item [-h] key_path value
positional arguments:
key_path Dot separated path to configuration key to remove value from
value Value to remove from key_path
optional arguments:
-h, --help show this help message and exit
```

271
docs/topic/tljh-config.rst
View File

@@ -1,271 +0,0 @@
.. _topic/tljh-config:
=====================================
Configuring TLJH with ``tljh-config``
=====================================
``tljh-config`` is the commandline program used to make configuration
changes to TLJH.
Running ``tljh-config``
=======================
You can run ``tljh-config`` in two ways:
#. From inside a terminal in JupyterHub while logged in as an admin user.
This method is recommended.
#. By directly calling ``/opt/tljh/hub/bin/tljh-config`` as root when
logged in to the server via other means (such as SSH). This is an
advanced use case, and not covered much in this guide.
.. _tljh-set:
Set / Unset a configuration property
====================================
TLJH's configuration is organized in a nested tree structure. You can
set a particular property with the following command:
.. code-block:: bash
sudo tljh-config set <property-path> <value>
where:
#. ``<property-path>`` is a dot-separated path to the property you want
to set.
#. ``<value>`` is the value you want to set the property to.
For example, to set the password for the DummyAuthenticator, you
need to set the ``auth.DummyAuthenticator.password`` property. You would
do so with the following:
.. code-block:: bash
sudo tljh-config set auth.DummyAuthenticator.password mypassword
This can only set string and numerical properties, not lists.
To unset a configuration property you can use the following command:
.. code-block:: bash
sudo tljh-config unset <property-path>
Unsetting a configuration property removes the property from the configuration
file. If what you want is only to change the property's value, you should use
``set`` and overwrite it with the desired value.
Some of the existing ``<property-path>`` are listed below by categories:
.. _tljh-base_url:
Base URL
--------
Use ``base_url`` to determine the base URL used by JupyterHub. This parameter will
be passed straight to ``c.JupyterHub.base_url``.
.. _tljh-set-auth:
Authentication
--------------
Use ``auth.type`` to determine authenticator to use. All parameters
in the config under ``auth.{auth.type}`` will be passed straight to the
authenticators themselves.
.. _tljh-set-ports:
Ports
-----
Use ``http.port`` and ``https.port`` to set the ports that TLJH will listen on,
which are 80 and 443 by default. However, if you change these, note that
TLJH does a lot of other things to the system (with user accounts and sudo
rules primarily) that might break security assumptions your other
applications have, so use with extreme caution.
.. code-block:: bash
sudo tljh-config set http.port 8080
sudo tljh-config set https.port 8443
sudo tljh-config reload proxy
.. _tljh-set-user-lists:
User Lists
----------
* ``users.allowed`` takes in usernames to whitelist
* ``users.banned`` takes in usernames to blacklist
* ``users.admin`` takes in usernames to designate as admins
.. code-block:: bash
sudo tljh-config add-item users.allowed good-user_1
sudo tljh-config add-item users.allowed good-user_2
sudo tljh-config add-item users.banned bad-user_6
sudo tljh-config add-item users.admin admin-user_0
sudo tljh-config remove-item users.allowed good-user_2
.. _tljh-set-user-limits:
User Server Limits
------------------
* ``limits.memory`` Specifies the maximum memory that can be used by each
individual user. By default there is no memory limit. The limit can be
specified as an absolute byte value. You can use
the suffixes K, M, G or T to mean Kilobyte, Megabyte, Gigabyte or Terabyte
respectively. Setting it to ``None`` disables memory limits.
.. code-block:: bash
sudo tljh-config set limits.memory 4G
Even if you want individual users to use as much memory as possible,
it is still good practice to set a memory limit of 80-90% of total
physical memory. This prevents one user from being able to single
handedly take down the machine accidentally by OOMing it.
* ``limits.cpu`` A float representing the total CPU-cores each user can use.
By default there is no CPU limit.
1 represents one full CPU, 4 represents 4 full CPUs, 0.5 represents
half of one CPU, etc. This value is ultimately converted to a percentage and
rounded down to the nearest integer percentage,
i.e. 1.5 is converted to 150%, 0.125 is converted to 12%, etc.
Setting it to ``None`` disables CPU limits.
.. code-block:: bash
sudo tljh-config set limits.cpu 2
.. _tljh-set-user-env:
User Environment
----------------
``user_environment.default_app`` Set default application users are
launched into. Currently can be set to the following values
``jupyterlab`` or ``nteract``
.. code-block:: bash
sudo tljh-config set user_environment.default_app jupyterlab
.. _tljh-set-extra-user-groups:
Extra User Groups
=================
``users.extra_user_groups`` is a configuration option that can be used
to automatically add a user to a specific group. By default, there are
no extra groups defined.
Users can be "paired" with the desired, **existing** groups using:
* ``tljh-config set``, if only one user is to be added to the
desired group:
.. code-block:: bash
tljh-config set users.extra_user_groups.group1 user1
* ``tljh-config add-item``, if multiple users are to be added to
the group:
.. code-block:: bash
tljh-config add-item users.extra_user_groups.group1 user1
tljh-config add-item users.extra_user_groups.group1 user2
.. _tljh-view-conf:
View current configuration
==========================
To see the current configuration, you can run the following command:
.. code-block:: bash
sudo tljh-config show
This will print the current configuration of your TLJH. This is very
useful when asking for support!
.. _tljh-reload-hub:
Reloading JupyterHub to apply configuration
===========================================
After modifying the configuration, you need to reload JupyterHub for
it to take effect. You can do so with:
.. code-block:: bash
sudo tljh-config reload
This should not affect any running users. The JupyterHub will be
restarted and loaded with the new configuration.
.. _tljh-edit-yaml:
Advanced: ``config.yaml``
=========================
``tljh-config`` is a simple program that modifies the contents of the
``config.yaml`` file located at ``/opt/tljh/config/config.yaml``. ``tljh-config``
is the recommended method of editing / viewing configuration since editing
YAML by hand in a terminal text editor is a large source of errors.
To learn more about the ``tljh-config`` usage, you can use the ``--help`` flag.
The ``--help`` flag can be used either directly, to get information about the
general usage of the command or after a positional argument. For example, using
it after an argument like ``remove-item`` gives information about this specific command.
.. code-block:: bash
sudo tljh-config --help
usage: tljh-config [-h] [--config-path CONFIG_PATH] {show,unset,set,add-item,remove-item,reload} ...
positional arguments:
{show,unset,set,add-item,remove-item,reload}
show Show current configuration
unset Unset a configuration property
set Set a configuration property
add-item Add a value to a list for a configuration property
remove-item Remove a value from a list for a configuration property
reload Reload a component to apply configuration change
optional arguments:
-h, --help show this help message and exit
--config-path CONFIG_PATH
Path to TLJH config.yaml file
.. code-block:: bash
sudo tljh-config remove-item --help
usage: tljh-config remove-item [-h] key_path value
positional arguments:
key_path Dot separated path to configuration key to remove value from
value Value to remove from key_path
optional arguments:
-h, --help show this help message and exit

26
docs/topic/whentouse.rst → docs/topic/whentouse.md
View File

@@ -1,34 +1,32 @@
.. _topic/whentouse:
(topic-whentouse)=
===================================
When to use The Littlest JupyterHub
===================================
# When to use The Littlest JupyterHub
This page is a brief guide to determining whether to use The Littlest JupyterHub
(TLJH) or `Zero to JupyterHub for Kubernetes <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_ (Z2JH).
(TLJH) or [Zero to JupyterHub for Kubernetes](https://zero-to-jupyterhub.readthedocs.io/en/latest/) (Z2JH).
Many of these ideas were first laid out in a
`blog post announcing TLJH <http://words.yuvi.in/post/the-littlest-jupyterhub/>`_.
[blog post announcing TLJH](http://words.yuvi.in/post/the-littlest-jupyterhub/).
`**The Littlest JupyterHub (TLJH)** <https://the-littlest-jupyterhub.readthedocs.io/en/latest/>`_ is an opinionated and pre-configured distribution
[\*\*The Littlest JupyterHub (TLJH)\*\*](https://the-littlest-jupyterhub.readthedocs.io/en/latest/) is an opinionated and pre-configured distribution
to deploy a JupyterHub on a **single machine** (in the cloud or on your own hardware).
It is designed to be a more lightweight and maintainable solution
for use-cases where size, scalability, and cost-savings are not a huge concern.
`**Zero to JupyterHub on Kubernetes** <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_ allows you
[\*\*Zero to JupyterHub on Kubernetes\*\*](https://zero-to-jupyterhub.readthedocs.io/en/latest/) allows you
to deploy JupyterHub on **Kubernetes**. This allows JupyterHub to scale to many thousands
of users, to flexibly grow/shrink the size of resources it needs, and to use
container technology in administering user sessions.
When to use TLJH vs. Z2JH
=========================
## When to use TLJH vs. Z2JH
The choice between TLJH and Z2JH ultimately comes down to only a few questions:
1. Do you want your hub and all users to live on a **single, larger machine** vs. spreading users on a **cluster of smaller machines** that are scaled up or down?
* If you can use a single machine, we recommend **The Littlest JupyterHub**.
* If you wish to use multiple machines, we recommend **Zero to JupyterHub for Kubernetes**.
- If you can use a single machine, we recommend **The Littlest JupyterHub**.
- If you wish to use multiple machines, we recommend **Zero to JupyterHub for Kubernetes**.
2. Do you **need to use container technology**?
* If no, we recommend **The Littlest JupyterHub**.
* If yes, we recommend **Zero to JupyterHub for Kubernetes**.
- If no, we recommend **The Littlest JupyterHub**.
- If yes, we recommend **Zero to JupyterHub for Kubernetes**.

26
docs/troubleshooting/index.rst → docs/troubleshooting/index.md
View File

@@ -1,25 +1,25 @@
===============
Troubleshooting
===============
# Troubleshooting
In time, all systems have issues that need to be debugged. Troubleshooting
guides help you find what is broken & hopefully fix it.
.. toctree::
:titlesonly:
:caption: Troubleshooting
```{toctree}
:caption: Troubleshooting
:titlesonly: true
logs
restart
logs
restart
```
Often, your issues are not related to TLJH itself but to the cloud provider
your server is running on. We have some documentation on common issues you
might run into with various providers and how to fix them. We welcome contributions
here to better support your favorite provider!
.. toctree::
:titlesonly:
```{toctree}
:titlesonly: true
providers/google
providers/amazon
providers/custom
providers/google
providers/amazon
providers/custom
```

105
docs/troubleshooting/logs.md Normal file
View File

@@ -0,0 +1,105 @@
(troubleshooting-logs)=
# Looking at Logs
**Logs** are extremely useful in piecing together what went wrong when things go wrong.
They contain a forensic record of what individual pieces of software were doing
before things went bad, and can help us understand the problem so we can fix it.
TLJH collects logs from JupyterHub, Traefik Proxy, & from each individual
user's notebook server. All the logs are accessible via [journalctl](https://www.freedesktop.org/software/systemd/man/journalctl.html).
The installer also writes logs to disk, to help with cases where the
installer did not succeed.
:::{warning}
If you are providing a snippet from the logs to someone else to help debug
a problem you might have, be careful to redact any private information (such
as usernames) from the snippet first!
:::
(troubleshooting-logs-installer)=
## Installer Logs
The JupyterHub installer writes log messages to `/opt/tljh/installer.log`.
This is very useful if the installation fails for any reason.
(troubleshoot-logs-jupyterhub)=
## JupyterHub Logs
JupyterHub is responsible for user authentication, & starting / stopping user
notebook servers. When there is a general systemic issue with JupyterHub (rather
than a specific issue with a particular user's notebook), looking at the JupyterHub
logs is a great first step.
```bash
sudo journalctl -u jupyterhub
```
This command displays logs from JupyterHub itself. See [](#journalctl-tips)
for tips on navigating the logs.
(troubleshooting-logs-traefik)=
## Traefik Proxy Logs
[traefik](https://traefik.io/) redirects traffic to JupyterHub / user notebook servers
as necessary & handles HTTPS. Look at this if all you can see in your browser
is one line cryptic error messages, or if you are having trouble with HTTPS.
```bash
sudo journalctl -u traefik
```
This command displays logs from Traefik. See [](#journalctl-tips)
for tips on navigating the logs.
## User Server Logs
Each user gets their own notebook server, and this server also produces logs.
Looking at these can be useful when a user can launch their server but run into
problems after that.
```bash
sudo journalctl -u jupyter-<name-of-user>
```
This command displays logs from the given user's notebook server. You can get a
list of all users from the "users" button at the top-right of the Admin page.
See [](#journalctl-tips) for tips on navigating the logs.
(journalctl-tips)=
## journalctl tips
`journalctl` has a lot of options to make your life as an administrator
easier. Here are some very basic tips on effective `journalctl` usage.
1. When looking at full logs (via `sudo journalctl -u <some-name>`), the output
usually does not fit into one screen. Hence, it is _paginated_ with
[less](<https://en.wikipedia.org/wiki/Less_(Unix)>). This allows you to
scroll up / down, search for specific words, etc. Some common keyboard shortcuts
are:
- Arrow keys to move up / down / left / right
- `G` to navigate to the end of the logs
- `g` to navigate to the start of the logs
- `/` followed by a string to search for & `enter` key to search the logs
from current position on screen to the end of the logs. If there are multiple
results, you can use `n` key to jump to the next search result. Use `?`
instead of `/` to search backwards from current position
- `q` or `Ctrl + C` to exit
There are plenty of [other commands & options](https://linux.die.net/man/1/less)
to explore if you wish.
2. Add `-f` to any `journalctl` command to view live logging output
that updates as new log lines are written. This is extremely useful when
actively debugging an issue.
For example, to watch live logs of JupyterHub, you can run:
```bash
sudo journalctl -u jupyterhub -f
```

112
docs/troubleshooting/logs.rst
View File

@@ -1,112 +0,0 @@
.. _troubleshooting/logs:
===============
Looking at Logs
===============
**Logs** are extremely useful in piecing together what went wrong when things go wrong.
They contain a forensic record of what individual pieces of software were doing
before things went bad, and can help us understand the problem so we can fix it.
TLJH collects logs from JupyterHub, Traefik Proxy, & from each individual
user's notebook server. All the logs are accessible via `journalctl <https://www.freedesktop.org/software/systemd/man/journalctl.html>`_.
The installer also writes logs to disk, to help with cases where the
installer did not succeed.
.. warning::
If you are providing a snippet from the logs to someone else to help debug
a problem you might have, be careful to redact any private information (such
as usernames) from the snippet first!
.. _troubleshooting/logs#installer:
Installer Logs
==============
The JupyterHub installer writes log messages to ``/opt/tljh/installer.log``.
This is very useful if the installation fails for any reason.
.. _troubleshoot_logs_jupyterhub:
JupyterHub Logs
===============
JupyterHub is responsible for user authentication, & starting / stopping user
notebook servers. When there is a general systemic issue with JupyterHub (rather
than a specific issue with a particular user's notebook), looking at the JupyterHub
logs is a great first step.
.. code-block:: bash
sudo journalctl -u jupyterhub
This command displays logs from JupyterHub itself. See :ref:`journalctl_tips`
for tips on navigating the logs.
.. _troubleshooting/logs/traefik:
Traefik Proxy Logs
==================
`traefik <https://traefik.io/>`_ redirects traffic to JupyterHub / user notebook servers
as necessary & handles HTTPS. Look at this if all you can see in your browser
is one line cryptic error messages, or if you are having trouble with HTTPS.
.. code-block:: bash
sudo journalctl -u traefik
This command displays logs from Traefik. See :ref:`journalctl_tips`
for tips on navigating the logs.
User Server Logs
================
Each user gets their own notebook server, and this server also produces logs.
Looking at these can be useful when a user can launch their server but run into
problems after that.
.. code-block:: bash
sudo journalctl -u jupyter-<name-of-user>
This command displays logs from the given user's notebook server. You can get a
list of all users from the "users" button at the top-right of the Admin page.
See :ref:`journalctl_tips` for tips on navigating the logs.
.. _journalctl_tips:
journalctl tips
===============
``journalctl`` has a lot of options to make your life as an administrator
easier. Here are some very basic tips on effective ``journalctl`` usage.
1. When looking at full logs (via ``sudo journalctl -u <some-name>``), the output
usually does not fit into one screen. Hence, it is *paginated* with
`less <https://en.wikipedia.org/wiki/Less_(Unix)>`_. This allows you to
scroll up / down, search for specific words, etc. Some common keyboard shortcuts
are:
* Arrow keys to move up / down / left / right
* ``G`` to navigate to the end of the logs
* ``g`` to navigate to the start of the logs
* ``/`` followed by a string to search for & ``enter`` key to search the logs
from current position on screen to the end of the logs. If there are multiple
results, you can use ``n`` key to jump to the next search result. Use ``?``
instead of ``/`` to search backwards from current position
* ``q`` or ``Ctrl + C`` to exit
There are plenty of `other commands & options <https://linux.die.net/man/1/less>`_
to explore if you wish.
2. Add ``-f`` to any ``journalctl`` command to view live logging output
that updates as new log lines are written. This is extremely useful when
actively debugging an issue.
For example, to watch live logs of JupyterHub, you can run:
.. code-block:: bash
sudo journalctl -u jupyterhub -f

26
docs/troubleshooting/providers/amazon.md Normal file
View File

@@ -0,0 +1,26 @@
# Troubleshooting issues on Amazon Web Services
This is an incomplete list of issues people have run into when running
TLJH on Amazon Web Services (AWS), and how they have fixed them!
## 'Connection Refused' error after restarting server
If you restarted your server from the EC2 Management Console & then try to access
your JupyterHub from a browser, you might get a **Connection Refused** error.
This is most likely because the **External IP** of your server has changed.
Check the **IPv4 Public IP** dislayed in the bottom of the `EC2 Management Console`
screen for that instance matches the IP you are trying to access. If you have a
domain name pointing to the IP address, you might have to change it to point to
the new correct IP.
You can prevent public IP changes by [associating a static IP](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)
with your server. In the Amazon Web Services ecosystem, the public static IP
addresses are handled under `Elastic IP addresses` category of AWS; these
addresses are tied to the overall AWS account. [This guide](https://dzone.com/articles/assign-fixed-ip-aws-ec2) might be helpful. Notice
there can be a cost to this. Although [the guide](https://dzone.com/articles/assign-fixed-ip-aws-ec2) is outdated (generally
half that [price now](https://aws.amazon.com/ec2/pricing/on-demand/#Elastic_IP_Addresses)),
Amazon describes [here](https://aws.amazon.com/premiumsupport/knowledge-center/elastic-ip-charges/)
how the Elastic IP address feature is free when associated with a running
instance, but that you'll be charged by the hour for maintaining that specific
IP address when it isn't associated with a running instance.

32
docs/troubleshooting/providers/amazon.rst
View File

@@ -1,32 +0,0 @@
=============================================
Troubleshooting issues on Amazon Web Services
=============================================
This is an incomplete list of issues people have run into when running
TLJH on Amazon Web Services (AWS), and how they have fixed them!
'Connection Refused' error after restarting server
==================================================
If you restarted your server from the EC2 Management Console & then try to access
your JupyterHub from a browser, you might get a **Connection Refused** error.
This is most likely because the **External IP** of your server has changed.
Check the **IPv4 Public IP** dislayed in the bottom of the `EC2 Management Console`
screen for that instance matches the IP you are trying to access. If you have a
domain name pointing to the IP address, you might have to change it to point to
the new correct IP.
You can prevent public IP changes by `associating a static IP
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html>`_
with your server. In the Amazon Web Services ecosystem, the public static IP
addresses are handled under `Elastic IP addresses` category of AWS; these
addresses are tied to the overall AWS account. `This guide
<https://dzone.com/articles/assign-fixed-ip-aws-ec2>`_ might be helpful. Notice
there can be a cost to this. Although `the guide
<https://dzone.com/articles/assign-fixed-ip-aws-ec2>`_ is outdated (generally
half that `price now <https://aws.amazon.com/ec2/pricing/on-demand/#Elastic_IP_Addresses>`_),
Amazon describes `here <https://aws.amazon.com/premiumsupport/knowledge-center/elastic-ip-charges/>`_
how the Elastic IP address feature is free when associated with a running
instance, but that you'll be charged by the hour for maintaining that specific
IP address when it isn't associated with a running instance.

27
docs/troubleshooting/providers/custom.rst → docs/troubleshooting/providers/custom.md
View File

@@ -1,8 +1,6 @@
.. _troubleshooting/providers/custom:
(troubleshooting-providers-custom)=
=========================================
Troubleshooting issues on your own server
=========================================
# Troubleshooting issues on your own server
This is an incomplete list of issues people have run into
when installing TLJH on their own servers, and ways they
@@ -11,23 +9,22 @@ Before trying any of them, also consider whether turning your machine on and off
and/or deleting the VM and starting over could solve the problem;
it has done so on a surprisingly high number of occasions!
Outgoing HTTP proxy required
============================
## Outgoing HTTP proxy required
If your server is behind a firewall that requires a HTTP proxy to reach
the internet, run these commands before running the installer
.. code-block:: bash
```bash
export http_proxy=<your_proxy-server>
```
export http_proxy=<your_proxy-server>
HTTPS certificate interception
==============================
## HTTPS certificate interception
If your server is behind a firewall that intercepts HTTPS requests
and re-signs them, you might have to explicitly tell TLJH which
certificates to use.
.. code::
export REQUESTS_CA_BUNDLE=</directory/with/your/ssl/certificates>
sudo npm config set cafile=</directory/with/your/ssl/certificates>
```
export REQUESTS_CA_BUNDLE=</directory/with/your/ssl/certificates>
sudo npm config set cafile=</directory/with/your/ssl/certificates>
```

17
docs/troubleshooting/providers/google.md Normal file
View File

@@ -0,0 +1,17 @@
# Troubleshooting issues on Google Cloud
This is an incomplete list of issues people have run into when running
TLJH on Google Cloud, and how they have fixed them!
## 'Connection Refused' error after restarting server
If you restarted your server from the Google Cloud console & then try to access
your JupyterHub from a browser, you might get a **Connection Refused** error.
This is most likely because the **External IP** of your server has changed.
Check the **External IP** in the [Google Cloud Console -> Compute Engine -> VM instances](https://console.cloud.google.com/compute/instances) screen
matches the IP you are trying to access. If you have a domain name pointing to the
IP address, you might have to change it to point to the new correct IP.
You can prevent External IP changes by [reserving the static IP](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip)
your server is using.

22
docs/troubleshooting/providers/google.rst
View File

@@ -1,22 +0,0 @@
======================================
Troubleshooting issues on Google Cloud
======================================
This is an incomplete list of issues people have run into when running
TLJH on Google Cloud, and how they have fixed them!
'Connection Refused' error after restarting server
==================================================
If you restarted your server from the Google Cloud console & then try to access
your JupyterHub from a browser, you might get a **Connection Refused** error.
This is most likely because the **External IP** of your server has changed.
Check the **External IP** in the `Google Cloud Console -> Compute Engine -> VM instances
<https://console.cloud.google.com/compute/instances>`_ screen
matches the IP you are trying to access. If you have a domain name pointing to the
IP address, you might have to change it to point to the new correct IP.
You can prevent External IP changes by `reserving the static IP
<https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip>`_
your server is using.

27
docs/troubleshooting/restart.md Normal file
View File

@@ -0,0 +1,27 @@
# Stopping and Restarting the JupyterHub Server
The user can **stop** the JupyterHub server using:
```console
$ systemctl stop jupyterhub.service
```
:::{warning}
Keep in mind that other services that may also require stopping:
- The user's Jupyter server: jupyter-username.service
- traefik.service
:::
The user may **restart** JupyterHub and Traefik services by running:
```console
$ sudo tljh-config reload proxy
```
This calls systemctl and restarts Traefik. The user may call systemctl and restart only the JupyterHub using the command:
```console
$ sudo tljh-config reload hub
```

29
docs/troubleshooting/restart.rst
View File

@@ -1,29 +0,0 @@
=============================================
Stopping and Restarting the JupyterHub Server
=============================================
The user can **stop** the JupyterHub server using:
.. code-block:: console
$ systemctl stop jupyterhub.service
.. warning::
Keep in mind that other services that may also require stopping:
* The user's Jupyter server: jupyter-username.service
* Traefik.service
The user may **restart** JupyterHub and Traefik services by running:
.. code-block:: console
$ sudo tljh-config reload proxy
This calls systemctl and restarts Traefik. The user may call systemctl and restart only the JupyterHub using the command:
.. code-block:: console
$ sudo tljh-config reload hub