mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-08 02:24:08 +00:00
Added docs to the folder
This commit is contained in:
alwasega
@@ -2,7 +2,16 @@
|
||||
|
||||
This section of the documentation provides step-by-step tutorials to help you achieve a specific goal. The tutorials should be a good place to start learning about JupyterHub and how it works.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
## Installation
|
||||
|
||||
These sections cover how to get up-and-running with JupyterHub. They cover
|
||||
some basics of the tools needed to deploy JupyterHub as well as how to get it
|
||||
running on your own infrastructure.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
installation/quickstart
|
||||
installation/installation-basics
|
||||
installation/quickstart-docker
|
||||
```
|
||||
|
||||
40
docs/source/tutorial/installation/installation-basics.md
Normal file
40
docs/source/tutorial/installation/installation-basics.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Installation Basics
|
||||
|
||||
## Platform support
|
||||
|
||||
JupyterHub is supported on Linux/Unix based systems. To use JupyterHub, you need
|
||||
a Unix server (typically Linux) running somewhere that is accessible to your
|
||||
team on the network. The JupyterHub server can be on an internal network at your
|
||||
organization, or it can run on the public internet (in which case, take care
|
||||
with the Hub's [security](./getting-started/security-basics)).
|
||||
|
||||
JupyterHub officially **does not** support Windows. You may be able to use
|
||||
JupyterHub on Windows if you use a Spawner and Authenticator that work on
|
||||
Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not
|
||||
be accepted, and the test suite will not run on Windows. Small patches that fix
|
||||
minor Windows compatibility issues (such as basic installation) **may** be accepted,
|
||||
however. For Windows-based systems, we would recommend running JupyterHub in a
|
||||
docker container or Linux VM.
|
||||
|
||||
[Additional Reference:](https://www.tornadoweb.org/en/stable/#installation)
|
||||
Tornado's documentation on Windows platform support
|
||||
|
||||
## Planning your installation
|
||||
|
||||
Prior to beginning installation, it's helpful to consider some of the following:
|
||||
|
||||
- deployment system (bare metal, Docker)
|
||||
- Authentication (PAM, OAuth, etc.)
|
||||
- Spawner of singleuser notebook servers (Docker, Batch, etc.)
|
||||
- Services (nbgrader, etc.)
|
||||
- JupyterHub database (default SQLite; traditional RDBMS such as PostgreSQL,)
|
||||
MySQL, or other databases supported by [SQLAlchemy](https://www.sqlalchemy.org))
|
||||
|
||||
## Folders and File Locations
|
||||
|
||||
It is recommended to put all of the files used by JupyterHub into standard
|
||||
UNIX filesystem locations.
|
||||
|
||||
- `/srv/jupyterhub` for all security and runtime files
|
||||
- `/etc/jupyterhub` for all configuration files
|
||||
- `/var/log` for log files
|
||||
65
docs/source/tutorial/installation/quickstart-docker.md
Normal file
65
docs/source/tutorial/installation/quickstart-docker.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 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.
|
||||
|
||||
:::{note}
|
||||
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, [JupyterLab](https://jupyterlab.readthedocs.io/) or Jupyter Notebook must be installed.
|
||||
:::
|
||||
|
||||
:::{important}
|
||||
We strongly recommend that you follow the [Zero to JupyterHub] tutorial to
|
||||
install JupyterHub.
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You should have [Docker] installed on a Linux/Unix based system.
|
||||
|
||||
## Run the Docker Image
|
||||
|
||||
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 exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console.
|
||||
|
||||
You can stop and resume the container by running `docker stop` and `docker start` respectively.
|
||||
|
||||
```
|
||||
# find the container id
|
||||
docker ps
|
||||
|
||||
# stop the running container
|
||||
docker stop <container-id>
|
||||
|
||||
# resume the paused container
|
||||
docker start <container-id>
|
||||
```
|
||||
|
||||
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
|
||||
configuration or using an ssl enabled proxy.
|
||||
|
||||
[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.
|
||||
|
||||
[docker]: https://www.docker.com/
|
||||
[zero to jupyterhub]: https://z2jh.jupyter.org/en/latest/
|
||||
95
docs/source/tutorial/installation/quickstart.md
Normal file
95
docs/source/tutorial/installation/quickstart.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Quickstart
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing JupyterHub, you will need:
|
||||
|
||||
- a Linux/Unix-based system
|
||||
- [Python](https://www.python.org/downloads/) 3.6 or greater. An understanding
|
||||
of using [`pip`](https://pip.pypa.io) or
|
||||
[`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) for
|
||||
installing Python packages is helpful.
|
||||
- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
|
||||
using your operating system's package manager.
|
||||
|
||||
- If you are using **`conda`**, the nodejs and npm dependencies will be installed for
|
||||
you by conda.
|
||||
|
||||
- If you are using **`pip`**, install a recent version of
|
||||
[nodejs/npm](https://docs.npmjs.com/getting-started/installing-node).
|
||||
For example, install it on Linux (Debian/Ubuntu) using:
|
||||
|
||||
```
|
||||
sudo apt-get install nodejs npm
|
||||
```
|
||||
|
||||
[nodesource][] is a great resource to get more recent versions of the nodejs runtime,
|
||||
if your system package manager only has an old version of Node.js (e.g. 10 or older).
|
||||
|
||||
- A [pluggable authentication module (PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module)
|
||||
to use the [default Authenticator](./getting-started/authenticators-users-basics.md).
|
||||
PAM is often available by default on most distributions, if this is not the case it can be installed by
|
||||
using the operating system's package manager.
|
||||
- TLS certificate and key for HTTPS communication
|
||||
- Domain name
|
||||
|
||||
[nodesource]: https://github.com/nodesource/distributions#table-of-contents
|
||||
|
||||
Before running the single-user notebook servers (which may be on the same
|
||||
system as the Hub or not), you will need:
|
||||
|
||||
- [JupyterLab][] version 3 or greater,
|
||||
or [Jupyter Notebook][]
|
||||
4 or greater.
|
||||
|
||||
[jupyterlab]: https://jupyterlab.readthedocs.io
|
||||
[jupyter notebook]: https://jupyter.readthedocs.io/en/latest/install.html
|
||||
|
||||
## Installation
|
||||
|
||||
JupyterHub can be installed with `pip` (and the proxy with `npm`) or `conda`:
|
||||
|
||||
**pip, npm:**
|
||||
|
||||
```bash
|
||||
python3 -m pip install jupyterhub
|
||||
npm install -g configurable-http-proxy
|
||||
python3 -m pip install jupyterlab notebook # needed if running the notebook servers in the same environment
|
||||
```
|
||||
|
||||
**conda** (one command installs jupyterhub and proxy):
|
||||
|
||||
```bash
|
||||
conda install -c conda-forge jupyterhub # installs jupyterhub and proxy
|
||||
conda install jupyterlab notebook # needed if running the notebook servers in the same environment
|
||||
```
|
||||
|
||||
Test your installation. If installed, these commands should return the packages'
|
||||
help contents:
|
||||
|
||||
```bash
|
||||
jupyterhub -h
|
||||
configurable-http-proxy -h
|
||||
```
|
||||
|
||||
## Start the Hub server
|
||||
|
||||
To start the Hub server, run the command:
|
||||
|
||||
```bash
|
||||
jupyterhub
|
||||
```
|
||||
|
||||
Visit `http://localhost:8000` in your browser, and sign in with your Unix
|
||||
credentials.
|
||||
|
||||
To **allow multiple users to sign in** to the Hub server, you must start
|
||||
`jupyterhub` as a _privileged user_, such as root:
|
||||
|
||||
```bash
|
||||
sudo jupyterhub
|
||||
```
|
||||
|
||||
The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
|
||||
describes how to run the server as a _less privileged user_. This requires
|
||||
additional configuration of the system.
|
||||
Reference in New Issue
Block a user