| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: jupyterhub |
| 3 |
Version: 5.2.1 |
| 4 |
Summary: JupyterHub: A multi-user server for Jupyter notebooks |
| 5 |
Author-email: Jupyter Development Team <[email protected]> |
| 6 |
License: BSD-3-Clause |
| 7 |
Project-URL: Homepage, https://hub.jupyter.org |
| 8 |
Project-URL: Documentation, https://jupyterhub.readthedocs.io |
| 9 |
Project-URL: Funding, https://jupyter.org/about |
| 10 |
Project-URL: Source, https://github.com/jupyterhub/jupyterhub |
| 11 |
Project-URL: Tracker, https://github.com/jupyterhub/jupyterhub/issues |
| 12 |
Keywords: Interactive,Interpreter,Shell,Web,Jupyter |
| 13 |
Classifier: Development Status :: 5 - Production/Stable |
| 14 |
Classifier: Intended Audience :: Developers |
| 15 |
Classifier: Intended Audience :: System Administrators |
| 16 |
Classifier: Intended Audience :: Science/Research |
| 17 |
Classifier: License :: OSI Approved :: BSD License |
| 18 |
Classifier: Programming Language :: Python |
| 19 |
Classifier: Programming Language :: Python :: 3 |
| 20 |
Classifier: Operating System :: POSIX |
| 21 |
Classifier: Framework :: Jupyter |
| 22 |
Requires-Python: >=3.8 |
| 23 |
Description-Content-Type: text/markdown |
| 24 |
License-File: COPYING.md |
| 25 |
Requires-Dist: alembic>=1.4 |
| 26 |
Requires-Dist: async_generator>=1.9; python_version < "3.10" |
| 27 |
Requires-Dist: certipy>=0.1.2 |
| 28 |
Requires-Dist: idna |
| 29 |
Requires-Dist: importlib_metadata>=3.6; python_version < "3.10" |
| 30 |
Requires-Dist: jinja2>=2.11.0 |
| 31 |
Requires-Dist: jupyter_events |
| 32 |
Requires-Dist: oauthlib>=3.0 |
| 33 |
Requires-Dist: packaging |
| 34 |
Requires-Dist: pamela>=1.1.0; sys_platform != "win32" |
| 35 |
Requires-Dist: prometheus_client>=0.5.0 |
| 36 |
Requires-Dist: psutil>=5.6.5; sys_platform == "win32" |
| 37 |
Requires-Dist: pydantic>=2 |
| 38 |
Requires-Dist: python-dateutil |
| 39 |
Requires-Dist: requests |
| 40 |
Requires-Dist: SQLAlchemy>=1.4.1 |
| 41 |
Requires-Dist: tornado>=5.1 |
| 42 |
Requires-Dist: traitlets>=4.3.2 |
| 43 |
Provides-Extra: test |
| 44 |
Requires-Dist: beautifulsoup4[html5lib]; extra == "test" |
| 45 |
Requires-Dist: coverage; extra == "test" |
| 46 |
Requires-Dist: cryptography; extra == "test" |
| 47 |
Requires-Dist: jsonschema; extra == "test" |
| 48 |
Requires-Dist: jupyterlab>=3; extra == "test" |
| 49 |
Requires-Dist: mock; extra == "test" |
| 50 |
Requires-Dist: nbclassic; extra == "test" |
| 51 |
Requires-Dist: pytest>=3.3; extra == "test" |
| 52 |
Requires-Dist: pytest-asyncio!=0.23.*,>=0.17; extra == "test" |
| 53 |
Requires-Dist: pytest-cov; extra == "test" |
| 54 |
Requires-Dist: pytest-rerunfailures; extra == "test" |
| 55 |
Requires-Dist: requests-mock; extra == "test" |
| 56 |
Requires-Dist: playwright; extra == "test" |
| 57 |
Requires-Dist: virtualenv; extra == "test" |
| 58 |
|
| 59 |
**[Technical Overview](#technical-overview)** | |
| 60 |
**[Installation](#installation)** | |
| 61 |
**[Configuration](#configuration)** | |
| 62 |
**[Docker](#docker)** | |
| 63 |
**[Contributing](#contributing)** | |
| 64 |
**[License](#license)** | |
| 65 |
**[Help and Resources](#help-and-resources)** |
| 66 |
|
| 67 |
--- |
| 68 |
|
| 69 |
# [JupyterHub](https://github.com/jupyterhub/jupyterhub) |
| 70 |
|
| 71 |
[](https://pypi.python.org/pypi/jupyterhub) |
| 72 |
[](https://anaconda.org/conda-forge/jupyterhub) |
| 73 |
[](https://jupyterhub.readthedocs.org/en/latest/) |
| 74 |
[](https://github.com/jupyterhub/jupyterhub/actions) |
| 75 |
[](https://codecov.io/gh/jupyterhub/jupyterhub) |
| 76 |
[](https://github.com/jupyterhub/jupyterhub/issues) |
| 77 |
[](https://discourse.jupyter.org/c/jupyterhub) |
| 78 |
[](https://gitter.im/jupyterhub/jupyterhub) |
| 79 |
|
| 80 |
With [JupyterHub](https://jupyterhub.readthedocs.io) you can create a |
| 81 |
**multi-user Hub** that spawns, manages, and proxies multiple instances of the |
| 82 |
single-user [Jupyter notebook](https://jupyter-notebook.readthedocs.io) |
| 83 |
server. |
| 84 |
|
| 85 |
[Project Jupyter](https://jupyter.org) created JupyterHub to support many |
| 86 |
users. The Hub can offer notebook servers to a class of students, a corporate |
| 87 |
data science workgroup, a scientific research project, or a high-performance |
| 88 |
computing group. |
| 89 |
|
| 90 |
## Technical overview |
| 91 |
|
| 92 |
Three main actors make up JupyterHub: |
| 93 |
|
| 94 |
- multi-user **Hub** (tornado process) |
| 95 |
- configurable http **proxy** (node-http-proxy) |
| 96 |
- multiple **single-user Jupyter notebook servers** (Python/Jupyter/tornado) |
| 97 |
|
| 98 |
Basic principles for operation are: |
| 99 |
|
| 100 |
- Hub launches a proxy. |
| 101 |
- The Proxy forwards all requests to Hub by default. |
| 102 |
- Hub handles login and spawns single-user servers on demand. |
| 103 |
- Hub configures proxy to forward URL prefixes to the single-user notebook |
| 104 |
servers. |
| 105 |
|
| 106 |
JupyterHub also provides a |
| 107 |
[REST API][] |
| 108 |
for administration of the Hub and its users. |
| 109 |
|
| 110 |
[rest api]: https://jupyterhub.readthedocs.io/en/latest/reference/rest-api.html |
| 111 |
|
| 112 |
## Installation |
| 113 |
|
| 114 |
### Check prerequisites |
| 115 |
|
| 116 |
- A Linux/Unix based system |
| 117 |
- [Python](https://www.python.org/downloads/) 3.8 or greater |
| 118 |
- [nodejs/npm](https://www.npmjs.com/) |
| 119 |
|
| 120 |
- If you are using **`conda`**, the nodejs and npm dependencies will be installed for |
| 121 |
you by conda. |
| 122 |
|
| 123 |
- If you are using **`pip`**, install a recent version (at least 12.0) of |
| 124 |
[nodejs/npm](https://docs.npmjs.com/getting-started/installing-node). |
| 125 |
|
| 126 |
- If using the default PAM Authenticator, a [pluggable authentication module (PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module). |
| 127 |
- TLS certificate and key for HTTPS communication |
| 128 |
- Domain name |
| 129 |
|
| 130 |
### Install packages |
| 131 |
|
| 132 |
#### Using `conda` |
| 133 |
|
| 134 |
To install JupyterHub along with its dependencies including nodejs/npm: |
| 135 |
|
| 136 |
```bash |
| 137 |
conda install -c conda-forge jupyterhub |
| 138 |
``` |
| 139 |
|
| 140 |
If you plan to run notebook servers locally, install JupyterLab or Jupyter notebook: |
| 141 |
|
| 142 |
```bash |
| 143 |
conda install jupyterlab |
| 144 |
conda install notebook |
| 145 |
``` |
| 146 |
|
| 147 |
#### Using `pip` |
| 148 |
|
| 149 |
JupyterHub can be installed with `pip`, and the proxy with `npm`: |
| 150 |
|
| 151 |
```bash |
| 152 |
npm install -g configurable-http-proxy |
| 153 |
python3 -m pip install jupyterhub |
| 154 |
``` |
| 155 |
|
| 156 |
If you plan to run notebook servers locally, you will need to install |
| 157 |
[JupyterLab or Jupyter notebook](https://jupyter.readthedocs.io/en/latest/install.html): |
| 158 |
|
| 159 |
python3 -m pip install --upgrade jupyterlab |
| 160 |
python3 -m pip install --upgrade notebook |
| 161 |
|
| 162 |
### Run the Hub server |
| 163 |
|
| 164 |
To start the Hub server, run the command: |
| 165 |
|
| 166 |
jupyterhub |
| 167 |
|
| 168 |
Visit `http://localhost:8000` in your browser, and sign in with your system username and password. |
| 169 |
|
| 170 |
_Note_: To allow multiple users to sign in to the server, you will need to |
| 171 |
run the `jupyterhub` command as a _privileged user_, such as root. |
| 172 |
The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges) |
| 173 |
describes how to run the server as a _less privileged user_, which requires |
| 174 |
more configuration of the system. |
| 175 |
|
| 176 |
## Configuration |
| 177 |
|
| 178 |
The [Getting Started](https://jupyterhub.readthedocs.io/en/latest/tutorial/index.html#getting-started) section of the |
| 179 |
documentation explains the common steps in setting up JupyterHub. |
| 180 |
|
| 181 |
The [**JupyterHub tutorial**](https://github.com/jupyterhub/jupyterhub-tutorial) |
| 182 |
provides an in-depth video and sample configurations of JupyterHub. |
| 183 |
|
| 184 |
### Create a configuration file |
| 185 |
|
| 186 |
To generate a default config file with settings and descriptions: |
| 187 |
|
| 188 |
jupyterhub --generate-config |
| 189 |
|
| 190 |
### Start the Hub |
| 191 |
|
| 192 |
To start the Hub on a specific url and port `10.0.1.2:443` with **https**: |
| 193 |
|
| 194 |
jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert |
| 195 |
|
| 196 |
### Authenticators |
| 197 |
|
| 198 |
| Authenticator | Description | |
| 199 |
| ---------------------------------------------------------------------------- | ------------------------------------------------- | |
| 200 |
| PAMAuthenticator | Default, built-in authenticator | |
| 201 |
| [OAuthenticator](https://github.com/jupyterhub/oauthenticator) | OAuth + JupyterHub Authenticator = OAuthenticator | |
| 202 |
| [ldapauthenticator](https://github.com/jupyterhub/ldapauthenticator) | Simple LDAP Authenticator Plugin for JupyterHub | |
| 203 |
| [kerberosauthenticator](https://github.com/jupyterhub/kerberosauthenticator) | Kerberos Authenticator Plugin for JupyterHub | |
| 204 |
|
| 205 |
### Spawners |
| 206 |
|
| 207 |
| Spawner | Description | |
| 208 |
| -------------------------------------------------------------- | -------------------------------------------------------------------------- | |
| 209 |
| LocalProcessSpawner | Default, built-in spawner starts single-user servers as local processes | |
| 210 |
| [dockerspawner](https://github.com/jupyterhub/dockerspawner) | Spawn single-user servers in Docker containers | |
| 211 |
| [kubespawner](https://github.com/jupyterhub/kubespawner) | Kubernetes spawner for JupyterHub | |
| 212 |
| [sudospawner](https://github.com/jupyterhub/sudospawner) | Spawn single-user servers without being root | |
| 213 |
| [systemdspawner](https://github.com/jupyterhub/systemdspawner) | Spawn single-user notebook servers using systemd | |
| 214 |
| [batchspawner](https://github.com/jupyterhub/batchspawner) | Designed for clusters using batch scheduling software | |
| 215 |
| [yarnspawner](https://github.com/jupyterhub/yarnspawner) | Spawn single-user notebook servers distributed on a Hadoop cluster | |
| 216 |
| [wrapspawner](https://github.com/jupyterhub/wrapspawner) | WrapSpawner and ProfilesSpawner enabling runtime configuration of spawners | |
| 217 |
|
| 218 |
## Docker |
| 219 |
|
| 220 |
A starter [**docker image for JupyterHub**](https://quay.io/repository/jupyterhub/jupyterhub) |
| 221 |
gives a baseline deployment of JupyterHub using Docker. |
| 222 |
|
| 223 |
**Important:** This `quay.io/jupyterhub/jupyterhub` image contains only the Hub itself, |
| 224 |
with no configuration. In general, one needs to make a derivative image, with |
| 225 |
at least a `jupyterhub_config.py` setting up an Authenticator and/or a Spawner. |
| 226 |
To run the single-user servers, which may be on the same system as the Hub or |
| 227 |
not, Jupyter Notebook version 4 or greater must be installed. |
| 228 |
|
| 229 |
The JupyterHub docker image can be started with the following command: |
| 230 |
|
| 231 |
docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub |
| 232 |
|
| 233 |
This command will create a container named `jupyterhub` that you can |
| 234 |
**stop and resume** with `docker stop/start`. |
| 235 |
|
| 236 |
The Hub service will be listening on all interfaces at port 8000, which makes |
| 237 |
this a good choice for **testing JupyterHub on your desktop or laptop**. |
| 238 |
|
| 239 |
If you want to run docker on a computer that has a public IP then you should |
| 240 |
(as in MUST) **secure it with ssl** by adding ssl options to your docker |
| 241 |
configuration or by using an ssl enabled proxy. |
| 242 |
|
| 243 |
[Mounting volumes](https://docs.docker.com/engine/admin/volumes/volumes/) will |
| 244 |
allow you to **store data outside the docker image (host system) so it will be persistent**, even when you start |
| 245 |
a new image. |
| 246 |
|
| 247 |
The command `docker exec -it jupyterhub bash` will spawn a root shell in your docker |
| 248 |
container. You can **use the root shell to create system users in the container**. |
| 249 |
These accounts will be used for authentication in JupyterHub's default configuration. |
| 250 |
|
| 251 |
## Contributing |
| 252 |
|
| 253 |
If you would like to contribute to the project, please read our |
| 254 |
[contributor documentation](https://jupyter.readthedocs.io/en/latest/contributing/content-contributor.html) |
| 255 |
and the [`CONTRIBUTING.md`](CONTRIBUTING.md). The `CONTRIBUTING.md` file |
| 256 |
explains how to set up a development installation, how to run the test suite, |
| 257 |
and how to contribute to documentation. |
| 258 |
|
| 259 |
For a high-level view of the vision and next directions of the project, see the |
| 260 |
[JupyterHub community roadmap](docs/source/contributing/roadmap.md). |
| 261 |
|
| 262 |
### A note about platform support |
| 263 |
|
| 264 |
JupyterHub is supported on Linux/Unix based systems. |
| 265 |
|
| 266 |
JupyterHub officially **does not** support Windows. You may be able to use |
| 267 |
JupyterHub on Windows if you use a Spawner and Authenticator that work on |
| 268 |
Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not |
| 269 |
be accepted, and the test suite will not run on Windows. Small patches that fix |
| 270 |
minor Windows compatibility issues (such as basic installation) **may** be accepted, |
| 271 |
however. For Windows-based systems, we would recommend running JupyterHub in a |
| 272 |
docker container or Linux VM. |
| 273 |
|
| 274 |
[Additional Reference:](http://www.tornadoweb.org/en/stable/#installation) Tornado's documentation on Windows platform support |
| 275 |
|
| 276 |
## License |
| 277 |
|
| 278 |
We use a shared copyright model that enables all contributors to maintain the |
| 279 |
copyright on their contributions. |
| 280 |
|
| 281 |
All code is licensed under the terms of the [revised BSD license](./COPYING.md). |
| 282 |
|
| 283 |
## Help and resources |
| 284 |
|
| 285 |
We encourage you to ask questions and share ideas on the [Jupyter community forum](https://discourse.jupyter.org/). |
| 286 |
You can also talk with us on our JupyterHub [Gitter](https://gitter.im/jupyterhub/jupyterhub) channel. |
| 287 |
|
| 288 |
- [Reporting Issues](https://github.com/jupyterhub/jupyterhub/issues) |
| 289 |
- [JupyterHub tutorial](https://github.com/jupyterhub/jupyterhub-tutorial) |
| 290 |
- [Documentation for JupyterHub](https://jupyterhub.readthedocs.io/en/latest/) |
| 291 |
- [Documentation for JupyterHub's REST API][rest api] |
| 292 |
- [Documentation for Project Jupyter](http://jupyter.readthedocs.io/en/latest/index.html) |
| 293 |
- [Project Jupyter website](https://jupyter.org) |
| 294 |
- [Project Jupyter community](https://jupyter.org/community) |
| 295 |
|
| 296 |
JupyterHub follows the Jupyter [Community Guides](https://jupyter.readthedocs.io/en/latest/community/content-community.html). |
| 297 |
|
| 298 |
--- |
| 299 |
|
| 300 |
**[Technical Overview](#technical-overview)** | |
| 301 |
**[Installation](#installation)** | |
| 302 |
**[Configuration](#configuration)** | |
| 303 |
**[Docker](#docker)** | |
| 304 |
**[Contributing](#contributing)** | |
| 305 |
**[License](#license)** | |
| 306 |
**[Help and Resources](#help-and-resources)** |