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

adopt myst

Browse Source 
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
2023-03-27 09:31:02 +02:00
parent a5e72046ab
commit de36cfc116
96 changed files with 4131 additions and 4491 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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 {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.
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
{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
```
```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 {ref}`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>`.
- {ref}`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
{ref}`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 {ref}`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:
```
#!/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`.
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 {ref}`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.
:::
1. 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 {ref}`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 {ref}`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 {ref}`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 {ref}`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 {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:
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 {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`.
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 {ref}`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
{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:
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 {ref}`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
{ref}`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 {ref}`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`.