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

updating content from zexuan's user test

Browse Source
This commit is contained in:
Chris Holdgraf
2018-08-10 10:09:24 -07:00
committed by yuvipanda
parent 258e350abc
commit 2181947f83
21 changed files with 468 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/howto/admin/admin-users.rst Normal file
View File

@@ -0,0 +1,101 @@
.. _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 logni 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. 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 -E tljh-config add-item users.admin <username>
sudo -E 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 -E tljh-config remove-item users.admin <username>
sudo -E 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.

79
docs/howto/admin/https.rst Normal file
View File

@@ -0,0 +1,79 @@
.. _howto/admin/https:
============
Enable HTTPS
============
Every JupyterHub deployment should enable HTTPS!
HTTPS encrypts traffic so that usernames and passwords and other potentially 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 <manual_https>` with your own TLS key and certificate.
If you don't know how to do that,
then :ref:`Let's Encrypt <letsencrypt>` is probably the right path for you.
.. _letsencrypt:
Automatic HTTPS with Let's Encrypt
==================================
To enable HTTPS via letsencrypt::
sudo -E tljh-config set https.enabled true
sudo -E tljh-config set https.letsencrypt.email you@example.com
sudo -E 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 -E 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 -E 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.
.. _manual_https:
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 -E tljh-config set https.enabled true
sudo -E tljh-config set https.tls.key /etc/mycerts/mydomain.key
sudo -E tljh-config set https.tls.cert /etc/mycerts/mydomain.cert
Once you have loaded this, your config should look like::
sudo -E 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 -E tljh-config reload proxy
and now access your Hub securely at https://yourhub.yourdomain.edu.

15
docs/howto/admin/nbresuse.rst Normal file
View File

@@ -0,0 +1,15 @@
.. _howto/admin/nbresuse:
=======================
Check your memory usage
=======================
The `nbresuse <https://github.com/yuvipanda/nbresuse>`_ 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 nbresuse

82
docs/howto/admin/resource-estimation.rst Normal file
View File

@@ -0,0 +1,82 @@
.. _howto/resource-estimation:
===================================
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 is usually the biggest determinant of server size in most JupyterHub
installations.
.. math::
Server Memory Recommended = (Maximum concurrent users \times Maximum memory allowed per user) + 128MB
The ``128MB`` is overhead for TLJH and related services. **Server Memory Recommended**
is the amount of Memory (RAM) the server you aquire should have - we recommend
erring on the side of 'more Memory'. The other terms are explained below.
Maximum concurrent users
------------------------
Even if your class has 100 students, most of them will not be using the JupyterHub
actively at an 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
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
-------------------------------
Depending on what kinda 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/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.
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::
Server CPU Recommended = (Maximum concurrent users \times Maximum CPU usage per user) + 0.2
The ``0.2`` is overhead for TLJH and related services. **Server CPU Recommended**
is the amount of CPU the server you acquire should have. We recommend using
the same process used to estimate Memory required for estimating CPU required.
Disk space
==========
Unlike Memory & CPU, disk space is predicated on **total** number of users,
rather than **maximum concurrent** users.
.. math::
Server Disk Size Recommended = (Total \times Maximum disk usage per user) + 2GB
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 -
active users will be logged out, but otherwise usually nothing bad happens.