hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 23:42:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

[pre-commit.ci] auto fixes from pre-commit.com hooks

Browse Source 
for more information, see https://pre-commit.ci
This commit is contained in:
pre-commit-ci[bot]
2023-01-09 21:04:01 +00:00
committed by YuviPanda
parent 6679c389b5
commit 3caea2a463
1 changed files with 100 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/source/explanation/concepts.md
View File

@@ -24,8 +24,6 @@ This guide is long, but after reading it you will be know of all major
components in the Jupyter ecosystem and everything else you read components in the Jupyter ecosystem and everything else you read
should make sense. should make sense.
## What is Jupyter? ## What is Jupyter?
Before we get too far, let's remember what our end goal is. A Before we get too far, let's remember what our end goal is. A
@@ -34,25 +32,24 @@ which is getting commands from a web browser and displaying the output
via that browser. What the process actually sees is roughly like via that browser. What the process actually sees is roughly like
getting commands on standard input(&) and writing to standard getting commands on standard input(&) and writing to standard
output(&). There is nothing intrinsically special about this process output(&). There is nothing intrinsically special about this process
- it can do anything a normal Python process can do, and nothing more. - it can do anything a normal Python process can do, and nothing more.
The **Jupyter kernel** handles capturing output and converting things The **Jupyter kernel** handles capturing output and converting things
such as graphics to a form usable by the browser. such as graphics to a form usable by the browser.
Everything we explain below is building up to this, going through many Everything we explain below is building up to this, going through many
different layers which give you many ways of customizing how this different layers which give you many ways of customizing how this
process runs. process runs.
## JupyterHub ## JupyterHub
**JupyterHub** is the central piece that provides multi-user **JupyterHub** is the central piece that provides multi-user
login capabilities. Despite this, the end user only briefly interacts with login capabilities. Despite this, the end user only briefly interacts with
JupyterHub and most of the actual Jupyter session does not relate to JupyterHub and most of the actual Jupyter session does not relate to
the hub at all: the hub mainly handles authentication and creating (JupyterHub calls it "spawning") the the hub at all: the hub mainly handles authentication and creating (JupyterHub calls it "spawning") the
single-user server. In short, anything which is related to *starting* single-user server. In short, anything which is related to _starting_
the user's workspace/environment is about JupyterHub, anything about the user's workspace/environment is about JupyterHub, anything about
*running* usually isn't. _running_ usually isn't.
If you have problems connecting the authentication, spawning, and the If you have problems connecting the authentication, spawning, and the
proxy (explained below), the issue is usually with JupyterHub. To proxy (explained below), the issue is usually with JupyterHub. To
@@ -84,7 +81,6 @@ The following authenticators are included with JupyterHub:
of a ssh server, but providing a web-browser based way to access the of a ssh server, but providing a web-browser based way to access the
machine. machine.
There are [plenty of others to choose from](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators). There are [plenty of others to choose from](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
You can connect to almost any other existing service to manage your You can connect to almost any other existing service to manage your
users. You either use all users from this other service (e.g. your users. You either use all users from this other service (e.g. your
@@ -189,7 +185,6 @@ what services it interacts with (for example, the Docker spawner
somehow puts logs in the Docker system services, Kubernetes through somehow puts logs in the Docker system services, Kubernetes through
the `kubectl` API). the `kubectl` API).
### Proxy ### Proxy
The JupyterHub **proxy** relays connections between the users The JupyterHub **proxy** relays connections between the users
@@ -208,7 +203,7 @@ The default proxy is **ConfigurableHttpProxy** which is simple but
effective. A more advanced option is the [**Traefik Proxy**](https://blog.jupyter.org/introducing-traefikproxy-a-new-jupyterhub-proxy-based-on-traefik-4839e972faf6), effective. A more advanced option is the [**Traefik Proxy**](https://blog.jupyter.org/introducing-traefikproxy-a-new-jupyterhub-proxy-based-on-traefik-4839e972faf6),
which gives you redundancy and high-availability. which gives you redundancy and high-availability.
When users "connect to JupyterHub", they *always* first connect to the When users "connect to JupyterHub", they _always_ first connect to the
proxy and the proxy relays the connection to the hub. Thus, the proxy proxy and the proxy relays the connection to the hub. Thus, the proxy
is responsible for SSL and accepting connections from the rest of the is responsible for SSL and accepting connections from the rest of the
internet. The user uses the hub to authenticate and start the server, internet. The user uses the hub to authenticate and start the server,
@@ -254,7 +249,7 @@ coupled and running as a service provides convenience of
authentication - it could be just as well run some other way, with a authentication - it could be just as well run some other way, with a
manually provided API token. manually provided API token.
Another example is *sharing files using hubshare*. Hubshare would work as an external service Another example is _sharing files using hubshare_. Hubshare would work as an external service
which user notebooks talk to and use Hub authentication, but otherwise which user notebooks talk to and use Hub authentication, but otherwise
it isn't directly a matter of the hub. You could equally well share it isn't directly a matter of the hub. You could equally well share
files by other extensions to the single-user notebook servers or files by other extensions to the single-user notebook servers or
@@ -269,8 +264,6 @@ services from the hub.
When a service is started from JupyterHub automatically, its logs are When a service is started from JupyterHub automatically, its logs are
included in the JupyterHub logs. included in the JupyterHub logs.
## Single-user notebook server ## Single-user notebook server
The **single-user notebook server** is the same thing you get by The **single-user notebook server** is the same thing you get by
@@ -325,7 +318,6 @@ to Docker and Kubernetes respectively, and batchspawner output goes to
the normal output places of batch jobs and is an explicit the normal output places of batch jobs and is an explicit
configuration option of the spawner. configuration option of the spawner.
**(Jupyter) Notebook** is the classic interface, where each notebook **(Jupyter) Notebook** is the classic interface, where each notebook
opens in a separate tab. It is traditionally started by `jupyter opens in a separate tab. It is traditionally started by `jupyter
notebook`. Does anything need to be said here? notebook`. Does anything need to be said here?
@@ -344,8 +336,6 @@ Extensions need to be re-written for JupyterLab (if moving from
classic notebooks). But, the server-side of the extensions can be classic notebooks). But, the server-side of the extensions can be
shared by both. shared by both.
## Kernel ## Kernel
The commands you run in the notebook session are not executed in the same process as The commands you run in the notebook session are not executed in the same process as
@@ -357,7 +347,7 @@ As a basic approximation, a **Jupyter kernel** is a process which
accepts commands (cells that are run) and returns the output to accepts commands (cells that are run) and returns the output to
Jupyter to display. One example is the **IPython Jupyter kernel**, Jupyter to display. One example is the **IPython Jupyter kernel**,
which runs Python. There is nothing special about it, it can be which runs Python. There is nothing special about it, it can be
considered a *normal Python process. The kernel process can be considered a \*normal Python process. The kernel process can be
approximated in UNIX terms as a process that takes commands on stdin approximated in UNIX terms as a process that takes commands on stdin
and returns stuff on stdout(&). Obviously, it's more because it has and returns stuff on stdout(&). Obviously, it's more because it has
to be able to disentangle all the possible outputs, such as figures, to be able to disentangle all the possible outputs, such as figures,
@@ -368,7 +358,7 @@ computer. Kernels are separate processes from the main single-user
notebook server (and thus obviously, different from the JupyterHub notebook server (and thus obviously, different from the JupyterHub
process and everything else). By default (and unless you do something process and everything else). By default (and unless you do something
special), kernels share the same environment as the notebook server special), kernels share the same environment as the notebook server
(data, resource limits, permissions, user id, etc.). But they *can* (data, resource limits, permissions, user id, etc.). But they _can_
run in a separate Python environment from the single-user server run in a separate Python environment from the single-user server
(search `--prefix` in the [ipykernel installation (search `--prefix` in the [ipykernel installation
instructions](https://ipython.readthedocs.io/en/stable/install/kernel_install.html)) instructions](https://ipython.readthedocs.io/en/stable/install/kernel_install.html))
@@ -383,7 +373,7 @@ A kernel doesn't just execute it's language - cell magics such as `%`,
IPython kernel commands and don't necessarily work in any other IPython kernel commands and don't necessarily work in any other
kernel unless they specifically support them. kernel unless they specifically support them.
Kernels are yet *another* layer of configurability. Kernels are yet _another_ layer of configurability.
Each kernel can run a different programming language, with different Each kernel can run a different programming language, with different
software, and so on. By default, they would run in the same software, and so on. By default, they would run in the same
environment as the single-user notebook server, and the most common environment as the single-user notebook server, and the most common
@@ -414,8 +404,6 @@ In these cases, you need to find the kernel logs and investigate.
The debug logs for the kernel are normally mixed in with the The debug logs for the kernel are normally mixed in with the
single-user notebook server logs. single-user notebook server logs.
## JupyterHub distributions ## JupyterHub distributions
There are several "distributions" which automatically install all of There are several "distributions" which automatically install all of
@@ -423,16 +411,16 @@ the things above and configure them for a certain purpose. They are
good ways to get started, but if you have custom needs, eventually it good ways to get started, but if you have custom needs, eventually it
may become hard to adapt them to your requirements. may become hard to adapt them to your requirements.
* [**Zero to JupyterHub with - [**Zero to JupyterHub with
Kubernetes**](https://zero-to-jupyterhub.readthedocs.io/) installs Kubernetes**](https://zero-to-jupyterhub.readthedocs.io/) installs
an entire scaleable system using Kubernetes. Uses KubeSpawner, an entire scaleable system using Kubernetes. Uses KubeSpawner,
....Authenticator, .... ....Authenticator, ....
* [**The Littlest JupyterHub**](https://tljh.jupyter.org/) installs JupyterHub on a single system - [**The Littlest JupyterHub**](https://tljh.jupyter.org/) installs JupyterHub on a single system
using SystemdSpawner and NativeAuthenticator (which manages users using SystemdSpawner and NativeAuthenticator (which manages users
itself). itself).
* [**JupyterHub the hard way**](https://github.com/jupyterhub/jupyterhub-the-hard-way/blob/master/docs/installation-guide-hard.md) - [**JupyterHub the hard way**](https://github.com/jupyterhub/jupyterhub-the-hard-way/blob/master/docs/installation-guide-hard.md)
takes you through everything yourself. It is a natural companion to takes you through everything yourself. It is a natural companion to
this guide, since you get to experience every little bit. this guide, since you get to experience every little bit.