mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-18 15:33:02 +00:00
Merge branch 'main' into patch-1
This commit is contained in:
Melissa Kirabo
12
.github/workflows/release.yml
vendored
12
.github/workflows/release.yml
vendored
@@ -108,10 +108,10 @@ jobs:
|
||||
# https://github.com/docker/build-push-action/tree/v2.4.0#usage
|
||||
# https://github.com/docker/build-push-action/blob/v2.4.0/docs/advanced/multi-platform.md
|
||||
- name: Set up QEMU (for docker buildx)
|
||||
uses: docker/setup-qemu-action@8b122486cedac8393e77aa9734c3528886e4a1a8 # associated tag: v1.0.2
|
||||
uses: docker/setup-qemu-action@e81a89b1732b9c48d79cd809d8d81d79c4647a18 # associated tag: v1.0.2
|
||||
|
||||
- name: Set up Docker Buildx (for multi-arch builds)
|
||||
uses: docker/setup-buildx-action@dc7b9719a96d48369863986a06765841d7ea23f6 # associated tag: v1.1.2
|
||||
uses: docker/setup-buildx-action@95cb08cb2672c73d4ffd2f422e6d11953d2a9c70
|
||||
with:
|
||||
# Allows pushing to registry on localhost:5000
|
||||
driver-opts: network=host
|
||||
@@ -149,7 +149,7 @@ jobs:
|
||||
branchRegex: ^\w[\w-.]*$
|
||||
|
||||
- name: Build and push jupyterhub
|
||||
uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94
|
||||
uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5
|
||||
with:
|
||||
context: .
|
||||
platforms: linux/amd64,linux/arm64
|
||||
@@ -170,7 +170,7 @@ jobs:
|
||||
branchRegex: ^\w[\w-.]*$
|
||||
|
||||
- name: Build and push jupyterhub-onbuild
|
||||
uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94
|
||||
uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5
|
||||
with:
|
||||
build-args: |
|
||||
BASE_IMAGE=${{ fromJson(steps.jupyterhubtags.outputs.tags)[0] }}
|
||||
@@ -191,7 +191,7 @@ jobs:
|
||||
branchRegex: ^\w[\w-.]*$
|
||||
|
||||
- name: Build and push jupyterhub-demo
|
||||
uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94
|
||||
uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5
|
||||
with:
|
||||
build-args: |
|
||||
BASE_IMAGE=${{ fromJson(steps.onbuildtags.outputs.tags)[0] }}
|
||||
@@ -215,7 +215,7 @@ jobs:
|
||||
branchRegex: ^\w[\w-.]*$
|
||||
|
||||
- name: Build and push jupyterhub/singleuser
|
||||
uses: docker/build-push-action@c84f38281176d4c9cdb1626ffafcd6b3911b5d94
|
||||
uses: docker/build-push-action@c56af957549030174b10d6867f20e78cfd7debc5
|
||||
with:
|
||||
build-args: |
|
||||
JUPYTERHUB_VERSION=${{ github.ref_type == 'tag' && github.ref_name || format('git:{0}', github.sha) }}
|
||||
|
||||
@@ -1,33 +1,33 @@
|
||||
# Interpreting common log messages
|
||||
|
||||
When debugging errors and outages, looking at the logs emitted by
|
||||
JupyterHub is very helpful. This document tries to document some common
|
||||
log messages, and what they mean.
|
||||
JupyterHub is very helpful. This document intends to describe some common
|
||||
log messages, what they mean and what are the most common causes that generated them, as well as some possible ways to fix them.
|
||||
|
||||
## Failing suspected API request to not-running server
|
||||
|
||||
### Example
|
||||
|
||||
Your logs might be littered with lines that might look slightly scary
|
||||
Your logs might be littered with lines that look scary
|
||||
|
||||
```
|
||||
[W 2022-03-10 17:25:19.774 JupyterHub base:1349] Failing suspected API request to not-running server: /hub/user/<user-name>/api/metrics/v1
|
||||
```
|
||||
|
||||
### Most likely cause
|
||||
### Cause
|
||||
|
||||
This likely means that the user's server has stopped running but they
|
||||
still have a browser tab open. For example, you might have 3 tabs open and you shut
|
||||
the server down via one.
|
||||
Another possible reason could be that you closed your laptop and the server was culled for inactivity, then reopened the laptop!
|
||||
However, the client-side code (JupyterLab, Classic Notebook, etc) doesn't interpret the shut-down server and continues to make some API requests.
|
||||
|
||||
This likely means is that the user's server has stopped running but they
|
||||
still have a browser tab open. For example, you might have 3 tabs open, and shut
|
||||
your server down via one. Or you closed your laptop, your server was
|
||||
culled for inactivity, and then you reopen your laptop again! The
|
||||
client side code (JupyterLab, Classic Notebook, etc) does not know
|
||||
yet that the server is dead, and continues to make some API requests.
|
||||
JupyterHub's architecture means that the proxy routes all requests that
|
||||
don't go to a running user server to the hub process itself. The hub
|
||||
process then explicitly returns a failure response, so the client knows
|
||||
that the server is not running anymore. This is used by JupyterLab to
|
||||
tell you your server is not running anymore, and offer you the option
|
||||
to let you restart it.
|
||||
inform the user that the server is not running anymore, and provide an option
|
||||
to restart it.
|
||||
|
||||
Most commonly, you'll see this in reference to the `/api/metrics/v1`
|
||||
URL, used by [jupyter-resource-usage](https://github.com/jupyter-server/jupyter-resource-usage).
|
||||
@@ -47,9 +47,9 @@ This log message is benign, and there is usually no action for you to take.
|
||||
### Cause
|
||||
|
||||
JupyterHub requires the `jupyterhub` python package installed inside the image or
|
||||
environment the user server starts in. This message indicates that the version of
|
||||
environment, the user server starts in. This message indicates that the version of
|
||||
the `jupyterhub` package installed inside the user image or environment is not
|
||||
the same version as the JupyterHub server itself. This is not necessarily always a
|
||||
the same as the JupyterHub server's version itself. This is not necessarily always a
|
||||
problem - some version drift is mostly acceptable, and the only two known cases of
|
||||
breakage are across the 0.7 and 2.0 version releases. In those cases, issues pop
|
||||
up immediately after upgrading your version of JupyterHub, so **always check the JupyterHub
|
||||
@@ -67,6 +67,6 @@ aligned, rather than as an indicator of an existing problem.
|
||||
### Actions you can take
|
||||
|
||||
Upgrade the version of the `jupyterhub` package in your user environment or image
|
||||
so it matches the version of JupyterHub running your JupyterHub server! If you
|
||||
so that it matches the version of JupyterHub running your JupyterHub server! If you
|
||||
are using the [zero-to-jupyterhub](https://z2jh.jupyter.org) helm chart, you can find the appropriate
|
||||
version of the `jupyterhub` package to install in your user image [here](https://jupyterhub.github.io/helm-chart/)
|
||||
|
||||
@@ -7,18 +7,18 @@ document describes how to do these upgrades.
|
||||
|
||||
If you are using :ref:`a JupyterHub distribution <index/distributions>`, you
|
||||
should consult the distribution's documentation on how to upgrade. This
|
||||
document is if you have set up your own JupyterHub without using a
|
||||
document is useful if you have set up your own JupyterHub without using a
|
||||
distribution.
|
||||
|
||||
It is long because is pretty detailed! Most likely, upgrading
|
||||
JupyterHub is painless, quick and with minimal user interruption.
|
||||
The steps are discussed in detail, so if you get stuck at any step you can always refer to this guide. Most likely,
|
||||
upgrading JupyterHub is painless, quick and with minimal user interruption.
|
||||
|
||||
Read the Changelog
|
||||
==================
|
||||
|
||||
The `changelog <../changelog.html>`_ contains information on what has
|
||||
changed with the new JupyterHub release, and any deprecation warnings.
|
||||
Read these notes to familiarize yourself with the coming changes. There
|
||||
The `changelog <../changelog.md>`_ contains information on what has
|
||||
changed with the new JupyterHub release and any deprecation warnings.
|
||||
Read these notes to familiarize yourself with the upcoming changes. There
|
||||
might be new releases of authenticators & spawners you are using, so
|
||||
read the changelogs for those too!
|
||||
|
||||
@@ -30,10 +30,10 @@ is managed by JupyterHub, your users will see service disruption during
|
||||
the upgrade process. You should notify them, and pick a time to do the
|
||||
upgrade where they will be least disrupted.
|
||||
|
||||
If you are using a different proxy, or running ``configurable-http-proxy``
|
||||
If you are using a different proxy or running ``configurable-http-proxy``
|
||||
independent of JupyterHub, your users will be able to continue using notebook
|
||||
servers they had already launched, but will not be able to launch new servers
|
||||
nor sign in.
|
||||
or sign in.
|
||||
|
||||
|
||||
Backup database & config
|
||||
@@ -41,22 +41,21 @@ Backup database & config
|
||||
|
||||
Before doing an upgrade, it is critical to back up:
|
||||
|
||||
#. Your JupyterHub database (sqlite by default, or MySQL / Postgres
|
||||
if you used those). If you are using sqlite (the default), you
|
||||
#. Your JupyterHub database (SQLite by default, or MySQL / Postgres
|
||||
if you used those). If you are using SQLite (the default), you
|
||||
should back up the ``jupyterhub.sqlite`` file.
|
||||
#. Your ``jupyterhub_config.py`` file.
|
||||
#. Your user's home directories. This is unlikely to be affected directly by
|
||||
a JupyterHub upgrade, but we recommend a backup since user data is very
|
||||
critical.
|
||||
#. Your users' home directories. This is unlikely to be affected directly by
|
||||
a JupyterHub upgrade, but we recommend a backup since user data is critical.
|
||||
|
||||
|
||||
Shut down JupyterHub
|
||||
===================
|
||||
====================
|
||||
|
||||
Shut down the JupyterHub process. This would vary depending on how you
|
||||
have set up JupyterHub to run. Most likely, it is using a process
|
||||
supervisor of some sort (``systemd`` or ``supervisord`` or even ``docker``).
|
||||
Use the supervisor specific command to stop the JupyterHub process.
|
||||
Use the supervisor-specific command to stop the JupyterHub process.
|
||||
|
||||
Upgrade JupyterHub packages
|
||||
===========================
|
||||
@@ -64,14 +63,14 @@ Upgrade JupyterHub packages
|
||||
There are two environments where the ``jupyterhub`` package is installed:
|
||||
|
||||
#. The *hub environment*, which is where the JupyterHub server process
|
||||
runs. This is started with the ``jupyterhub`` command, and is what
|
||||
runs. This is started with the ``jupyterhub`` command and is what
|
||||
people generally think of as JupyterHub.
|
||||
|
||||
#. The *notebook user environments*. This is where the user notebook
|
||||
servers are launched from, and is probably custom to your own
|
||||
#. The *notebook user environments*. This is where the user's notebook
|
||||
servers are launched from and are probably custom to your own
|
||||
installation. This could be just one environment (different from the
|
||||
hub environment) that is shared by all users, one environment
|
||||
per user, or same environment as the hub environment. The hub
|
||||
per user, or the same environment as the hub environment. The hub
|
||||
launched the ``jupyterhub-singleuser`` command in this environment,
|
||||
which in turn starts the notebook server.
|
||||
|
||||
@@ -95,7 +94,7 @@ with:
|
||||
Where ``<version>`` is the version of JupyterHub you are upgrading to.
|
||||
|
||||
You should also check for new releases of the authenticator & spawner you
|
||||
are using. You might wish to upgrade those packages too along with JupyterHub,
|
||||
are using. You might wish to upgrade those packages, too, along with JupyterHub
|
||||
or upgrade them separately.
|
||||
|
||||
Upgrade JupyterHub database
|
||||
@@ -109,7 +108,7 @@ database. From the hub environment, in the same directory as your
|
||||
|
||||
jupyterhub upgrade-db
|
||||
|
||||
This should find the location of your database, and run necessary upgrades
|
||||
This should find the location of your database, and run the necessary upgrades
|
||||
for it.
|
||||
|
||||
SQLite database disadvantages
|
||||
@@ -118,11 +117,11 @@ SQLite database disadvantages
|
||||
SQLite has some disadvantages when it comes to upgrading JupyterHub. These
|
||||
are:
|
||||
|
||||
- ``upgrade-db`` may not work, and you may need delete your database
|
||||
- ``upgrade-db`` may not work, and you may need to delete your database
|
||||
and start with a fresh one.
|
||||
- ``downgrade-db`` **will not** work if you want to rollback to an
|
||||
earlier version, so backup the ``jupyterhub.sqlite`` file before
|
||||
upgrading
|
||||
upgrading.
|
||||
|
||||
What happens if I delete my database?
|
||||
-------------------------------------
|
||||
@@ -137,10 +136,10 @@ resides only in the Hub database includes:
|
||||
If the following conditions are true, you should be fine clearing the
|
||||
Hub database and starting over:
|
||||
|
||||
- users specified in config file, or login using an external
|
||||
- users specified in the config file, or login using an external
|
||||
authentication provider (Google, GitHub, LDAP, etc)
|
||||
- user servers are stopped during upgrade
|
||||
- don't mind causing users to login again after upgrade
|
||||
- user servers are stopped during the upgrade
|
||||
- don't mind causing users to log in again after the upgrade
|
||||
|
||||
Start JupyterHub
|
||||
================
|
||||
@@ -148,7 +147,7 @@ Start JupyterHub
|
||||
Once the database upgrade is completed, start the ``jupyterhub``
|
||||
process again.
|
||||
|
||||
#. Log-in and start the server to make sure things work as
|
||||
#. Log in and start the server to make sure things work as
|
||||
expected.
|
||||
#. Check the logs for any errors or deprecation warnings. You
|
||||
might have to update your ``jupyterhub_config.py`` file to
|
||||
|
||||
23
docs/source/contributing/community.md
Normal file
23
docs/source/contributing/community.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# Community communication channels
|
||||
|
||||
We use different channels of communication for different purposes. Whichever one you use will depend on what kind of communication you want to engage in.
|
||||
|
||||
## Discourse (recommended)
|
||||
|
||||
We use [Discourse](https://discourse.jupyter.org) for online discussions and support questions. Everyone in the Jupyter community is welcome to bring ideas and questions there.
|
||||
|
||||
All our past and current discussions on Discourse are archived and searchable. This is why we recommend you first go to Discourse, so that discussions remain useful and accessible to the whole community.
|
||||
|
||||
## Gitter
|
||||
|
||||
We use [our Gitter channel](https://gitter.im/jupyterhub/jupyterhub) for online, real-time text chat; a place for more ephemeral discussions. When you're not on Discourse, you can stop here to have other discussions on the fly.
|
||||
|
||||
## Github Issues
|
||||
|
||||
Github issues are used for most long-form project discussions, bug reports and feature requests.
|
||||
|
||||
Issues related to a specific authenticator or spawner should be opened in the appropriate repository for the authenticator or spawner. If you are using a specific JupyterHub distribution (such as [Zero to JupyterHub on Kubernetes](http://github.com/jupyterhub/zero-to-jupyterhub-k8s) or [The Littlest JupyterHub](http://github.com/jupyterhub/the-littlest-jupyterhub/)), you should open issues directly in their repository.
|
||||
|
||||
If you cannot find a repository to open your issue in, do not worry! Open the issue in the [main JupyterHub repository](https://github.com/jupyterhub/jupyterhub/) and our community will help you figure it out.
|
||||
|
||||
**NOTE**: Our community is distributed across the world in various timezones, so please be patient if you do not get a response immediately!
|
||||
@@ -1,30 +0,0 @@
|
||||
.. _contributing/community:
|
||||
|
||||
================================
|
||||
Community communication channels
|
||||
================================
|
||||
|
||||
We use `Discourse <https://discourse.jupyter.org>` for online discussion.
|
||||
Everyone in the Jupyter community is welcome to bring ideas and questions there.
|
||||
In addition, we use `Gitter <https://gitter.im>`_ for online, real-time text chat,
|
||||
a place for more ephemeral discussions.
|
||||
The primary Gitter channel for JupyterHub is `jupyterhub/jupyterhub <https://gitter.im/jupyterhub/jupyterhub>`_.
|
||||
Gitter isn't archived or searchable, so we recommend going to discourse first
|
||||
to make sure that discussions are most useful and accessible to the community.
|
||||
Remember that our community is distributed across the world in various
|
||||
timezones, so be patient if you do not get an answer immediately!
|
||||
|
||||
GitHub issues are used for most long-form project discussions, bug reports
|
||||
and feature requests. Issues related to a specific authenticator or
|
||||
spawner should be directed to the appropriate repository for the
|
||||
authenticator or spawner. If you are using a specific JupyterHub
|
||||
distribution (such as `Zero to JupyterHub on Kubernetes <http://github.com/jupyterhub/zero-to-jupyterhub-k8s>`_
|
||||
or `The Littlest JupyterHub <http://github.com/jupyterhub/the-littlest-jupyterhub/>`_),
|
||||
you should open issues directly in their repository. If you can not
|
||||
find a repository to open your issue in, do not worry! Create it in the `main
|
||||
JupyterHub repository <https://github.com/jupyterhub/jupyterhub/>`_ and our
|
||||
community will help you figure it out.
|
||||
|
||||
A `mailing list <https://groups.google.com/forum/#!forum/jupyter>`_ for all
|
||||
of Project Jupyter exists, along with one for `teaching with Jupyter
|
||||
<https://groups.google.com/forum/#!forum/jupyter-education>`_.
|
||||
@@ -7,7 +7,7 @@ Setting up a development install
|
||||
System requirements
|
||||
===================
|
||||
|
||||
JupyterHub can only run on MacOS or Linux operating systems. If you are
|
||||
JupyterHub can only run on macOS or Linux operating systems. If you are
|
||||
using Windows, we recommend using `VirtualBox <https://virtualbox.org>`_
|
||||
or a similar system to run `Ubuntu Linux <https://ubuntu.com>`_ for
|
||||
development.
|
||||
@@ -15,10 +15,10 @@ development.
|
||||
Install Python
|
||||
--------------
|
||||
|
||||
JupyterHub is written in the `Python <https://python.org>`_ programming language, and
|
||||
JupyterHub is written in the `Python <https://python.org>`_ programming language and
|
||||
requires you have at least version 3.6 installed locally. If you haven’t
|
||||
installed Python before, the recommended way to install it is to use
|
||||
`miniconda <https://conda.io/miniconda.html>`_. Remember to get the ‘Python 3’ version,
|
||||
`Miniconda <https://conda.io/miniconda.html>`_. Remember to get the ‘Python 3’ version,
|
||||
and **not** the ‘Python 2’ version!
|
||||
|
||||
Install nodejs
|
||||
@@ -26,13 +26,13 @@ Install nodejs
|
||||
|
||||
`NodeJS 12+ <https://nodejs.org/en/>`_ is required for building some JavaScript components.
|
||||
``configurable-http-proxy``, the default proxy implementation for JupyterHub, is written in Javascript.
|
||||
If you have not installed nodejs before, we recommend installing it in the ``miniconda`` environment you set up for Python.
|
||||
If you have not installed NodeJS before, we recommend installing it in the ``miniconda`` environment you set up for Python.
|
||||
You can do so with ``conda install nodejs``.
|
||||
|
||||
Install git
|
||||
-----------
|
||||
|
||||
JupyterHub uses `git <https://git-scm.com>`_ & `GitHub <https://github.com>`_
|
||||
JupyterHub uses `Git <https://git-scm.com>`_ & `GitHub <https://github.com>`_
|
||||
for development & collaboration. You need to `install git
|
||||
<https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_ to work on
|
||||
JupyterHub. We also recommend getting a free account on GitHub.com.
|
||||
@@ -40,13 +40,11 @@ JupyterHub. We also recommend getting a free account on GitHub.com.
|
||||
Setting up a development install
|
||||
================================
|
||||
|
||||
When developing JupyterHub, you need to make changes to the code & see
|
||||
their effects quickly. You need to do a developer install to make that
|
||||
happen.
|
||||
When developing JupyterHub, you would need to make changes and be able to instantly view the results of the changes. To achieve that, a developer install is required.
|
||||
|
||||
.. note:: This guide does not attempt to dictate *how* development
|
||||
environments should be isolated since that is a personal preference and can
|
||||
be achieved in many ways, for example `tox`, `conda`, `docker`, etc. See this
|
||||
be achieved in many ways, for example, `tox`, `conda`, `docker`, etc. See this
|
||||
`forum thread <https://discourse.jupyter.org/t/thoughts-on-using-tox/3497>`_ for
|
||||
a more detailed discussion.
|
||||
|
||||
@@ -107,7 +105,7 @@ happen.
|
||||
|
||||
The default database engine is ``sqlite`` so if you are just trying
|
||||
to get up and running quickly for local development that should be
|
||||
available via `python <https://docs.python.org/3.5/library/sqlite3.html>`__.
|
||||
available via `Python <https://docs.python.org/3.5/library/sqlite3.html>`__.
|
||||
See :doc:`/reference/database` for details on other supported databases.
|
||||
|
||||
6. Install the development version of JupyterHub. This lets you edit
|
||||
@@ -137,7 +135,7 @@ To simplify testing of JupyterHub, it’s helpful to use
|
||||
authenticator and SimpleLocalProcessSpawner instead of the default spawner.
|
||||
|
||||
There is a sample configuration file that does this in
|
||||
``testing/jupyterhub_config.py``. To launch jupyterhub with this
|
||||
``testing/jupyterhub_config.py``. To launch JupyterHub with this
|
||||
configuration:
|
||||
|
||||
.. code:: bash
|
||||
@@ -153,14 +151,14 @@ JupyterHub as.
|
||||
|
||||
DummyAuthenticator allows you to log in with any username & password,
|
||||
while SimpleLocalProcessSpawner allows you to start servers without having to
|
||||
create a unix user for each JupyterHub user. Together, these make it
|
||||
create a Unix user for each JupyterHub user. Together, these make it
|
||||
much easier to test JupyterHub.
|
||||
|
||||
Tip: If you are working on parts of JupyterHub that are common to all
|
||||
authenticators & spawners, we recommend using both DummyAuthenticator &
|
||||
SimpleLocalProcessSpawner. If you are working on just authenticator related
|
||||
SimpleLocalProcessSpawner. If you are working on just authenticator-related
|
||||
parts, use only SimpleLocalProcessSpawner. Similarly, if you are working on
|
||||
just spawner related parts, use only DummyAuthenticator.
|
||||
just spawner-related parts, use only DummyAuthenticator.
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
@@ -4,19 +4,16 @@
|
||||
Testing JupyterHub and linting code
|
||||
===================================
|
||||
|
||||
Unit test help validate that JupyterHub works the way we think it does,
|
||||
and continues to do so when changes occur. They also help communicate
|
||||
precisely what we expect our code to do.
|
||||
Unit tests help confirm that JupyterHub works as intended, including after modifications are made. Additionally, they help in clarifying our expectations for our code.
|
||||
|
||||
JupyterHub uses `pytest <https://pytest.org>`_ for all our tests. You
|
||||
can find them under ``jupyterhub/tests`` directory in the git repository.
|
||||
JupyterHub uses `pytest <https://pytest.org>`_ for all the tests. You
|
||||
can find them under the `jupyterhub/tests <https://github.com/jupyterhub/jupyterhub/tree/main/jupyterhub/tests>`_ directory in the git repository.
|
||||
|
||||
Running the tests
|
||||
==================
|
||||
|
||||
#. Make sure you have completed :ref:`contributing/setup`. You should be able
|
||||
to start ``jupyterhub`` from the commandline & access it from your
|
||||
web browser. This ensures that the dev environment is properly set
|
||||
#. Make sure you have completed :ref:`contributing/setup`. Once completed, you should be able
|
||||
to run ``jupyterhub`` on your command line and access JupyterHub from your browser at http://localhost:8000. Being able to run and access `jupyterhub` should mean that the dev environment is properly set
|
||||
up for tests to run.
|
||||
|
||||
#. You can run all tests in JupyterHub
|
||||
@@ -57,7 +54,7 @@ Running the tests
|
||||
|
||||
pytest -v jupyterhub/tests/test_api.py::test_shutdown
|
||||
|
||||
See the `pytest usage documentation <https://pytest.readthedocs.io/en/latest/usage.html>`_ for more details.
|
||||
For more information, refer to the `pytest usage documentation <https://pytest.readthedocs.io/en/latest/usage.html>`_.
|
||||
|
||||
Test organisation
|
||||
=================
|
||||
@@ -98,8 +95,7 @@ And fixtures to add functionality or spawning behavior:
|
||||
- ``bad_spawn``: enables the BadSpawner (a spawner that fails immediately)
|
||||
- ``slow_bad_spawn``: enables the SlowBadSpawner (a spawner that fails after a short delay)
|
||||
|
||||
See the `pytest fixtures documentation <https://pytest.readthedocs.io/en/latest/fixture.html>`_
|
||||
for how to use the existing fixtures, and how to create new ones.
|
||||
For information on using the existing fixtures and creating new ones, refer to the `pytest fixtures documentation <https://pytest.readthedocs.io/en/latest/fixture.html>`_
|
||||
|
||||
|
||||
Troubleshooting Test Failures
|
||||
@@ -108,8 +104,7 @@ Troubleshooting Test Failures
|
||||
All the tests are failing
|
||||
-------------------------
|
||||
|
||||
Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and
|
||||
can launch ``jupyterhub`` from the terminal.
|
||||
Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and are able to access JupyterHub from your browser at http://localhost:8000 after starting ``jupyterhub`` in your command line.
|
||||
|
||||
|
||||
Code formatting and linting
|
||||
@@ -117,13 +112,13 @@ Code formatting and linting
|
||||
|
||||
JupyterHub has adopted automatic code formatting and linting.
|
||||
As long as your code is valid, the pre-commit hook should take care of how it should look.
|
||||
You can invoke the pre-commit hook by hand at any time with:
|
||||
You can invoke the pre-commit hook manually at any time with:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
pre-commit run
|
||||
|
||||
which should run any autoformatting on your code and tell you about any errors it couldn't fix automatically.
|
||||
This should run any auto formatting on your code and tell you about any errors it couldn't fix automatically.
|
||||
You may also install `black integration <https://github.com/psf/black#editor-integration>`_
|
||||
into your text editor to format code automatically.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Event logging and Telemetry
|
||||
==========================
|
||||
===========================
|
||||
|
||||
JupyterHub can be configured to record structured events from a running server using Jupyter's `Telemetry System`_. The types of events that JupyterHub emits are defined by `JSON schemas`_ listed at the bottom of this page_.
|
||||
|
||||
@@ -15,8 +15,8 @@ Event logging is handled by its ``Eventlog`` object. This leverages Python's sta
|
||||
|
||||
To begin recording events, you'll need to set two configurations:
|
||||
|
||||
1. ``handlers``: tells the EventLog *where* to route your events. This trait is a list of Python logging handlers that route events to
|
||||
2. ``allows_schemas``: tells the EventLog *which* events should be recorded. No events are emitted by default; all recorded events must be listed here.
|
||||
1. ``handlers``: tells the EventLog *where* to route your events; this trait is a list of Python logging handlers that route events to the destination
|
||||
2. ``allows_schemas``: tells the EventLog *which* events should be recorded; no events are emitted by default; all recorded events must be listed here
|
||||
|
||||
Here's a basic example:
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Hub via the REST API.
|
||||
|
||||
## API Token basics
|
||||
|
||||
### Create an API token
|
||||
### Step 1: Generate an API token
|
||||
|
||||
To run such an external service, an API token must be created and
|
||||
provided to the service.
|
||||
@@ -43,12 +43,12 @@ generating an API token is available from the JupyterHub user interface:
|
||||
|
||||
|
||||
|
||||
### Pass environment variable with token to the Hub
|
||||
### Step 2: Pass environment variable with token to the Hub
|
||||
|
||||
In the case of `cull_idle_servers`, it is passed as the environment
|
||||
variable called `JUPYTERHUB_API_TOKEN`.
|
||||
|
||||
### Use API tokens for services and tasks that require external access
|
||||
### Step 3: Use API tokens for services and tasks that require external access
|
||||
|
||||
While API tokens are often associated with a specific user, API tokens
|
||||
can be used by services that require external access for activities
|
||||
@@ -62,7 +62,7 @@ c.JupyterHub.services = [
|
||||
]
|
||||
```
|
||||
|
||||
### Restart JupyterHub
|
||||
### Step 4: Restart JupyterHub
|
||||
|
||||
Upon restarting JupyterHub, you should see a message like below in the
|
||||
logs:
|
||||
@@ -78,16 +78,15 @@ single-user servers, and only cookies can be used for authentication.
|
||||
0.8 supports using JupyterHub API tokens to authenticate to single-user
|
||||
servers.
|
||||
|
||||
## Configure the idle culler to run as a Hub-Managed Service
|
||||
## How to configure the idle culler to run as a Hub-Managed Service
|
||||
|
||||
Install the idle culler:
|
||||
### Step 1: Install the idle culler:
|
||||
|
||||
```
|
||||
pip install jupyterhub-idle-culler
|
||||
```
|
||||
|
||||
In `jupyterhub_config.py`, add the following dictionary for the
|
||||
`idle-culler` Service to the `c.JupyterHub.services` list:
|
||||
### Step 2: In `jupyterhub_config.py`, add the following dictionary for the `idle-culler` Service to the `c.JupyterHub.services` list:
|
||||
|
||||
```python
|
||||
c.JupyterHub.services = [
|
||||
@@ -127,7 +126,7 @@ It now needs the scopes:
|
||||
- `admin:servers` to start/stop servers
|
||||
```
|
||||
|
||||
## Run `cull-idle` manually as a standalone script
|
||||
## How to run `cull-idle` manually as a standalone script
|
||||
|
||||
Now you can run your script by providing it
|
||||
the API token and it will authenticate through the REST API to
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Spawners and single-user notebook servers
|
||||
|
||||
Since the single-user server is an instance of `jupyter notebook`, an entire separate
|
||||
multi-process application, there are many aspects of that server that can be configured, and a lot
|
||||
Since the single-user server is an instance of `jupyter notebook`, an entirely separate
|
||||
multi-process application, there are many aspects of that server that can be configured and a lot
|
||||
of ways to express that configuration.
|
||||
|
||||
At the JupyterHub level, you can set some values on the Spawner. The simplest of these is
|
||||
`Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root
|
||||
notebook directory is the highest level directory users will be able to access in the notebook
|
||||
notebook directory is the highest-level directory users will be able to access in the notebook
|
||||
dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is
|
||||
expanded to the user's home directory.
|
||||
|
||||
@@ -20,7 +20,7 @@ You can also specify extra command line arguments to the notebook server with:
|
||||
c.Spawner.args = ['--debug', '--profile=PHYS131']
|
||||
```
|
||||
|
||||
This could be used to set the users default page for the single user server:
|
||||
This could be used to set the user's default page for the single-user server:
|
||||
|
||||
```python
|
||||
c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
|
||||
@@ -30,4 +30,4 @@ Since the single-user server extends the notebook server application,
|
||||
it still loads configuration from the `jupyter_notebook_config.py` config file.
|
||||
Each user may have one of these files in `$HOME/.jupyter/`.
|
||||
Jupyter also supports loading system-wide config files from `/etc/jupyter/`,
|
||||
which is the place to put configuration that you want to affect all of your users.
|
||||
which is the place to put the configuration that you want to affect all of your users.
|
||||
|
||||
@@ -2,10 +2,17 @@
|
||||
JupyterHub
|
||||
==========
|
||||
`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users.
|
||||
It is a multi-user **Hub** that spawns, manages, and proxies multiple instances
|
||||
of the single-user `Jupyter notebook`_ server. Therefore, with JupyterHub,
|
||||
users can log in to the server, and write Python code in a web browser,
|
||||
without having to install software on their local machine.
|
||||
Because JupyterHub manages a separate Jupyter environment for each user,
|
||||
it can be used in a class of students, a corporate data science group, or a scientific
|
||||
research group. It is a multi-user **Hub** that spawns, manages, and proxies multiple
|
||||
instances of the single-user `Jupyter notebook`_ server.
|
||||
|
||||
JupyterHub offers distributions for different use cases. Be sure to
|
||||
take a look at them before continuing with the configuration of the broad
|
||||
original system of `JupyterHub`_. As of now, you can find two main cases:
|
||||
|
||||
1. `The Littlest JupyterHub <https://github.com/jupyterhub/the-littlest-jupyterhub>`__ distribution is suitable if you need a small number of users (1-100) and a single server with a simple environment.
|
||||
2. `Zero to JupyterHub with Kubernetes <https://github.com/jupyterhub/zero-to-jupyterhub-k8s>`__ allows you to deploy dynamic servers on the cloud if you need even more users.
|
||||
|
||||
JupyterHub supports web browsers, tablets and smartphones and can be used by
|
||||
multiple users at the same time such as; a class of students, a corporate data
|
||||
@@ -69,7 +76,6 @@ Today, you can find two main use cases:
|
||||
*It is important to evaluate these distributions before you can continue with the
|
||||
configuration of the broad original system of* **JupyterHub**.
|
||||
|
||||
|
||||
Installation Guide
|
||||
------------------
|
||||
|
||||
@@ -121,8 +127,8 @@ RBAC Reference
|
||||
Contributing
|
||||
------------
|
||||
|
||||
We want you to contribute to JupyterHub in ways that are most exciting
|
||||
& useful to you. We value documentation, testing, bug reporting & code equally,
|
||||
We welcome you to contribute to JupyterHub in ways that are most exciting
|
||||
& useful to you. We value documentation, testing, bug reporting & code equally
|
||||
and are glad to have your contributions in whatever form you wish :)
|
||||
|
||||
Our `Code of Conduct <https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md>`_ and `reporting guidelines <https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md>`_
|
||||
|
||||
@@ -1,49 +1,62 @@
|
||||
Using Docker
|
||||
============
|
||||
Install JupyterHub with Docker
|
||||
==============================
|
||||
|
||||
The JupyterHub `docker image <https://hub.docker.com/r/jupyterhub/jupyterhub/>`_ is the fastest way to set up Jupyterhub in your local development environment.
|
||||
|
||||
The ``JupyterHub`` docker image runs the Hub service only. It does not provide other Jupyter components such as Notebook installation, which are needed by the single-user servers.
|
||||
To run the single-user servers, which may be on the same system as the Hub or not, Jupyter Notebook or Jupyter Lab must be installed.
|
||||
|
||||
.. important::
|
||||
We strongly recommend that you follow the `Zero to JupyterHub`_ tutorial to
|
||||
install JupyterHub.
|
||||
|
||||
We highly recommend following the `Zero to JupyterHub`_ tutorial for
|
||||
installing JupyterHub.
|
||||
|
||||
Alternate installation using Docker
|
||||
-----------------------------------
|
||||
Prerequisites
|
||||
-------------
|
||||
You should have `Docker`_ installed on a Linux/Unix based system.
|
||||
|
||||
A ready to go `docker image <https://hub.docker.com/r/jupyterhub/jupyterhub/>`_
|
||||
gives a straightforward deployment of JupyterHub.
|
||||
|
||||
.. note::
|
||||
Run the Docker Image
|
||||
--------------------
|
||||
|
||||
This ``jupyterhub/jupyterhub`` docker image is only an image for running
|
||||
the Hub service itself. It does not provide the other Jupyter components,
|
||||
such as Notebook installation, which are needed by the single-user servers.
|
||||
To run the single-user servers, which may be on the same system as the Hub or
|
||||
not, Jupyter Notebook version 4 or greater must be installed.
|
||||
|
||||
Starting JupyterHub with docker
|
||||
-------------------------------
|
||||
|
||||
The JupyterHub docker image can be started with the following command::
|
||||
To pull the latest JupyterHub image and start the `jupyterhub` container, run this command in your terminal.
|
||||
::
|
||||
|
||||
docker run -d -p 8000:8000 --name jupyterhub jupyterhub/jupyterhub jupyterhub
|
||||
|
||||
This command will create a container named ``jupyterhub`` that you can
|
||||
**stop and resume** with ``docker stop/start``.
|
||||
This command exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console.
|
||||
|
||||
The Hub service will be listening on all interfaces at port 8000, which makes
|
||||
this a good choice for **testing JupyterHub on your desktop or laptop**.
|
||||
You can stop and resume the container by running `docker stop` and `docker start` respectively.
|
||||
::
|
||||
|
||||
If you want to run docker on a computer that has a public IP then you should
|
||||
(as in MUST) **secure it with ssl** by adding ssl options to your docker
|
||||
# find the container id
|
||||
docker ps
|
||||
|
||||
# stop the running container
|
||||
docker stop <container-id>
|
||||
|
||||
# resume the paused container
|
||||
docker start <container-id>
|
||||
|
||||
|
||||
If you are running Docker on a computer that has a public IP address, you must **secure it with ssl** by adding ssl options to your docker
|
||||
configuration or using a ssl enabled proxy.
|
||||
|
||||
`Mounting volumes <https://docs.docker.com/engine/admin/volumes/volumes/>`_
|
||||
will allow you to store data outside the docker image (host system) so it will
|
||||
be persistent, even when you start a new image.
|
||||
|
||||
The command ``docker exec -it jupyterhub bash`` will spawn a root shell in your
|
||||
docker container. You can use the root shell to **create system users in the container**.
|
||||
These accounts will be used for authentication in JupyterHub's default
|
||||
`Mounting volumes <https://docs.docker.com/engine/admin/volumes/volumes/>`_
|
||||
enables you to persist and store the data generated by the docker container, even when you stop the container.
|
||||
The persistent data can be stored on the host system, outside the container.
|
||||
|
||||
|
||||
Create System Users
|
||||
-------------------
|
||||
|
||||
Spawn a root shell in your docker container by running this command in the terminal.::
|
||||
|
||||
docker exec -it jupyterhub bash
|
||||
|
||||
The created accounts will be used for authentication in JupyterHub's default
|
||||
configuration.
|
||||
|
||||
.. _Zero to JupyterHub: https://zero-to-jupyterhub.readthedocs.io/en/latest/
|
||||
.. _Docker: https://www.docker.com/
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
# Roles
|
||||
|
||||
JupyterHub provides four roles that are available by default:
|
||||
JupyterHub provides four (4) roles that are available by default:
|
||||
|
||||
```{admonition} **Default roles**
|
||||
- `user` role provides a {ref}`default user scope <default-user-scope-target>` `self` that grants access to the user's own resources.
|
||||
@@ -13,11 +13,11 @@ JupyterHub provides four roles that are available by default:
|
||||
**These roles cannot be deleted.**
|
||||
```
|
||||
|
||||
These default roles have a default collection of scopes,
|
||||
but you can define the scopes associated with each role (excluding admin) to suit your needs,
|
||||
We call these 'default' roles because they are available by default and have a default collection of scopes.
|
||||
However, you can define the scopes associated with each role (excluding the admin role) to suit your needs,
|
||||
as seen [below](overriding-default-roles).
|
||||
|
||||
The `user`, `admin`, and `token` roles by default all preserve the permissions prior to RBAC.
|
||||
The `user`, `admin`, and `token` roles, by default, all preserve the permissions prior to Role-based Access Control (RBAC).
|
||||
Only the `server` role is changed from pre-2.0, to reduce its permissions to activity-only
|
||||
instead of the default of a full access token.
|
||||
|
||||
@@ -31,10 +31,10 @@ Roles can be assigned to the following entities:
|
||||
An entity can have zero, one, or multiple roles, and there are no restrictions on which roles can be assigned to which entity. Roles can be added to or removed from entities at any time.
|
||||
|
||||
**Users** \
|
||||
When a new user gets created, they are assigned their default role `user`. Additionaly, if the user is created with admin privileges (via `c.Authenticator.admin_users` in `jupyterhub_config.py` or `admin: true` via API), they will be also granted `admin` role. If existing user's admin status changes via API or `jupyterhub_config.py`, their default role will be updated accordingly (after next startup for the latter).
|
||||
When a new user gets created, they are assigned their default role, `user`. Additionally, if the user is created with admin privileges (via `c.Authenticator.admin_users` in `jupyterhub_config.py` or `admin: true` via API), they will be also granted `admin` role. If existing user's admin status changes via API or `jupyterhub_config.py`, their default role will be updated accordingly (after next startup for the latter).
|
||||
|
||||
**Services** \
|
||||
Services do not have a default role. Services without roles have no access to the guarded API end-points, so most services will require assignment of a role in order to function.
|
||||
Services do not have a default role. Services without roles have no access to the guarded API end-points. So, most services will require assignment of a role in order to function.
|
||||
|
||||
**Groups** \
|
||||
A group does not require any role, and has no roles by default. If a user is a member of a group, they automatically inherit any of the group's permissions (see {ref}`resolving-roles-scopes-target` for more details). This is useful for assigning a set of common permissions to several users.
|
||||
@@ -113,7 +113,7 @@ In case the role with a certain name already exists in the database, its definit
|
||||
|
||||
(overriding-default-roles)=
|
||||
|
||||
### Overriding default roles
|
||||
### Overriding Default Roles
|
||||
|
||||
Role definitions can include those of the "default" roles listed above (admin excluded),
|
||||
if the default scopes associated with those roles do not suit your deployment.
|
||||
@@ -154,7 +154,7 @@ c.JupyterHub.load_roles = [
|
||||
|
||||
(removing-roles-target)=
|
||||
|
||||
## Removing roles
|
||||
## Removing Roles
|
||||
|
||||
Only the entities present in the role definition in the `jupyterhub_config.py` remain the role bearers. If a user, service or group is removed from the role definition, they will lose the role on the next startup.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Technical Implementation
|
||||
|
||||
Roles are stored in the database, where they are associated with users, services, etc., and can be added or modified as explained in {ref}`define-role-target` section. Users, services, groups, and tokens can gain, change, and lose roles. This is currently achieved via `jupyterhub_config.py` (see {ref}`define-role-target`) and will be made available via API in future. The latter will allow for changing a token's role, and thereby its permissions, without the need to issue a new token.
|
||||
[Roles](roles) are stored in the database, where they are associated with users, services, and groups. Roles can be added or modified as explained in the {ref}`define-role-target` section. Users, services, groups, and tokens can gain, change, and lose roles. This is currently achieved via `jupyterhub_config.py` (see {ref}`define-role-target`) and will be made available via API in the future. The latter will allow for changing a user's role, and thereby its permissions, without the need to restart JupyterHub.
|
||||
|
||||
Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. Scope variables take on five different formats which is reflected throughout the utilities via specific nomenclature:
|
||||
Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. Scope variables take on five different formats that are reflected throughout the utilities via specific nomenclature:
|
||||
|
||||
```{admonition} **Scope variable nomenclature**
|
||||
:class: tip
|
||||
@@ -11,22 +11,22 @@ Roles and scopes utilities can be found in `roles.py` and `scopes.py` modules. S
|
||||
- _expanded scopes_ \
|
||||
Set of fully expanded scopes without abbreviations (i.e., resolved metascopes, filters, and subscopes). E.g., `{"users:activity!user=charlie", "read:users:activity!user=charlie"}`.
|
||||
- _parsed scopes_ \
|
||||
Dictionary represenation of expanded scopes. E.g., `{"users:activity": {"user": ["charlie"]}, "read:users:activity": {"users": ["charlie"]}}`.
|
||||
Dictionary representation of expanded scopes. E.g., `{"users:activity": {"user": ["charlie"]}, "read:users:activity": {"users": ["charlie"]}}`.
|
||||
- _intersection_ \
|
||||
Set of expanded scopes as intersection of 2 expanded scope sets.
|
||||
- _identify scopes_ \
|
||||
Set of expanded scopes needed for identify (whoami) endpoints.
|
||||
Set of expanded scopes needed for identity (whoami) endpoints.
|
||||
```
|
||||
|
||||
(resolving-roles-scopes-target)=
|
||||
|
||||
## Resolving roles and scopes
|
||||
|
||||
**Resolving roles** refers to determining which roles a user, service, or group has, extracting the list of scopes from each role and combining them into a single set of scopes.
|
||||
**Resolving roles** involves determining which roles a user, service, or group has, extracting the list of scopes from each role and combining them into a single set of scopes.
|
||||
|
||||
**Resolving scopes** involves expanding scopes into all their possible subscopes (_expanded scopes_), parsing them into format used for access evaluation (_parsed scopes_) and, if applicable, comparing two sets of scopes (_intersection_). All procedures take into account the scope hierarchy, {ref}`vertical <vertical-filtering-target>` and {ref}`horizontal filtering <horizontal-filtering-target>`, limiting or elevated permissions (`read:<resource>` or `admin:<resource>`, respectively), and metascopes.
|
||||
**Resolving scopes** involves expanding scopes into all their possible subscopes (_expanded scopes_), parsing them into the format used for access evaluation (_parsed scopes_) and, if applicable, comparing two sets of scopes (_intersection_). All procedures take into account the scope hierarchy, {ref}`vertical <vertical-filtering-target>` and {ref}`horizontal filtering <horizontal-filtering-target>`, limiting or elevated permissions (`read:<resource>` or `admin:<resource>`, respectively), and metascopes.
|
||||
|
||||
Roles and scopes are resolved on several occasions, for example when requesting an API token with specific scopes or making an API request. The following sections provide more details.
|
||||
Roles and scopes are resolved on several occasions, for example when requesting an API token with specific scopes or when making an API request. The following sections provide more details.
|
||||
|
||||
(requesting-api-token-target)=
|
||||
|
||||
@@ -43,25 +43,24 @@ Prior to 3.0, tokens stored _roles_,
|
||||
which meant their scopes were resolved on each request.
|
||||
:::
|
||||
|
||||
API tokens grant access to JupyterHub's APIs. The RBAC framework allows for requesting tokens with specific permissions.
|
||||
API tokens grant access to JupyterHub's APIs. The Role Based Access Control (RBAC) framework allows for the requesting of tokens with specific permissions.
|
||||
|
||||
RBAC is involved in several stages of the OAuth token flow.
|
||||
|
||||
When requesting a token via the tokens API (`/users/:name/tokens`), or the token page (`/hub/token`),
|
||||
if no scopes are requested, the token is issued with the permissions stored on the default `token` role
|
||||
(providing the requester is allowed to create the token).
|
||||
(provided the requester is allowed to create the token).
|
||||
|
||||
OAuth tokens are also requested via OAuth flow
|
||||
|
||||
If the token is requested with any scopes, the permissions of requesting entity are checked against the requested permissions to ensure the token would not grant its owner additional privileges.
|
||||
|
||||
If, due to modifications of permissions of the token or token owner,
|
||||
at API request time a token has any scopes that its owner does not,
|
||||
those scopes are removed.
|
||||
If a token has any scopes that its owner does not possess
|
||||
at the time of making the API request, those scopes are removed.
|
||||
The API request is resolved without additional errors using the scope _intersection_;
|
||||
the Hub logs a warning in this case (see {ref}`Figure 2 <api-request-chart>`).
|
||||
|
||||
Resolving a token's scope (yellow box in {ref}`Figure 1 <token-request-chart>`) corresponds to resolving all the token's owner roles (including the roles associated with their groups) and the token's own scopes into a set of scopes. The two sets are compared (Resolve the scopes box in orange in {ref}`Figure 1 <token-request-chart>`), taking into account the scope hierarchy.
|
||||
Resolving a token's scope (yellow box in {ref}`Figure 1 <token-request-chart>`) corresponds to resolving all the roles of the token's owner (including the roles associated with their groups) and the token's own scopes into a set of scopes. The two sets are compared (Resolve the scopes box in orange in {ref}`Figure 1 <token-request-chart>`), taking into account the scope hierarchy.
|
||||
If the token's scopes are a subset of the token owner's scopes, the token is issued with the requested scopes; if not, JupyterHub will raise an error.
|
||||
|
||||
{ref}`Figure 1 <token-request-chart>` below illustrates the steps involved. The orange rectangles highlight where in the process the roles and scopes are resolved.
|
||||
@@ -75,10 +74,10 @@ Figure 1. Resolving roles and scopes during API token request
|
||||
|
||||
### Making an API request
|
||||
|
||||
With the RBAC framework, each authenticated JupyterHub API request is guarded by a scope decorator that specifies which scopes are required to gain the access to the API.
|
||||
With the RBAC framework, each authenticated JupyterHub API request is guarded by a scope decorator that specifies which scopes are required in order to gain the access to the API.
|
||||
|
||||
When an API request is performed, the requesting API token's scopes are again intersected with its owner's (yellow box in {ref}`Figure 2 <api-request-chart>`) to ensure the token does not grant more permissions than its owner has at the request time (e.g., due to changing/losing roles).
|
||||
If the owner's roles do not include some scopes of the token's scopes, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being passed on. In the case of no _intersection_, an empty set of scopes will be used.
|
||||
When an API request is made, the requesting API token's scopes are again intersected with its owner's (yellow box in {ref}`Figure 2 <api-request-chart>`) to ensure that the token does not grant more permissions than its owner has at the request time (e.g., due to changing/losing roles).
|
||||
If the owner's roles do not include some scopes of the token, only the _intersection_ of the token's and owner's scopes will be used. For example, using a token with scope `users` whose owner's role scope is `read:users:name` will result in only the `read:users:name` scope being passed on. In the case of no _intersection_, an empty set of scopes will be used.
|
||||
|
||||
The passed scopes are compared to the scopes required to access the API as follows:
|
||||
|
||||
@@ -86,7 +85,7 @@ The passed scopes are compared to the scopes required to access the API as follo
|
||||
|
||||
- if that is not the case, another check is utilized to determine if subscopes of the required API scopes can be found in the passed scope set:
|
||||
|
||||
- if found, the RBAC framework employs the {ref}`filtering <vertical-filtering-target>` procedures to refine the API response to access only resource attributes corresponding to the passed scopes. For example, providing a scope `read:users:activity!group=class-C` for the _GET /users_ API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model
|
||||
- if found, the RBAC framework employs the {ref}`filtering <vertical-filtering-target>` procedures to refine the API response to access only resource attributes corresponding to the passed scopes. For example, providing a scope `read:users:activity!group=class-C` for the `GET /users` API will return a list of user models from group `class-C` containing only the `last_activity` attribute for each user model
|
||||
|
||||
- if not found, the access to API is denied
|
||||
|
||||
|
||||
@@ -5,15 +5,15 @@ deployment with the following assumptions:
|
||||
|
||||
- Running JupyterHub on a single cloud server
|
||||
- Using SSL on the standard HTTPS port 443
|
||||
- Using GitHub OAuth (using oauthenticator) for login
|
||||
- Using GitHub OAuth (using [OAuthenticator](https://oauthenticator.readthedocs.io/en/latest)) for login
|
||||
- Using the default spawner (to configure other spawners, uncomment and edit
|
||||
`spawner_class` as well as follow the instructions for your desired spawner)
|
||||
- Users exist locally on the server
|
||||
- Users' notebooks to be served from `~/assignments` to allow users to browse
|
||||
for notebooks within other users' home directories
|
||||
- You want the landing page for each user to be a `Welcome.ipynb` notebook in
|
||||
their assignments directory.
|
||||
- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`.
|
||||
their assignments directory
|
||||
- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`
|
||||
|
||||
The `jupyterhub_config.py` file would have these settings:
|
||||
|
||||
@@ -69,7 +69,7 @@ c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
|
||||
```
|
||||
|
||||
Using the GitHub Authenticator requires a few additional
|
||||
environment variable to be set prior to launching JupyterHub:
|
||||
environment variables to be set prior to launching JupyterHub:
|
||||
|
||||
```bash
|
||||
export GITHUB_CLIENT_ID=github_id
|
||||
@@ -79,3 +79,5 @@ export CONFIGPROXY_AUTH_TOKEN=super-secret
|
||||
# append log output to log file /var/log/jupyterhub.log
|
||||
jupyterhub -f /etc/jupyterhub/jupyterhub_config.py &>> /var/log/jupyterhub.log
|
||||
```
|
||||
|
||||
Visit the [Github OAuthenticator reference](https://oauthenticator.readthedocs.io/en/latest/api/gen/oauthenticator.github.html) to see the full list of options for configuring Github OAuth with JupyterHub.
|
||||
|
||||
@@ -14,7 +14,7 @@ satisfy the following:
|
||||
- After testing, the server in question should be able to score at least an A on the
|
||||
Qualys SSL Labs [SSL Server Test](https://www.ssllabs.com/ssltest/)
|
||||
|
||||
Let's start out with needed JupyterHub configuration in `jupyterhub_config.py`:
|
||||
Let's start out with the needed JupyterHub configuration in `jupyterhub_config.py`:
|
||||
|
||||
```python
|
||||
# Force the proxy to only listen to connections to 127.0.0.1 (on port 8000)
|
||||
@@ -30,15 +30,15 @@ This can take a few minutes:
|
||||
openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096
|
||||
```
|
||||
|
||||
## nginx
|
||||
## Nginx
|
||||
|
||||
This **`nginx` config file** is fairly standard fare except for the two
|
||||
`location` blocks within the main section for HUB.DOMAIN.tld.
|
||||
To create a new site for jupyterhub in your nginx config, make a new file
|
||||
To create a new site for jupyterhub in your Nginx config, make a new file
|
||||
in `sites.enabled`, e.g. `/etc/nginx/sites.enabled/jupyterhub.conf`:
|
||||
|
||||
```bash
|
||||
# top-level http config for websocket headers
|
||||
# Top-level HTTP config for WebSocket headers
|
||||
# If Upgrade is defined, Connection = upgrade
|
||||
# If Upgrade is empty, Connection = close
|
||||
map $http_upgrade $connection_upgrade {
|
||||
@@ -51,7 +51,7 @@ server {
|
||||
listen 80;
|
||||
server_name HUB.DOMAIN.TLD;
|
||||
|
||||
# Tell all requests to port 80 to be 302 redirected to HTTPS
|
||||
# Redirect the request to HTTPS
|
||||
return 302 https://$host$request_uri;
|
||||
}
|
||||
|
||||
@@ -101,10 +101,10 @@ server {
|
||||
If `nginx` is not running on port 443, substitute `$http_host` for `$host` on
|
||||
the lines setting the `Host` header.
|
||||
|
||||
`nginx` will now be the front facing element of JupyterHub on `443` which means
|
||||
`nginx` will now be the front-facing element of JupyterHub on `443` which means
|
||||
it is also free to bind other servers, like `NO_HUB.DOMAIN.TLD` to the same port
|
||||
on the same machine and network interface. In fact, one can simply use the same
|
||||
server blocks as above for `NO_HUB` and simply add line for the root directory
|
||||
server blocks as above for `NO_HUB` and simply add a line for the root directory
|
||||
of the site as well as the applicable location call:
|
||||
|
||||
```bash
|
||||
@@ -112,7 +112,7 @@ server {
|
||||
listen 80;
|
||||
server_name NO_HUB.DOMAIN.TLD;
|
||||
|
||||
# Tell all requests to port 80 to be 302 redirected to HTTPS
|
||||
# Redirect the request to HTTPS
|
||||
return 302 https://$host$request_uri;
|
||||
}
|
||||
|
||||
@@ -143,12 +143,12 @@ Now restart `nginx`, restart the JupyterHub, and enjoy accessing
|
||||
`https://HUB.DOMAIN.TLD` while serving other content securely on
|
||||
`https://NO_HUB.DOMAIN.TLD`.
|
||||
|
||||
### SELinux permissions for nginx
|
||||
### SELinux permissions for Nginx
|
||||
|
||||
On distributions with SELinux enabled (e.g. Fedora), one may encounter permission errors
|
||||
when the nginx service is started.
|
||||
when the Nginx service is started.
|
||||
|
||||
We need to allow nginx to perform network relay and connect to the jupyterhub port. The
|
||||
We need to allow Nginx to perform network relay and connect to the JupyterHub port. The
|
||||
following commands do that:
|
||||
|
||||
```bash
|
||||
@@ -157,26 +157,26 @@ setsebool -P httpd_can_network_relay 1
|
||||
setsebool -P httpd_can_network_connect 1
|
||||
```
|
||||
|
||||
Replace 8000 with the port the jupyterhub server is running from.
|
||||
Replace 8000 with the port the JupyterHub server is running from.
|
||||
|
||||
## Apache
|
||||
|
||||
As with nginx above, you can use [Apache](https://httpd.apache.org) as the reverse proxy.
|
||||
First, we will need to enable the apache modules that we are going to need:
|
||||
As with Nginx above, you can use [Apache](https://httpd.apache.org) as the reverse proxy.
|
||||
First, we will need to enable the Apache modules that we are going to need:
|
||||
|
||||
```bash
|
||||
a2enmod ssl rewrite proxy headers proxy_http proxy_wstunnel
|
||||
```
|
||||
|
||||
Our Apache configuration is equivalent to the nginx configuration above:
|
||||
Our Apache configuration is equivalent to the Nginx configuration above:
|
||||
|
||||
- Redirect HTTP to HTTPS
|
||||
- Good SSL Configuration
|
||||
- Support for websockets on any proxied URL
|
||||
- Support for WebSocket on any proxied URL
|
||||
- JupyterHub is running locally at http://127.0.0.1:8000
|
||||
|
||||
```bash
|
||||
# redirect HTTP to HTTPS
|
||||
# Redirect HTTP to HTTPS
|
||||
Listen 80
|
||||
<VirtualHost HUB.DOMAIN.TLD:80>
|
||||
ServerName HUB.DOMAIN.TLD
|
||||
@@ -188,26 +188,26 @@ Listen 443
|
||||
|
||||
ServerName HUB.DOMAIN.TLD
|
||||
|
||||
# enable HTTP/2, if available
|
||||
# Enable HTTP/2, if available
|
||||
Protocols h2 http/1.1
|
||||
|
||||
# HTTP Strict Transport Security (mod_headers is required) (63072000 seconds)
|
||||
Header always set Strict-Transport-Security "max-age=63072000"
|
||||
|
||||
# configure SSL
|
||||
# Configure SSL
|
||||
SSLEngine on
|
||||
SSLCertificateFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem
|
||||
SSLOpenSSLConfCmd DHParameters /etc/ssl/certs/dhparam.pem
|
||||
|
||||
# intermediate configuration from ssl-config.mozilla.org (2022-03-03)
|
||||
# Please note, that this configuration might be out-dated - please update it accordingly using https://ssl-config.mozilla.org/
|
||||
# Intermediate configuration from SSL-config.mozilla.org (2022-03-03)
|
||||
# Please note, that this configuration might be outdated - please update it accordingly using https://ssl-config.mozilla.org/
|
||||
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
|
||||
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
|
||||
SSLHonorCipherOrder off
|
||||
SSLSessionTickets off
|
||||
|
||||
# Use RewriteEngine to handle websocket connection upgrades
|
||||
# Use RewriteEngine to handle WebSocket connection upgrades
|
||||
RewriteEngine On
|
||||
RewriteCond %{HTTP:Connection} Upgrade [NC]
|
||||
RewriteCond %{HTTP:Upgrade} websocket [NC]
|
||||
@@ -224,7 +224,7 @@ Listen 443
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
In case of the need to run the jupyterhub under /jhub/ or other location please use the below configurations:
|
||||
In case of the need to run JupyterHub under /jhub/ or another location please use the below configurations:
|
||||
|
||||
- JupyterHub running locally at http://127.0.0.1:8000/jhub/ or other location
|
||||
|
||||
@@ -241,7 +241,7 @@ httpd.conf amendments:
|
||||
jupyterhub_config.py amendments:
|
||||
|
||||
```bash
|
||||
--The public facing URL of the whole JupyterHub application.
|
||||
--This is the address on which the proxy will bind. Sets protocol, ip, base_url
|
||||
--The public-facing URL of the whole JupyterHub application.
|
||||
--This is the address on which the proxy will bind. Sets protocol, IP, base_url
|
||||
c.JupyterHub.bind_url = 'http://127.0.0.1:8000/jhub/'
|
||||
```
|
||||
|
||||
@@ -7,8 +7,8 @@ environment in some way.
|
||||
Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook
|
||||
server, most configuration and documentation that applies to Jupyter Notebook
|
||||
applies to the single-user environments. Configuration of user environments
|
||||
typically does not occur through JupyterHub itself, but rather through system-
|
||||
wide configuration of Jupyter, which is inherited by `jupyterhub-singleuser`.
|
||||
typically does not occur through JupyterHub itself, but rather through the system-wide
|
||||
configuration of Jupyter, which is inherited by `jupyterhub-singleuser`.
|
||||
|
||||
**Tip:** When searching for configuration tips for JupyterHub user
|
||||
environments, try removing JupyterHub from your search because there are a lot
|
||||
@@ -17,10 +17,10 @@ configuration is the same.
|
||||
|
||||
This section will focus on user environments, including:
|
||||
|
||||
- Installing packages
|
||||
- Configuring Jupyter and IPython
|
||||
- Installing kernelspecs
|
||||
- Using containers vs. multi-user hosts
|
||||
- [Installing packages](#installing-packages)
|
||||
- [Configuring Jupyter and IPython](#configuring-jupyter-and-ipython)
|
||||
- [Installing kernelspecs](#installing-kernelspecs)
|
||||
- [Using containers vs. multi-user hosts](#multi-user-hosts-vs-containers)
|
||||
|
||||
## Installing packages
|
||||
|
||||
@@ -30,7 +30,7 @@ system-wide or in a shared environment.
|
||||
This installation location should always be in the same environment that
|
||||
`jupyterhub-singleuser` itself is installed in, and must be _readable and
|
||||
executable_ by your users. If you want users to be able to install additional
|
||||
packages, it must also be _writable_ by your users.
|
||||
packages, the installation location must also be _writable_ by your users.
|
||||
|
||||
If you are using a standard system Python install, you would use:
|
||||
|
||||
@@ -109,7 +109,7 @@ they are available to all of your users. This means installing kernelspecs
|
||||
either system-wide (e.g. in /usr/local/) or in the `sys.prefix` of JupyterHub
|
||||
itself.
|
||||
|
||||
Jupyter kernelspec installation is system wide by default, but some kernels
|
||||
Jupyter kernelspec installation is system-wide by default, but some kernels
|
||||
may default to installing kernelspecs in your home directory. These will need
|
||||
to be moved system-wide to ensure that they are accessible.
|
||||
|
||||
@@ -143,12 +143,12 @@ depending on what Spawner you are using.
|
||||
The first category is a **shared system (multi-user host)** where
|
||||
each user has a JupyterHub account and a home directory as well as being
|
||||
a real system user. In this example, shared configuration and installation
|
||||
must be in a 'system-wide' location, such as `/etc/` or `/usr/local`
|
||||
must be in a 'system-wide' location, such as `/etc/`, or `/usr/local`
|
||||
or a custom prefix such as `/opt/conda`.
|
||||
|
||||
When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or
|
||||
DockerSpawner), the 'system-wide' environment is really the container image
|
||||
which you are using for users.
|
||||
that you are using for users.
|
||||
|
||||
In both cases, you want to _avoid putting configuration in user home
|
||||
directories_ because users can change those configuration settings. Also,
|
||||
@@ -157,7 +157,7 @@ difficult for admins to update later.
|
||||
|
||||
## Named servers
|
||||
|
||||
By default, in a JupyterHub deployment each user has exactly one server.
|
||||
By default, in a JupyterHub deployment, each user has exactly one server.
|
||||
|
||||
JupyterHub can, however, have multiple servers per user.
|
||||
This is most useful in deployments where users can configure the environment
|
||||
@@ -181,7 +181,7 @@ as well as the admin page:
|
||||
|
||||
|
||||
Named servers can be accessed, created, started, stopped, and deleted
|
||||
from these pages. Activity tracking is now per-server as well.
|
||||
from these pages. Activity tracking is now per server as well.
|
||||
|
||||
The number of named servers per user can be limited by setting a constant value:
|
||||
|
||||
@@ -207,9 +207,9 @@ If `named_server_limit_per_user` is set to `0`, no limit is enforced.
|
||||
|
||||
(classic-notebook-ui)=
|
||||
|
||||
## Switching back to classic notebook
|
||||
## Switching back to the classic notebook
|
||||
|
||||
By default the single-user server launches JupyterLab,
|
||||
By default, the single-user server launches JupyterLab,
|
||||
which is based on [Jupyter Server][].
|
||||
This is the default server when running JupyterHub ≥ 2.0.
|
||||
You can switch to using the legacy Jupyter Notebook server by setting the `JUPYTERHUB_SINGLEUSER_APP` environment variable
|
||||
@@ -223,11 +223,11 @@ export JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp'
|
||||
[jupyter notebook]: https://jupyter-notebook.readthedocs.io
|
||||
|
||||
:::{versionchanged} 2.0
|
||||
JupyterLab is now the default singleuser UI, if available,
|
||||
JupyterLab is now the default single-user UI, if available,
|
||||
which is based on the [Jupyter Server][],
|
||||
no longer the legacy [Jupyter Notebook][] server.
|
||||
JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`),
|
||||
and Jupyter server could be selected by specifying
|
||||
and the Jupyter server could be selected by specifying
|
||||
|
||||
```python
|
||||
# jupyterhub_config.py
|
||||
|
||||
@@ -267,8 +267,8 @@ Spawners mainly do one thing: launch a command in an environment.
|
||||
|
||||
The command-line is constructed from user configuration:
|
||||
|
||||
- Spawner.cmd (default: `['jupterhub-singleuser']`)
|
||||
- Spawner.args (cli args to pass to the cmd, default: empty)
|
||||
- Spawner.cmd (default: `['jupyterhub-singleuser']`)
|
||||
- Spawner.args (CLI args to pass to the cmd, default: empty)
|
||||
|
||||
where the configuration:
|
||||
|
||||
@@ -319,12 +319,12 @@ Optional environment variables, depending on configuration:
|
||||
- JUPYTERHUB_ROOT_DIR - the root directory of the server (notebook directory), when Spawner.notebook_dir is defined (new in 2.0)
|
||||
- JUPYTERHUB_DEFAULT_URL - the default URL for the server (for redirects from /user/:name/),
|
||||
if Spawner.default_url is defined
|
||||
(new in 2.0, previously passed via cli)
|
||||
(new in 2.0, previously passed via CLI)
|
||||
- JUPYTERHUB_DEBUG=1 - generic debug flag, sets maximum log level when Spawner.debug is True
|
||||
(new in 2.0, previously passed via cli)
|
||||
(new in 2.0, previously passed via CLI)
|
||||
- JUPYTERHUB_DISABLE_USER_CONFIG=1 - disable loading user config,
|
||||
sets maximum log level when Spawner.debug is True (new in 2.0,
|
||||
previously passed via cli)
|
||||
previously passed via CLI)
|
||||
|
||||
- JUPYTERHUB*[MEM|CPU]*[LIMIT_GUARANTEE] - the values of cpu and memory limits and guarantees.
|
||||
These are not expected to be enforced by the process,
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
The **Technical Overview** section gives you a high-level view of:
|
||||
|
||||
- JupyterHub's Subsystems: Hub, Proxy, Single-User Notebook Server
|
||||
- JupyterHub's major Subsystems: Hub, Proxy, Single-User Notebook Server
|
||||
- how the subsystems interact
|
||||
- the process from JupyterHub access to user login
|
||||
- JupyterHub's default behavior
|
||||
@@ -11,16 +11,16 @@ The **Technical Overview** section gives you a high-level view of:
|
||||
The goal of this section is to share a deeper technical understanding of
|
||||
JupyterHub and how it works.
|
||||
|
||||
## The Subsystems: Hub, Proxy, Single-User Notebook Server
|
||||
## The Major Subsystems: Hub, Proxy, Single-User Notebook Server
|
||||
|
||||
JupyterHub is a set of processes that together provide a single user Jupyter
|
||||
Notebook server for each person in a group. Three major subsystems are started
|
||||
JupyterHub is a set of processes that together, provide a single-user Jupyter
|
||||
Notebook server for each person in a group. Three subsystems are started
|
||||
by the `jupyterhub` command line program:
|
||||
|
||||
- **Hub** (Python/Tornado): manages user accounts, authentication, and
|
||||
coordinates Single User Notebook Servers using a Spawner.
|
||||
coordinates Single User Notebook Servers using a [Spawner](./spawners.md).
|
||||
|
||||
- **Proxy**: the public facing part of JupyterHub that uses a dynamic proxy
|
||||
- **Proxy**: the public-facing part of JupyterHub that uses a dynamic proxy
|
||||
to route HTTP requests to the Hub and Single User Notebook Servers.
|
||||
[configurable http proxy](https://github.com/jupyterhub/configurable-http-proxy)
|
||||
(node-http-proxy) is the default proxy.
|
||||
@@ -28,7 +28,7 @@ by the `jupyterhub` command line program:
|
||||
- **Single-User Notebook Server** (Python/Tornado): a dedicated,
|
||||
single-user, Jupyter Notebook server is started for each user on the system
|
||||
when the user logs in. The object that starts the single-user notebook
|
||||
servers is called a **Spawner**.
|
||||
servers is called a **[Spawner](./spawners.md)**.
|
||||
|
||||
|
||||
|
||||
@@ -41,8 +41,8 @@ The basic principles of operation are:
|
||||
|
||||
- The Hub spawns the proxy (in the default JupyterHub configuration)
|
||||
- The proxy forwards all requests to the Hub by default
|
||||
- The Hub handles login, and spawns single-user notebook servers on demand
|
||||
- The Hub configures the proxy to forward url prefixes to single-user notebook
|
||||
- The Hub handles login and spawns single-user notebook servers on demand
|
||||
- The Hub configures the proxy to forward URL prefixes to single-user notebook
|
||||
servers
|
||||
|
||||
The proxy is the only process that listens on a public interface. The Hub sits
|
||||
@@ -50,17 +50,16 @@ behind the proxy at `/hub`. Single-user servers sit behind the proxy at
|
||||
`/user/[username]`.
|
||||
|
||||
Different **[authenticators](./authenticators.md)** control access
|
||||
to JupyterHub. The default one (PAM) uses the user accounts on the server where
|
||||
to JupyterHub. The default one [(PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module) uses the user accounts on the server where
|
||||
JupyterHub is running. If you use this, you will need to create a user account
|
||||
on the system for each user on your team. Using other authenticators, you can
|
||||
on the system for each user on your team. However, using other authenticators you can
|
||||
allow users to sign in with e.g. a GitHub account, or with any single-sign-on
|
||||
system your organization has.
|
||||
|
||||
Next, **[spawners](./spawners.md)** control how JupyterHub starts
|
||||
the individual notebook server for each user. The default spawner will
|
||||
start a notebook server on the same machine running under their system username.
|
||||
The other main option is to start each server in a separate container, often
|
||||
using Docker.
|
||||
The other main option is to start each server in a separate container, often using [Docker](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/).
|
||||
|
||||
## The Process from JupyterHub Access to User Login
|
||||
|
||||
@@ -72,20 +71,20 @@ When a user accesses JupyterHub, the following events take place:
|
||||
- A single-user notebook server instance is [spawned](./spawners.md) for the
|
||||
logged-in user
|
||||
- When the single-user notebook server starts, the proxy is notified to forward
|
||||
requests to `/user/[username]/*` to the single-user notebook server.
|
||||
- A cookie is set on `/hub/`, containing an encrypted token. (Prior to version
|
||||
requests made to `/user/[username]/*`, to the single-user notebook server.
|
||||
- A [cookie](https://en.wikipedia.org/wiki/HTTP_cookie) is set on `/hub/`, containing an encrypted token. (Prior to version
|
||||
0.8, a cookie for `/user/[username]` was used too.)
|
||||
- The browser is redirected to `/user/[username]`, and the request is handled by
|
||||
the single-user notebook server.
|
||||
|
||||
The single-user server identifies the user with the Hub via OAuth:
|
||||
How does the single-user server identify the user with the Hub via OAuth?
|
||||
|
||||
- on request, the single-user server checks a cookie
|
||||
- if no cookie is set, redirect to the Hub for verification via OAuth
|
||||
- after verification at the Hub, the browser is redirected back to the
|
||||
- On request, the single-user server checks a cookie
|
||||
- If no cookie is set, the single-user server redirects to the Hub for verification via OAuth
|
||||
- After verification at the Hub, the browser is redirected back to the
|
||||
single-user server
|
||||
- the token is verified and stored in a cookie
|
||||
- if no user is identified, the browser is redirected back to `/hub/login`
|
||||
- The token is verified and stored in a cookie
|
||||
- If no user is identified, the browser is redirected back to `/hub/login`
|
||||
|
||||
## Default Behavior
|
||||
|
||||
@@ -111,7 +110,7 @@ working directory:
|
||||
This file needs to persist so that a **Hub** server restart will avoid
|
||||
invalidating cookies. Conversely, deleting this file and restarting the server
|
||||
effectively invalidates all login cookies. The cookie secret file is discussed
|
||||
in the [Cookie Secret section of the Security Settings document](../getting-started/security-basics.md).
|
||||
in the [Cookie Secret section of the Security Settings document](../getting-started/security-basics.rst).
|
||||
|
||||
The location of these files can be specified via configuration settings. It is
|
||||
recommended that these files be stored in standard UNIX filesystem locations,
|
||||
|
||||
@@ -84,5 +84,5 @@ template (for example, `login.html`) with:
|
||||
```
|
||||
|
||||
Extending `page.html` puts the message on all pages, but note that
|
||||
extending `page.html` take precedence over an extension of a specific
|
||||
extending `page.html` takes precedence over an extension of a specific
|
||||
page (unlike the variable-based approach above).
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
This document describes how JupyterHub routes requests.
|
||||
|
||||
This does not include the [REST API](./rest.md) urls.
|
||||
This does not include the [REST API](./rest.md) URLs.
|
||||
|
||||
In general, all URLs can be prefixed with `c.JupyterHub.base_url` to
|
||||
run the whole JupyterHub application on a prefix.
|
||||
|
||||
All authenticated handlers redirect to `/hub/login` to login users
|
||||
prior to being redirected back to the originating page.
|
||||
All authenticated handlers redirect to `/hub/login` to log-in users
|
||||
before being redirected back to the originating page.
|
||||
The returned request should preserve all query parameters.
|
||||
|
||||
## `/`
|
||||
@@ -25,12 +25,12 @@ This is an authenticated URL.
|
||||
|
||||
This handler redirects users to the default URL of the application,
|
||||
which defaults to the user's default server.
|
||||
That is, it redirects to `/hub/spawn` if the user's server is not running,
|
||||
or the server itself (`/user/:name`) if the server is running.
|
||||
That is, the handler redirects to `/hub/spawn` if the user's server is not running,
|
||||
or to the server itself (`/user/:name`) if the server is running.
|
||||
|
||||
This default url behavior can be customized in two ways:
|
||||
This default URL behavior can be customized in two ways:
|
||||
|
||||
To redirect users to the JupyterHub home page (`/hub/home`)
|
||||
First, to redirect users to the JupyterHub home page (`/hub/home`)
|
||||
instead of spawning their server,
|
||||
set `redirect_to_server` to False:
|
||||
|
||||
@@ -40,7 +40,7 @@ c.JupyterHub.redirect_to_server = False
|
||||
|
||||
This might be useful if you have a Hub where you expect
|
||||
users to be managing multiple server configurations
|
||||
and automatic spawning is not desirable.
|
||||
but automatic spawning is not desirable.
|
||||
|
||||
Second, you can customise the landing page to any page you like,
|
||||
such as a custom service you have deployed e.g. with course information:
|
||||
@@ -57,7 +57,7 @@ By default, the Hub home page has just one or two buttons
|
||||
for starting and stopping the user's server.
|
||||
|
||||
If named servers are enabled, there will be some additional
|
||||
tools for management of named servers.
|
||||
tools for management of the named servers.
|
||||
|
||||
_Version added: 1.0_ named server UI is new in 1.0.
|
||||
|
||||
@@ -65,7 +65,7 @@ _Version added: 1.0_ named server UI is new in 1.0.
|
||||
|
||||
This is the JupyterHub login page.
|
||||
If you have a form-based username+password login,
|
||||
such as the default PAMAuthenticator,
|
||||
such as the default [PAMAuthenticator](https://en.wikipedia.org/wiki/Pluggable_authentication_module),
|
||||
this page will render the login form.
|
||||
|
||||
|
||||
@@ -77,19 +77,19 @@ to login with the chosen service.
|
||||
|
||||
|
||||
|
||||
If you want to skip the user-interaction to initiate logging in
|
||||
via the button, you can set
|
||||
If you want to skip the user interaction and initiate login
|
||||
via the button, you can set:
|
||||
|
||||
```python
|
||||
c.Authenticator.auto_login = True
|
||||
```
|
||||
|
||||
This can be useful when the user is "already logged in" via some mechanism,
|
||||
but a handshake via redirects is necessary to complete the authentication with JupyterHub.
|
||||
This can be useful when the user is "already logged in" via some mechanism.
|
||||
However, a handshake via `redirects` is necessary to complete the authentication with JupyterHub.
|
||||
|
||||
## `/hub/logout`
|
||||
|
||||
Visiting `/hub/logout` clears cookies from the current browser.
|
||||
Visiting `/hub/logout` clears [cookies](https://en.wikipedia.org/wiki/HTTP_cookie) from the current browser.
|
||||
Note that **logging out does not stop a user's server(s)** by default.
|
||||
|
||||
If you would like to shut down user servers on logout,
|
||||
@@ -105,8 +105,8 @@ does not mean the user is no longer actively using their server from another mac
|
||||
## `/user/:username[/:servername]`
|
||||
|
||||
If a user's server is running, this URL is handled by the user's given server,
|
||||
not the Hub.
|
||||
The username is the first part and, if using named servers,
|
||||
not by the Hub.
|
||||
The username is the first part, and if using named servers,
|
||||
the server name is the second part.
|
||||
|
||||
If the user's server is _not_ running, this will be redirected to `/hub/user/:username/...`
|
||||
@@ -120,11 +120,11 @@ if the specified server were running).
|
||||
Handling this URL is the most complicated condition in JupyterHub,
|
||||
because there can be many states:
|
||||
|
||||
1. server is not active
|
||||
1. the server is not active
|
||||
a. user matches
|
||||
b. user doesn't match
|
||||
2. server is ready
|
||||
3. server is pending, but not ready
|
||||
2. the server is ready
|
||||
3. the server is pending, but not ready
|
||||
|
||||
If the server is pending spawn,
|
||||
the browser will be redirected to `/hub/spawn-pending/:username/:servername`
|
||||
@@ -140,39 +140,37 @@ Some checks are performed and a delay is added before redirecting back to `/user
|
||||
If something is really wrong, this can result in a redirect loop.
|
||||
|
||||
Visiting this page will never result in triggering the spawn of servers
|
||||
without additional user action (i.e. clicking the link on the page)
|
||||
without additional user action (i.e. clicking the link on the page).
|
||||
|
||||
|
||||
|
||||
_Version changed: 1.0_
|
||||
|
||||
Prior to 1.0, this URL itself was responsible for spawning servers,
|
||||
and served the progress page if it was pending,
|
||||
redirected to running servers, and
|
||||
This was useful because it made sure that requested servers were restarted after they stopped,
|
||||
but could also be harmful because unused servers would continuously be restarted if e.g.
|
||||
an idle JupyterLab frontend were open pointed at it,
|
||||
which constantly makes polling requests.
|
||||
Prior to 1.0, this URL itself was responsible for spawning servers.
|
||||
If the progress page was pending, the URL redirected it to running servers.
|
||||
This was useful because it made sure that the requested servers were restarted after they stopped.
|
||||
However, it could also be harmful because unused servers would continuously be restarted if e.g.
|
||||
an idle JupyterLab frontend that constantly makes polling requests was openly pointed at it.
|
||||
|
||||
### Special handling of API requests
|
||||
|
||||
Requests to `/user/:username[/:servername]/api/...` are assumed to be
|
||||
from applications connected to stopped servers.
|
||||
These are failed with 503 and an informative JSON error message
|
||||
indicating how to spawn the server.
|
||||
This is meant to help applications such as JupyterLab
|
||||
These requests fail with a `503` status code and an informative JSON error message
|
||||
that indicates how to spawn the server.
|
||||
This is meant to help applications such as JupyterLab,
|
||||
that are connected to a server that has stopped.
|
||||
|
||||
_Version changed: 1.0_
|
||||
|
||||
JupyterHub 0.9 failed these API requests with status 404,
|
||||
but 1.0 uses 503.
|
||||
JupyterHub version 0.9 failed these API requests with status `404`,
|
||||
but version 1.0 uses 503.
|
||||
|
||||
## `/user-redirect/...`
|
||||
|
||||
This URL is for sharing a URL that will redirect a user
|
||||
The `/user-redirect/...` URL is for sharing a URL that will redirect a user
|
||||
to a path on their own default server.
|
||||
This is useful when users have the same file at the same URL on their servers,
|
||||
This is useful when different users have the same file at the same URL on their servers,
|
||||
and you want a single link to give to any user that will open that file on their server.
|
||||
|
||||
e.g. a link to `/user-redirect/notebooks/Index.ipynb`
|
||||
@@ -194,7 +192,7 @@ that is intended to make it possible.
|
||||
### `/hub/spawn[/:username[/:servername]]`
|
||||
|
||||
Requesting `/hub/spawn` will spawn the default server for the current user.
|
||||
If `username` and optionally `servername` are specified,
|
||||
If the `username` and optionally `servername` are specified,
|
||||
then the specified server for the specified user will be spawned.
|
||||
Once spawn has been requested,
|
||||
the browser is redirected to `/hub/spawn-pending/...`.
|
||||
@@ -207,7 +205,7 @@ and a POST request will trigger the actual spawn and redirect.
|
||||
|
||||
_Version added: 1.0_
|
||||
|
||||
1.0 adds the ability to specify username and servername.
|
||||
1.0 adds the ability to specify `username` and `servername`.
|
||||
Prior to 1.0, only `/hub/spawn` was recognized for the default server.
|
||||
|
||||
_Version changed: 1.0_
|
||||
@@ -247,7 +245,7 @@ against the [JupyterHub REST API](./rest.md).
|
||||
|
||||
Administrators can take various administrative actions from this page:
|
||||
|
||||
1. add/remove users
|
||||
2. grant admin privileges
|
||||
3. start/stop user servers
|
||||
4. shutdown JupyterHub itself
|
||||
- add/remove users
|
||||
- grant admin privileges
|
||||
- start/stop user servers
|
||||
- shutdown JupyterHub itself
|
||||
|
||||
@@ -5,7 +5,7 @@ The **Security Overview** section helps you learn about:
|
||||
- the design of JupyterHub with respect to web security
|
||||
- the semi-trusted user
|
||||
- the available mitigations to protect untrusted users from each other
|
||||
- the value of periodic security audits.
|
||||
- the value of periodic security audits
|
||||
|
||||
This overview also helps you obtain a deeper understanding of how JupyterHub
|
||||
works.
|
||||
@@ -32,7 +32,7 @@ servers) as a single website (i.e. single domain).
|
||||
|
||||
To protect users from each other, a user must **never** be able to write arbitrary
|
||||
HTML and serve it to another user on the Hub's domain. JupyterHub's
|
||||
authentication setup prevents a user writing arbitrary HTML and serving it to
|
||||
authentication setup prevents a user from writing arbitrary HTML and serving it to
|
||||
another user because only the owner of a given single-user notebook server is
|
||||
allowed to view user-authored pages served by the given single-user notebook
|
||||
server.
|
||||
@@ -101,8 +101,8 @@ pose additional risk to the web application's security.
|
||||
|
||||
### Encrypt internal connections with SSL/TLS
|
||||
|
||||
By default, all communication on the server, between the proxy, hub, and single
|
||||
-user notebooks is performed unencrypted. Setting the `internal_ssl` flag in
|
||||
By default, all communications on the server, between the proxy, hub, and single
|
||||
-user notebooks are performed unencrypted. Setting the `internal_ssl` flag in
|
||||
`jupyterhub_config.py` secures the aforementioned routes. Turning this
|
||||
feature on does require that the enabled `Spawner` can use the certificates
|
||||
generated by the `Hub` (the default `LocalProcessSpawner` can, for instance).
|
||||
@@ -118,7 +118,7 @@ extend to securing the `tcp` sockets as well.
|
||||
|
||||
## Security audits
|
||||
|
||||
We recommend that you do periodic reviews of your deployment's security. It's
|
||||
We recommend that you do periodic reviews of your deployment's security. It is
|
||||
good practice to keep JupyterHub, configurable-http-proxy, and nodejs
|
||||
versions up to date.
|
||||
|
||||
@@ -129,7 +129,7 @@ A handy website for testing your deployment is
|
||||
|
||||
## Vulnerability reporting
|
||||
|
||||
If you believe you’ve found a security vulnerability in JupyterHub, or any
|
||||
If you believe you have found a security vulnerability in JupyterHub, or any
|
||||
Jupyter project, please report it to
|
||||
[security@ipython.org](mailto:security@ipython.org). If you prefer to encrypt
|
||||
your security reports, you can use [this PGP public
|
||||
|
||||
@@ -1,35 +1,9 @@
|
||||
# Troubleshooting
|
||||
|
||||
When troubleshooting, you may see unexpected behaviors or receive an error
|
||||
message. This section provide links for identifying the cause of the
|
||||
message. This section provides links for identifying the cause of the
|
||||
problem and how to resolve it.
|
||||
|
||||
[_Behavior_](#behavior)
|
||||
|
||||
- JupyterHub proxy fails to start
|
||||
- sudospawner fails to run
|
||||
- What is the default behavior when none of the lists (admin, allowed,
|
||||
allowed groups) are set?
|
||||
- JupyterHub Docker container not accessible at localhost
|
||||
|
||||
[_Errors_](#errors)
|
||||
|
||||
- 500 error after spawning my single-user server
|
||||
|
||||
[_How do I...?_](#how-do-i)
|
||||
|
||||
- Use a chained SSL certificate
|
||||
- Install JupyterHub without a network connection
|
||||
- I want access to the whole filesystem, but still default users to their home directory
|
||||
- How do I increase the number of pySpark executors on YARN?
|
||||
- How do I use JupyterLab's prerelease version with JupyterHub?
|
||||
- How do I set up JupyterHub for a workshop (when users are not known ahead of time)?
|
||||
- How do I set up rotating daily logs?
|
||||
- Toree integration with HDFS rack awareness script
|
||||
- Where do I find Docker images and Dockerfiles related to JupyterHub?
|
||||
|
||||
[_Troubleshooting commands_](#troubleshooting-commands)
|
||||
|
||||
## Behavior
|
||||
|
||||
### JupyterHub proxy fails to start
|
||||
@@ -40,9 +14,9 @@ If you have tried to start the JupyterHub proxy and it fails to start:
|
||||
`c.JupyterHub.ip = '*'`; if it is, try `c.JupyterHub.ip = ''`
|
||||
- Try starting with `jupyterhub --ip=0.0.0.0`
|
||||
|
||||
**Note**: If this occurs on Ubuntu/Debian, check that the you are using a
|
||||
recent version of node. Some versions of Ubuntu/Debian come with a version
|
||||
of node that is very old, and it is necessary to update node.
|
||||
**Note**: If this occurs on Ubuntu/Debian, check that you are using a
|
||||
recent version of [Node](https://nodejs.org). Some versions of Ubuntu/Debian come with a version
|
||||
of Node that is very old, and it is necessary to update Node.
|
||||
|
||||
### sudospawner fails to run
|
||||
|
||||
@@ -61,24 +35,24 @@ to the config file, `jupyterhub_config.py`.
|
||||
### What is the default behavior when none of the lists (admin, allowed, allowed groups) are set?
|
||||
|
||||
When nothing is given for these lists, there will be no admins, and all users
|
||||
who can authenticate on the system (i.e. all the unix users on the server with
|
||||
who can authenticate on the system (i.e. all the Unix users on the server with
|
||||
a password) will be allowed to start a server. The allowed username set lets you limit
|
||||
this to a particular set of users, and admin_users lets you specify who
|
||||
among them may use the admin interface (not necessary, unless you need to do
|
||||
things like inspect other users' servers, or modify the user list at runtime).
|
||||
things like inspect other users' servers or modify the user list at runtime).
|
||||
|
||||
### JupyterHub Docker container not accessible at localhost
|
||||
|
||||
Even though the command to start your Docker container exposes port 8000
|
||||
(`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`),
|
||||
it is possible that the IP address itself is not accessible/visible. As a result
|
||||
it is possible that the IP address itself is not accessible/visible. As a result,
|
||||
when you try http://localhost:8000 in your browser, you are unable to connect
|
||||
even though the container is running properly. One workaround is to explicitly
|
||||
tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this
|
||||
command:
|
||||
`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000`
|
||||
|
||||
### How can I kill ports from JupyterHub managed services that have been orphaned?
|
||||
### How can I kill ports from JupyterHub-managed services that have been orphaned?
|
||||
|
||||
I started JupyterHub + nbgrader on the same host without containers. When I try to restart JupyterHub + nbgrader with this configuration, errors appear that the service accounts cannot start because the ports are being used.
|
||||
|
||||
@@ -92,7 +66,7 @@ Where `<service_port>` is the port used by the nbgrader course service. This con
|
||||
|
||||
### Why am I getting a Spawn failed error message?
|
||||
|
||||
After successfully logging in to JupyterHub with a compatible authenticators, I get a 'Spawn failed' error message in the browser. The JupyterHub logs have `jupyterhub KeyError: "getpwnam(): name not found: <my_user_name>`.
|
||||
After successfully logging in to JupyterHub with a compatible authenticator, I get a 'Spawn failed' error message in the browser. The JupyterHub logs have `jupyterhub KeyError: "getpwnam(): name not found: <my_user_name>`.
|
||||
|
||||
This issue occurs when the authenticator requires a local system user to exist. In these cases, you need to use a spawner
|
||||
that does not require an existing system user account, such as `DockerSpawner` or `KubeSpawner`.
|
||||
@@ -109,23 +83,9 @@ sudo MY_ENV=abc123 \
|
||||
/srv/jupyterhub/jupyterhub
|
||||
```
|
||||
|
||||
### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner?
|
||||
|
||||
Use `docker logs <container>` where `<container>` is the container name defined within `docker-compose.yml`. For example, to view the logs of the JupyterHub container use:
|
||||
|
||||
docker logs hub
|
||||
|
||||
By default, the user's notebook server is named `jupyter-<username>` where `username` is the user's username within JupyterHub's db. So if you wanted to see the logs for user `foo` you would use:
|
||||
|
||||
docker logs jupyter-foo
|
||||
|
||||
You can also tail logs to view them in real time using the `-f` option:
|
||||
|
||||
docker logs -f hub
|
||||
|
||||
## Errors
|
||||
|
||||
### 500 error after spawning my single-user server
|
||||
### Error 500 after spawning my single-user server
|
||||
|
||||
You receive a 500 error when accessing the URL `/user/<your_name>/...`.
|
||||
This is often seen when your single-user server cannot verify your user cookie
|
||||
@@ -185,10 +145,10 @@ If you receive a 403 error, the API token for the single-user server is likely
|
||||
invalid. Commonly, the 403 error is caused by resetting the JupyterHub
|
||||
database (either removing jupyterhub.sqlite or some other action) while
|
||||
leaving single-user servers running. This happens most frequently when using
|
||||
DockerSpawner, because Docker's default behavior is to stop/start containers
|
||||
which resets the JupyterHub database, rather than destroying and recreating
|
||||
DockerSpawner because Docker's default behavior is to stop/start containers
|
||||
that reset the JupyterHub database, rather than destroying and recreating
|
||||
the container every time. This means that the same API token is used by the
|
||||
server for its whole life, until the container is rebuilt.
|
||||
server for its whole life until the container is rebuilt.
|
||||
|
||||
The fix for this Docker case is to remove any Docker containers seeing this
|
||||
issue (typically all containers created before a certain point in time):
|
||||
@@ -201,14 +161,14 @@ your server again.
|
||||
|
||||
##### Proxy settings (403 GET)
|
||||
|
||||
When your whole JupyterHub sits behind a organization proxy (_not_ a reverse proxy like NGINX as part of your setup and _not_ the configurable-http-proxy) the environment variables `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy` and `https_proxy` might be set. This confuses the jupyterhub-singleuser servers: When connecting to the Hub for authorization they connect via the proxy instead of directly connecting to the Hub on localhost. The proxy might deny the request (403 GET). This results in the singleuser server thinking it has a wrong auth token. To circumvent this you should add `<hub_url>,<hub_ip>,localhost,127.0.0.1` to the environment variables `NO_PROXY` and `no_proxy`.
|
||||
When your whole JupyterHub sits behind an organization proxy (_not_ a reverse proxy like NGINX as part of your setup and _not_ the configurable-http-proxy) the environment variables `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, and `https_proxy` might be set. This confuses the Jupyterhub single-user servers: When connecting to the Hub for authorization they connect via the proxy instead of directly connecting to the Hub on localhost. The proxy might deny the request (403 GET). This results in the single-user server thinking it has the wrong auth token. To circumvent this you should add `<hub_url>,<hub_ip>,localhost,127.0.0.1` to the environment variables `NO_PROXY` and `no_proxy`.
|
||||
|
||||
### Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error
|
||||
|
||||
[JupyterHub services](https://jupyterhub.readthedocs.io/en/stable/reference/services.html) allow processes to interact with JupyterHub's REST API. Example use-cases include:
|
||||
|
||||
- **Secure Testing**: provide a canonical Jupyter Notebook for testing production data to reduce the number of entry points into production systems.
|
||||
- **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such grading assignments.
|
||||
- **Grading Assignments**: provide access to shared Jupyter Notebooks that may be used for management tasks such as grading assignments.
|
||||
- **Private Dashboards**: share dashboards with certain group members.
|
||||
|
||||
If possible, try to run the Jupyter Notebook as an externally managed service with one of the provided [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks).
|
||||
@@ -222,7 +182,7 @@ If you launch a Jupyter Notebook with the `jupyterhub-singleuser` command direct
|
||||
Did you launch it manually?
|
||||
```
|
||||
|
||||
If you plan on testing `jupyterhub-singleuser` independently from JupyterHub, then you can set the api token environment variable. For example, if were to run the single-user Jupyter Notebook on the host, then:
|
||||
If you plan on testing `jupyterhub-singleuser` independently from JupyterHub, then you can set the API token environment variable. For example, if you were to run the single-user Jupyter Notebook on the host, then:
|
||||
|
||||
export JUPYTERHUB_API_TOKEN=my_secret_token
|
||||
jupyterhub-singleuser
|
||||
@@ -256,7 +216,7 @@ You would then set in your `jupyterhub_config.py` file the `ssl_key` and
|
||||
#### Example
|
||||
|
||||
Your certificate provider gives you the following files: `example_host.crt`,
|
||||
`Entrust_L1Kroot.txt` and `Entrust_Root.txt`.
|
||||
`Entrust_L1Kroot.txt`, and `Entrust_Root.txt`.
|
||||
|
||||
Concatenate the files appending the chain cert and root cert to your host cert:
|
||||
|
||||
@@ -289,7 +249,7 @@ with npmbox:
|
||||
python3 -m pip wheel jupyterhub
|
||||
npmbox configurable-http-proxy
|
||||
|
||||
### I want access to the whole filesystem, but still default users to their home directory
|
||||
### I want access to the whole filesystem and still default users to their home directory
|
||||
|
||||
Setting the following in `jupyterhub_config.py` will configure access to
|
||||
the entire filesystem and set the default to the user's home directory.
|
||||
@@ -321,7 +281,7 @@ For instance:
|
||||
python3 -m pip install jupyterlab
|
||||
jupyter serverextension enable --py jupyterlab --sys-prefix
|
||||
|
||||
The important thing is that jupyterlab is installed and enabled in the
|
||||
The important thing is that JupyterLab is installed and enabled in the
|
||||
single-user notebook server environment. For system users, this means
|
||||
system-wide, as indicated above. For Docker containers, it means inside
|
||||
the single-user docker image, etc.
|
||||
@@ -334,14 +294,14 @@ notebook servers to default to JupyterLab:
|
||||
### How do I set up JupyterHub for a workshop (when users are not known ahead of time)?
|
||||
|
||||
1. Set up JupyterHub using OAuthenticator for GitHub authentication
|
||||
2. Configure admin list to have workshop leaders be listed with administrator privileges.
|
||||
2. Configure the admin list to have workshop leaders be listed with administrator privileges.
|
||||
|
||||
Users will need a GitHub account to log in and be authenticated by the Hub.
|
||||
|
||||
### How do I set up rotating daily logs?
|
||||
|
||||
You can do this with [logrotate](https://linux.die.net/man/8/logrotate),
|
||||
or pipe to `logger` to use syslog instead of directly to a file.
|
||||
or pipe to `logger` to use Syslog instead of directly to a file.
|
||||
|
||||
For example, with this logrotate config file:
|
||||
|
||||
@@ -362,6 +322,52 @@ Or use syslog:
|
||||
|
||||
jupyterhub | logger -t jupyterhub
|
||||
|
||||
### Toree integration with HDFS rack awareness script
|
||||
|
||||
The Apache Toree kernel will have an issue when running with JupyterHub if the standard HDFS
|
||||
rack awareness script is used. This will materialize in the logs as a repeated WARN:
|
||||
|
||||
```bash
|
||||
16/11/29 16:24:20 WARN ScriptBasedMapping: Exception running /etc/hadoop/conf/topology_script.py some.ip.address
|
||||
ExitCodeException exitCode=1: File "/etc/hadoop/conf/topology_script.py", line 63
|
||||
print rack
|
||||
^
|
||||
SyntaxError: Missing parentheses in call to 'print'
|
||||
|
||||
at `org.apache.hadoop.util.Shell.runCommand(Shell.java:576)`
|
||||
```
|
||||
|
||||
In order to resolve this issue, there are two potential options.
|
||||
|
||||
1. Update HDFS core-site.xml, so the parameter "net.topology.script.file.name" points to a custom
|
||||
script (e.g. /etc/hadoop/conf/custom_topology_script.py). Copy the original script and change the first line point
|
||||
to a python two installation (e.g. /usr/bin/python).
|
||||
2. In spark-env.sh add a Python 2 installation to your path (e.g. export PATH=/opt/anaconda2/bin:$PATH).
|
||||
|
||||
### Where do I find Docker images and Dockerfiles related to JupyterHub?
|
||||
|
||||
Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/).
|
||||
The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/)
|
||||
provides an example single-user notebook server for use with DockerSpawner.
|
||||
|
||||
Additional single-user notebook server images can be found at the [Jupyter
|
||||
organization on DockerHub](https://hub.docker.com/r/jupyter/) and information
|
||||
about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks).
|
||||
|
||||
### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner?
|
||||
|
||||
Use `docker logs <container>` where `<container>` is the container name defined within `docker-compose.yml`. For example, to view the logs of the JupyterHub container use:
|
||||
|
||||
docker logs hub
|
||||
|
||||
By default, the user's notebook server is named `jupyter-<username>` where `username` is the user's username within JupyterHub's db. So if you wanted to see the logs for user `foo` you would use:
|
||||
|
||||
docker logs jupyter-foo
|
||||
|
||||
You can also tail logs to view them in real-time using the `-f` option:
|
||||
|
||||
docker logs -f hub
|
||||
|
||||
## Troubleshooting commands
|
||||
|
||||
The following commands provide additional detail about installed packages,
|
||||
@@ -385,35 +391,3 @@ jupyter kernelspec list
|
||||
```bash
|
||||
jupyterhub --debug
|
||||
```
|
||||
|
||||
### Toree integration with HDFS rack awareness script
|
||||
|
||||
The Apache Toree kernel will an issue, when running with JupyterHub, if the standard HDFS
|
||||
rack awareness script is used. This will materialize in the logs as a repeated WARN:
|
||||
|
||||
```bash
|
||||
16/11/29 16:24:20 WARN ScriptBasedMapping: Exception running /etc/hadoop/conf/topology_script.py some.ip.address
|
||||
ExitCodeException exitCode=1: File "/etc/hadoop/conf/topology_script.py", line 63
|
||||
print rack
|
||||
^
|
||||
SyntaxError: Missing parentheses in call to 'print'
|
||||
|
||||
at `org.apache.hadoop.util.Shell.runCommand(Shell.java:576)`
|
||||
```
|
||||
|
||||
In order to resolve this issue, there are two potential options.
|
||||
|
||||
1. Update HDFS core-site.xml, so the parameter "net.topology.script.file.name" points to a custom
|
||||
script (e.g. /etc/hadoop/conf/custom_topology_script.py). Copy the original script and change the first line point
|
||||
to a python two installation (e.g. /usr/bin/python).
|
||||
2. In spark-env.sh add a Python 2 installation to your path (e.g. export PATH=/opt/anaconda2/bin:$PATH).
|
||||
|
||||
### Where do I find Docker images and Dockerfiles related to JupyterHub?
|
||||
|
||||
Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/).
|
||||
The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/)
|
||||
provides an example single user notebook server for use with DockerSpawner.
|
||||
|
||||
Additional single user notebook server images can be found at the [Jupyter
|
||||
organization on DockerHub](https://hub.docker.com/r/jupyter/) and information
|
||||
about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks).
|
||||
|
||||
@@ -6,12 +6,28 @@ that appear when JupyterHub renders pages.
|
||||
To run the service as a hub-managed service simply include in your JupyterHub
|
||||
configuration file something like:
|
||||
|
||||
:notebook:**Info**: You can run the announcement service example from the `examples`
|
||||
directory, using one of the several services provided by JupyterHub.
|
||||
|
||||
```python
|
||||
|
||||
import sys
|
||||
|
||||
from pathlib import Path
|
||||
# absolute path to announcement.py
|
||||
announcement_py = str(Path(__file__).parent.joinpath("announcement.py").resolve())
|
||||
|
||||
#ensure get_config() is added in
|
||||
c = get_config()
|
||||
|
||||
...
|
||||
..
|
||||
|
||||
c.JupyterHub.services = [
|
||||
{
|
||||
'name': 'announcement',
|
||||
'url': 'http://127.0.0.1:8888',
|
||||
'command': [sys.executable, "-m", "announcement", "--port", "8888"],
|
||||
'command': [sys.executable, announcement_py, "--port", "8888"],
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
import sys
|
||||
|
||||
c = get_config()
|
||||
|
||||
# To run the announcement service managed by the hub, add this.
|
||||
|
||||
port = 9999
|
||||
|
||||
Reference in New Issue
Block a user