mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
adopt myst
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
100
docs/howto/admin/admin-users.md
Normal file
100
docs/howto/admin/admin-users.md
Normal 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.
|
||||
@@ -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
56
docs/howto/admin/enable-extensions.md
Normal 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
|
||||
```
|
||||
@@ -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
118
docs/howto/admin/https.md
Normal 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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
82
docs/howto/admin/systemd.md
Normal 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)
|
||||
@@ -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>`_
|
||||
Reference in New Issue
Block a user