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

run pre-commit (prettier)

Browse Source
This commit is contained in:
Min RK
2021-02-12 15:25:58 +01:00
parent 3c7203741f
commit 9331dd13da
58 changed files with 854 additions and 944 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.circleci/config.yml
View File

@@ -24,7 +24,6 @@ jobs:
command: | command: |
docker run --rm -it -v $PWD/dockerfiles:/io jupyterhub/jupyterhub python3 /io/test.py docker run --rm -it -v $PWD/dockerfiles:/io jupyterhub/jupyterhub python3 /io/test.py
# Tell CircleCI to use this workflow when it builds the site # Tell CircleCI to use this workflow when it builds the site
workflows: workflows:
version: 2 version: 2

2
.github/workflows/test.yml vendored
View File

@@ -51,7 +51,6 @@ jobs:
echo "or after-the-fact on already committed files with" echo "or after-the-fact on already committed files with"
echo " pre-commit run --all-files" echo " pre-commit run --all-files"
# Run "pytest jupyterhub/tests" in various configurations # Run "pytest jupyterhub/tests" in various configurations
pytest: pytest:
runs-on: ubuntu-20.04 runs-on: ubuntu-20.04
@@ -131,7 +130,6 @@ jobs:
echo "JUPYTERHUB_SINGLEUSER_APP=jupyterhub.tests.mockserverapp.MockServerApp" >> $GITHUB_ENV echo "JUPYTERHUB_SINGLEUSER_APP=jupyterhub.tests.mockserverapp.MockServerApp" >> $GITHUB_ENV
fi fi
- uses: actions/checkout@v2 - uses: actions/checkout@v2
# NOTE: actions/setup-node@v1 make use of a cache within the GitHub base # NOTE: actions/setup-node@v1 make use of a cache within the GitHub base
# environment and setup in a fraction of a second. # environment and setup in a fraction of a second.
- name: Install Node v14 - name: Install Node v14

40
.pre-commit-config.yaml
View File

@@ -1,21 +1,21 @@
repos: repos:
- repo: https://github.com/asottile/reorder_python_imports - repo: https://github.com/asottile/reorder_python_imports
rev: v1.9.0 rev: v1.9.0
hooks: hooks:
- id: reorder-python-imports - id: reorder-python-imports
- repo: https://github.com/psf/black - repo: https://github.com/psf/black
rev: 20.8b1 rev: 20.8b1
hooks: hooks:
- id: black - id: black
- repo: https://github.com/pre-commit/mirrors-prettier - repo: https://github.com/pre-commit/mirrors-prettier
rev: v2.2.1 rev: v2.2.1
hooks: hooks:
- id: prettier - id: prettier
- repo: https://github.com/pre-commit/pre-commit-hooks - repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.4.0 rev: v2.4.0
hooks: hooks:
- id: end-of-file-fixer - id: end-of-file-fixer
- id: check-case-conflict - id: check-case-conflict
- id: check-executables-have-shebangs - id: check-executables-have-shebangs
- id: requirements-txt-fixer - id: requirements-txt-fixer
- id: flake8 - id: flake8

16
CHECKLIST-Release.md
View File

@@ -2,24 +2,24 @@
- [ ] Upgrade Docs prior to Release - [ ] Upgrade Docs prior to Release
- [ ] Change log - [ ] Change log
- [ ] New features documented - [ ] New features documented
- [ ] Update the contributor list - thank you page - [ ] Update the contributor list - thank you page
- [ ] Upgrade and test Reference Deployments - [ ] Upgrade and test Reference Deployments
- [ ] Release software - [ ] Release software
- [ ] Make sure 0 issues in milestone - [ ] Make sure 0 issues in milestone
- [ ] Follow release process steps - [ ] Follow release process steps
- [ ] Send builds to PyPI (Warehouse) and Conda Forge - [ ] Send builds to PyPI (Warehouse) and Conda Forge
- [ ] Blog post and/or release note - [ ] Blog post and/or release note
- [ ] Notify users of release - [ ] Notify users of release
- [ ] Email Jupyter and Jupyter In Education mailing lists - [ ] Email Jupyter and Jupyter In Education mailing lists
- [ ] Tweet (optional) - [ ] Tweet (optional)
- [ ] Increment the version number for the next release - [ ] Increment the version number for the next release

46
CONTRIBUTING.md
View File

@@ -18,39 +18,41 @@ JupyterHub requires Python >= 3.5 and nodejs.
As a Python project, a development install of JupyterHub follows standard practices for the basics (steps 1-2). As a Python project, a development install of JupyterHub follows standard practices for the basics (steps 1-2).
1. clone the repo 1. clone the repo
```bash ```bash
git clone https://github.com/jupyterhub/jupyterhub git clone https://github.com/jupyterhub/jupyterhub
``` ```
2. do a development install with pip 2. do a development install with pip
```bash ```bash
cd jupyterhub cd jupyterhub
python3 -m pip install --editable . python3 -m pip install --editable .
``` ```
3. install the development requirements, 3. install the development requirements,
which include things like testing tools which include things like testing tools
```bash ```bash
python3 -m pip install -r dev-requirements.txt python3 -m pip install -r dev-requirements.txt
``` ```
4. install configurable-http-proxy with npm: 4. install configurable-http-proxy with npm:
```bash ```bash
npm install -g configurable-http-proxy npm install -g configurable-http-proxy
``` ```
5. set up pre-commit hooks for automatic code formatting, etc. 5. set up pre-commit hooks for automatic code formatting, etc.
```bash ```bash
pre-commit install pre-commit install
``` ```
You can also invoke the pre-commit hook manually at any time with You can also invoke the pre-commit hook manually at any time with
```bash ```bash
pre-commit run pre-commit run
``` ```
## Contributing ## Contributing
@@ -71,7 +73,7 @@ into your text editor to format code automatically.
If you have already committed files before setting up the pre-commit If you have already committed files before setting up the pre-commit
hook with `pre-commit install`, you can fix everything up using hook with `pre-commit install`, you can fix everything up using
`pre-commit run --all-files`. You need to make the fixing commit `pre-commit run --all-files`. You need to make the fixing commit
yourself after that. yourself after that.
## Testing ## Testing

6
COPYING.md
View File

@@ -24,7 +24,7 @@ software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
@@ -46,8 +46,8 @@ Jupyter uses a shared copyright model. Each contributor maintains copyright
over their contributions to Jupyter. But, it is important to note that these over their contributions to Jupyter. But, it is important to note that these
contributions are typically only changes to the repositories. Thus, the Jupyter contributions are typically only changes to the repositories. Thus, the Jupyter
source code, in its entirety is not the copyright of any single person or source code, in its entirety is not the copyright of any single person or
institution. Instead, it is the collective copyright of the entire Jupyter institution. Instead, it is the collective copyright of the entire Jupyter
Development Team. If individual contributors want to maintain a record of what Development Team. If individual contributors want to maintain a record of what
changes/contributions they have specific copyright on, they should indicate changes/contributions they have specific copyright on, they should indicate
their copyright in the commit message of the change, when they commit the their copyright in the commit message of the change, when they commit the
change to one of the Jupyter repositories. change to one of the Jupyter repositories.

17
README.md
View File

@@ -6,10 +6,8 @@
**[License](#license)** | **[License](#license)** |
**[Help and Resources](#help-and-resources)** **[Help and Resources](#help-and-resources)**
# [JupyterHub](https://github.com/jupyterhub/jupyterhub) # [JupyterHub](https://github.com/jupyterhub/jupyterhub)
[![Latest PyPI version](https://img.shields.io/pypi/v/jupyterhub?logo=pypi)](https://pypi.python.org/pypi/jupyterhub) [![Latest PyPI version](https://img.shields.io/pypi/v/jupyterhub?logo=pypi)](https://pypi.python.org/pypi/jupyterhub)
[![Latest conda-forge version](https://img.shields.io/conda/vn/conda-forge/jupyterhub?logo=conda-forge)](https://www.npmjs.com/package/jupyterhub) [![Latest conda-forge version](https://img.shields.io/conda/vn/conda-forge/jupyterhub?logo=conda-forge)](https://www.npmjs.com/package/jupyterhub)
[![Documentation build status](https://img.shields.io/readthedocs/jupyterhub?logo=read-the-docs)](https://jupyterhub.readthedocs.org/en/latest/) [![Documentation build status](https://img.shields.io/readthedocs/jupyterhub?logo=read-the-docs)](https://jupyterhub.readthedocs.org/en/latest/)
@@ -53,17 +51,16 @@ for administration of the Hub and its users.
## Installation ## Installation
### Check prerequisites ### Check prerequisites
- A Linux/Unix based system - A Linux/Unix based system
- [Python](https://www.python.org/downloads/) 3.5 or greater - [Python](https://www.python.org/downloads/) 3.5 or greater
- [nodejs/npm](https://www.npmjs.com/) - [nodejs/npm](https://www.npmjs.com/)
* If you are using **`conda`**, the nodejs and npm dependencies will be installed for - If you are using **`conda`**, the nodejs and npm dependencies will be installed for
you by conda. you by conda.
* If you are using **`pip`**, install a recent version of - If you are using **`pip`**, install a recent version of
[nodejs/npm](https://docs.npmjs.com/getting-started/installing-node). [nodejs/npm](https://docs.npmjs.com/getting-started/installing-node).
For example, install it on Linux (Debian/Ubuntu) using: For example, install it on Linux (Debian/Ubuntu) using:
@@ -102,7 +99,7 @@ JupyterHub can be installed with `pip`, and the proxy with `npm`:
```bash ```bash
npm install -g configurable-http-proxy npm install -g configurable-http-proxy
python3 -m pip install jupyterhub python3 -m pip install jupyterhub
``` ```
If you plan to run notebook servers locally, you will need to install the If you plan to run notebook servers locally, you will need to install the
@@ -120,10 +117,10 @@ To start the Hub server, run the command:
Visit `https://localhost:8000` in your browser, and sign in with your unix Visit `https://localhost:8000` in your browser, and sign in with your unix
PAM credentials. PAM credentials.
*Note*: To allow multiple users to sign into the server, you will need to _Note_: To allow multiple users to sign into the server, you will need to
run the `jupyterhub` command as a *privileged user*, such as root. run the `jupyterhub` command as a _privileged user_, such as root.
The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges) 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*, which requires describes how to run the server as a _less privileged user_, which requires
more configuration of the system. more configuration of the system.
## Configuration ## Configuration
@@ -142,7 +139,7 @@ To generate a default config file with settings and descriptions:
### Start the Hub ### Start the Hub
To start the Hub on a specific url and port ``10.0.1.2:443`` with **https**: To start the Hub on a specific url and port `10.0.1.2:443` with **https**:
jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert

3
demo-image/README.md
View File

@@ -15,9 +15,10 @@ This should only be used for demo or testing purposes!
It shouldn't be used as a base image to build on. It shouldn't be used as a base image to build on.
### Try it ### Try it
1. `cd` to the root of your jupyterhub repo. 1. `cd` to the root of your jupyterhub repo.
2. Build the demo image with `docker build -t jupyterhub-demo demo-image`. 2. Build the demo image with `docker build -t jupyterhub-demo demo-image`.
3. Run the demo image with `docker run -d -p 8000:8000 jupyterhub-demo`. 3. Run the demo image with `docker run -d -p 8000:8000 jupyterhub-demo`.

22
dockerfiles/README.md
View File

@@ -1,20 +1,20 @@
## What is Dockerfile.alpine ## What is Dockerfile.alpine
Dockerfile.alpine contains base image for jupyterhub. It does not work independently, but only as part of a full jupyterhub cluster
Dockerfile.alpine contains base image for jupyterhub. It does not work independently, but only as part of a full jupyterhub cluster
## How to use it? ## How to use it?
1. A running configurable-http-proxy, whose API is accessible. 1. A running configurable-http-proxy, whose API is accessible.
2. A jupyterhub_config file. 2. A jupyterhub_config file.
3. Authentication and other libraries required by the specific jupyterhub_config file. 3. Authentication and other libraries required by the specific jupyterhub_config file.
## Steps to test it outside a cluster ## Steps to test it outside a cluster
* start configurable-http-proxy in another container - start configurable-http-proxy in another container
* specify CONFIGPROXY_AUTH_TOKEN env in both containers - specify CONFIGPROXY_AUTH_TOKEN env in both containers
* put both containers on the same network (e.g. docker network create jupyterhub; docker run ... --net jupyterhub) - put both containers on the same network (e.g. docker network create jupyterhub; docker run ... --net jupyterhub)
* tell jupyterhub where CHP is (e.g. c.ConfigurableHTTPProxy.api_url = 'http://chp:8001') - tell jupyterhub where CHP is (e.g. c.ConfigurableHTTPProxy.api_url = 'http://chp:8001')
* tell jupyterhub not to start the proxy itself (c.ConfigurableHTTPProxy.should_start = False) - tell jupyterhub not to start the proxy itself (c.ConfigurableHTTPProxy.should_start = False)
* Use dummy authenticator for ease of testing. Update following in jupyterhub_config file - Use dummy authenticator for ease of testing. Update following in jupyterhub_config file
- c.JupyterHub.authenticator_class = 'dummyauthenticator.DummyAuthenticator' - c.JupyterHub.authenticator_class = 'dummyauthenticator.DummyAuthenticator'
- c.DummyAuthenticator.password = "your strong password" - c.DummyAuthenticator.password = "your strong password"

159
docs/rest-api.yml
View File

@@ -1,13 +1,12 @@
# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default # see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default
swagger: '2.0' swagger: "2.0"
info: info:
title: JupyterHub title: JupyterHub
description: The REST API for JupyterHub description: The REST API for JupyterHub
version: 1.2.0dev version: 1.2.0dev
license: license:
name: BSD-3-Clause name: BSD-3-Clause
schemes: schemes: [http, https]
[http, https]
securityDefinitions: securityDefinitions:
token: token:
type: apiKey type: apiKey
@@ -28,7 +27,7 @@ paths:
This endpoint is not authenticated for the purpose of clients and user This endpoint is not authenticated for the purpose of clients and user
to identify the JupyterHub version before setting up authentication. to identify the JupyterHub version before setting up authentication.
responses: responses:
'200': "200":
description: The JupyterHub version description: The JupyterHub version
schema: schema:
type: object type: object
@@ -44,7 +43,7 @@ paths:
JupyterHub's version and executable path, JupyterHub's version and executable path,
and which Authenticator and Spawner are active. and which Authenticator and Spawner are active.
responses: responses:
'200': "200":
description: Detailed JupyterHub info description: Detailed JupyterHub info
schema: schema:
type: object type: object
@@ -95,12 +94,12 @@ paths:
Added in JupyterHub 1.3 Added in JupyterHub 1.3
responses: responses:
'200': "200":
description: The Hub's user list description: The Hub's user list
schema: schema:
type: array type: array
items: items:
$ref: '#/definitions/User' $ref: "#/definitions/User"
post: post:
summary: Create multiple users summary: Create multiple users
parameters: parameters:
@@ -119,13 +118,13 @@ paths:
description: whether the created users should be admins description: whether the created users should be admins
type: boolean type: boolean
responses: responses:
'201': "201":
description: The users have been created description: The users have been created
schema: schema:
type: array type: array
description: The created users description: The created users
items: items:
$ref: '#/definitions/User' $ref: "#/definitions/User"
/users/{name}: /users/{name}:
get: get:
summary: Get a user by name summary: Get a user by name
@@ -136,10 +135,10 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: The User model description: The User model
schema: schema:
$ref: '#/definitions/User' $ref: "#/definitions/User"
post: post:
summary: Create a single user summary: Create a single user
parameters: parameters:
@@ -149,10 +148,10 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'201': "201":
description: The user has been created description: The user has been created
schema: schema:
$ref: '#/definitions/User' $ref: "#/definitions/User"
patch: patch:
summary: Modify a user summary: Modify a user
description: Change a user's name or admin status description: Change a user's name or admin status
@@ -176,10 +175,10 @@ paths:
type: boolean type: boolean
description: update admin (optional, if another key is updated i.e. name) description: update admin (optional, if another key is updated i.e. name)
responses: responses:
'200': "200":
description: The updated user info description: The updated user info
schema: schema:
$ref: '#/definitions/User' $ref: "#/definitions/User"
delete: delete:
summary: Delete a user summary: Delete a user
parameters: parameters:
@@ -189,14 +188,12 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'204': "204":
description: The user has been deleted description: The user has been deleted
/users/{name}/activity: /users/{name}/activity:
post: post:
summary: summary: Notify Hub of activity for a given user.
Notify Hub of activity for a given user. description: Notify the Hub of activity by the user,
description:
Notify the Hub of activity by the user,
e.g. accessing a service or (more likely) e.g. accessing a service or (more likely)
actively using a server. actively using a server.
parameters: parameters:
@@ -224,7 +221,7 @@ paths:
The default server has an empty name (''). The default server has an empty name ('').
type: object type: object
properties: properties:
'<server name>': "<server name>":
description: | description: |
Activity for a single server. Activity for a single server.
type: object type: object
@@ -237,16 +234,16 @@ paths:
description: | description: |
Timestamp of last-seen activity on this server. Timestamp of last-seen activity on this server.
example: example:
last_activity: '2019-02-06T12:54:14Z' last_activity: "2019-02-06T12:54:14Z"
servers: servers:
'': "":
last_activity: '2019-02-06T12:54:14Z' last_activity: "2019-02-06T12:54:14Z"
gpu: gpu:
last_activity: '2019-02-06T12:54:14Z' last_activity: "2019-02-06T12:54:14Z"
responses: responses:
'401': "401":
$ref: '#/responses/Unauthorized' $ref: "#/responses/Unauthorized"
'404': "404":
description: No such user description: No such user
/users/{name}/server: /users/{name}/server:
post: post:
@@ -271,9 +268,9 @@ paths:
type: object type: object
responses: responses:
'201': "201":
description: The user's notebook server has started description: The user's notebook server has started
'202': "202":
description: The user's notebook server has not yet started, but has been requested description: The user's notebook server has not yet started, but has been requested
delete: delete:
summary: Stop a user's server summary: Stop a user's server
@@ -284,9 +281,9 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'204': "204":
description: The user's notebook server has stopped description: The user's notebook server has stopped
'202': "202":
description: The user's notebook server has not yet stopped as it is taking a while to stop description: The user's notebook server has not yet stopped as it is taking a while to stop
/users/{name}/servers/{server_name}: /users/{name}/servers/{server_name}:
post: post:
@@ -300,7 +297,7 @@ paths:
- name: server_name - name: server_name
description: | description: |
name given to a named-server. name given to a named-server.
Note that depending on your JupyterHub infrastructure there are chracterter size limitation to `server_name`. Default spawner with K8s pod will not allow Jupyter Notebooks to be spawned with a name that contains more than 253 characters (keep in mind that the pod will be spawned with extra characters to identify the user and hub). Note that depending on your JupyterHub infrastructure there are chracterter size limitation to `server_name`. Default spawner with K8s pod will not allow Jupyter Notebooks to be spawned with a name that contains more than 253 characters (keep in mind that the pod will be spawned with extra characters to identify the user and hub).
in: path in: path
required: true required: true
@@ -316,9 +313,9 @@ paths:
schema: schema:
type: object type: object
responses: responses:
'201': "201":
description: The user's notebook named-server has started description: The user's notebook named-server has started
'202': "202":
description: The user's notebook named-server has not yet started, but has been requested description: The user's notebook named-server has not yet started, but has been requested
delete: delete:
summary: Stop a user's named-server summary: Stop a user's named-server
@@ -346,9 +343,9 @@ paths:
Removing a server deletes things like the state of the stopped server. Removing a server deletes things like the state of the stopped server.
Default: false. Default: false.
responses: responses:
'204': "204":
description: The user's notebook named-server has stopped description: The user's notebook named-server has stopped
'202': "202":
description: The user's notebook named-server has not yet stopped as it is taking a while to stop description: The user's notebook named-server has not yet stopped as it is taking a while to stop
/users/{name}/tokens: /users/{name}/tokens:
parameters: parameters:
@@ -360,15 +357,15 @@ paths:
get: get:
summary: List tokens for the user summary: List tokens for the user
responses: responses:
'200': "200":
description: The list of tokens description: The list of tokens
schema: schema:
type: array type: array
items: items:
$ref: '#/definitions/Token' $ref: "#/definitions/Token"
'401': "401":
$ref: '#/responses/Unauthorized' $ref: "#/responses/Unauthorized"
'404': "404":
description: No such user description: No such user
post: post:
summary: Create a new token for the user summary: Create a new token for the user
@@ -386,11 +383,11 @@ paths:
type: string type: string
description: A note attached to the token for future bookkeeping description: A note attached to the token for future bookkeeping
responses: responses:
'201': "201":
description: The newly created token description: The newly created token
schema: schema:
$ref: '#/definitions/Token' $ref: "#/definitions/Token"
'400': "400":
description: Body must be a JSON dict or empty description: Body must be a JSON dict or empty
/users/{name}/tokens/{token_id}: /users/{name}/tokens/{token_id}:
parameters: parameters:
@@ -406,33 +403,33 @@ paths:
get: get:
summary: Get the model for a token by id summary: Get the model for a token by id
responses: responses:
'200': "200":
description: The info for the new token description: The info for the new token
schema: schema:
$ref: '#/definitions/Token' $ref: "#/definitions/Token"
delete: delete:
summary: Delete (revoke) a token by id summary: Delete (revoke) a token by id
responses: responses:
'204': "204":
description: The token has been deleted description: The token has been deleted
/user: /user:
get: get:
summary: Return authenticated user's model summary: Return authenticated user's model
responses: responses:
'200': "200":
description: The authenticated user's model is returned. description: The authenticated user's model is returned.
schema: schema:
$ref: '#/definitions/User' $ref: "#/definitions/User"
/groups: /groups:
get: get:
summary: List groups summary: List groups
responses: responses:
'200': "200":
description: The list of groups description: The list of groups
schema: schema:
type: array type: array
items: items:
$ref: '#/definitions/Group' $ref: "#/definitions/Group"
/groups/{name}: /groups/{name}:
get: get:
summary: Get a group by name summary: Get a group by name
@@ -443,10 +440,10 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: The group model description: The group model
schema: schema:
$ref: '#/definitions/Group' $ref: "#/definitions/Group"
post: post:
summary: Create a group summary: Create a group
parameters: parameters:
@@ -456,10 +453,10 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'201': "201":
description: The group has been created description: The group has been created
schema: schema:
$ref: '#/definitions/Group' $ref: "#/definitions/Group"
delete: delete:
summary: Delete a group summary: Delete a group
parameters: parameters:
@@ -469,7 +466,7 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'204': "204":
description: The group has been deleted description: The group has been deleted
/groups/{name}/users: /groups/{name}/users:
post: post:
@@ -493,10 +490,10 @@ paths:
items: items:
type: string type: string
responses: responses:
'200': "200":
description: The users have been added to the group description: The users have been added to the group
schema: schema:
$ref: '#/definitions/Group' $ref: "#/definitions/Group"
delete: delete:
summary: Remove users from a group summary: Remove users from a group
parameters: parameters:
@@ -518,18 +515,18 @@ paths:
items: items:
type: string type: string
responses: responses:
'200': "200":
description: The users have been removed from the group description: The users have been removed from the group
/services: /services:
get: get:
summary: List services summary: List services
responses: responses:
'200': "200":
description: The service list description: The service list
schema: schema:
type: array type: array
items: items:
$ref: '#/definitions/Service' $ref: "#/definitions/Service"
/services/{name}: /services/{name}:
get: get:
summary: Get a service by name summary: Get a service by name
@@ -540,16 +537,16 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: The Service model description: The Service model
schema: schema:
$ref: '#/definitions/Service' $ref: "#/definitions/Service"
/proxy: /proxy:
get: get:
summary: Get the proxy's routing table summary: Get the proxy's routing table
description: A convenience alias for getting the routing table directly from the proxy description: A convenience alias for getting the routing table directly from the proxy
responses: responses:
'200': "200":
description: Routing table description: Routing table
schema: schema:
type: object type: object
@@ -557,7 +554,7 @@ paths:
post: post:
summary: Force the Hub to sync with the proxy summary: Force the Hub to sync with the proxy
responses: responses:
'200': "200":
description: Success description: Success
patch: patch:
summary: Notify the Hub about a new proxy summary: Notify the Hub about a new proxy
@@ -583,7 +580,7 @@ paths:
type: string type: string
description: CONFIGPROXY_AUTH_TOKEN for the new proxy description: CONFIGPROXY_AUTH_TOKEN for the new proxy
responses: responses:
'200': "200":
description: Success description: Success
/authorizations/token: /authorizations/token:
post: post:
@@ -605,7 +602,7 @@ paths:
password: password:
type: string type: string
responses: responses:
'200': "200":
description: The new API token description: The new API token
schema: schema:
type: object type: object
@@ -613,7 +610,7 @@ paths:
token: token:
type: string type: string
description: The new API token. description: The new API token.
'403': "403":
description: The user can not be authenticated. description: The user can not be authenticated.
/authorizations/token/{token}: /authorizations/token/{token}:
get: get:
@@ -624,9 +621,9 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: The user or service identified by the API token description: The user or service identified by the API token
'404': "404":
description: A user or service is not found. description: A user or service is not found.
/authorizations/cookie/{cookie_name}/{cookie_value}: /authorizations/cookie/{cookie_name}/{cookie_value}:
get: get:
@@ -642,15 +639,15 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: The user identified by the cookie description: The user identified by the cookie
schema: schema:
$ref: '#/definitions/User' $ref: "#/definitions/User"
'404': "404":
description: A user is not found. description: A user is not found.
/oauth2/authorize: /oauth2/authorize:
get: get:
summary: 'OAuth 2.0 authorize endpoint' summary: "OAuth 2.0 authorize endpoint"
description: | description: |
Redirect users to this URL to begin the OAuth process. Redirect users to this URL to begin the OAuth process.
It is not an API endpoint. It is not an API endpoint.
@@ -676,9 +673,9 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: Success description: Success
'400': "400":
description: OAuth2Error description: OAuth2Error
/oauth2/token: /oauth2/token:
post: post:
@@ -715,7 +712,7 @@ paths:
required: true required: true
type: string type: string
responses: responses:
'200': "200":
description: JSON response including the token description: JSON response including the token
schema: schema:
type: object type: object
@@ -742,9 +739,9 @@ paths:
type: boolean type: boolean
description: Whether users' notebook servers should be shutdown as well (default from Hub config) description: Whether users' notebook servers should be shutdown as well (default from Hub config)
responses: responses:
'202': "202":
description: Shutdown successful description: Shutdown successful
'400': "400":
description: Unexpeced value for proxy or servers description: Unexpeced value for proxy or servers
# Descriptions of common responses # Descriptions of common responses
responses: responses:
@@ -782,7 +779,7 @@ definitions:
type: array type: array
description: The active servers for this user. description: The active servers for this user.
items: items:
$ref: '#/definitions/Server' $ref: "#/definitions/Server"
Server: Server:
type: object type: object
properties: properties:

8
docs/source/_static/custom.css
View File

@@ -1,4 +1,4 @@
/* Added to avoid logo being too squeezed */ /* Added to avoid logo being too squeezed */
.navbar-brand { .navbar-brand {
height: 4rem !important; height: 4rem !important;
} }

336
docs/source/changelog.md
View File

File diff suppressed because one or more lines are too long

68
docs/source/contributing/roadmap.md
View File

@@ -6,8 +6,8 @@ the community of users, contributors, and maintainers.
The goal is to communicate priorities and upcoming release plans. The goal is to communicate priorities and upcoming release plans.
It is not a aimed at limiting contributions to what is listed here. It is not a aimed at limiting contributions to what is listed here.
## Using the roadmap ## Using the roadmap
### Sharing Feedback on the Roadmap ### Sharing Feedback on the Roadmap
All of the community is encouraged to provide feedback as well as share new All of the community is encouraged to provide feedback as well as share new
@@ -22,17 +22,17 @@ maintainers will help identify what a good next step is for the issue.
When submitting an issue, think about what "next step" category best describes When submitting an issue, think about what "next step" category best describes
your issue: your issue:
* **now**, concrete/actionable step that is ready for someone to start work on. - **now**, concrete/actionable step that is ready for someone to start work on.
These might be items that have a link to an issue or more abstract like These might be items that have a link to an issue or more abstract like
"decrease typos and dead links in the documentation" "decrease typos and dead links in the documentation"
* **soon**, less concrete/actionable step that is going to happen soon, - **soon**, less concrete/actionable step that is going to happen soon,
discussions around the topic are coming close to an end at which point it can discussions around the topic are coming close to an end at which point it can
move into the "now" category move into the "now" category
* **later**, abstract ideas or tasks, need a lot of discussion or - **later**, abstract ideas or tasks, need a lot of discussion or
experimentation to shape the idea so that it can be executed. Can also experimentation to shape the idea so that it can be executed. Can also
contain concrete/actionable steps that have been postponed on purpose contain concrete/actionable steps that have been postponed on purpose
(these are steps that could be in "now" but the decision was taken to work on (these are steps that could be in "now" but the decision was taken to work on
them later) them later)
### Reviewing and Updating the Roadmap ### Reviewing and Updating the Roadmap
@@ -47,8 +47,8 @@ For those please create a
The roadmap should give the reader an idea of what is happening next, what needs The roadmap should give the reader an idea of what is happening next, what needs
input and discussion before it can happen and what has been postponed. input and discussion before it can happen and what has been postponed.
## The roadmap proper ## The roadmap proper
### Project vision ### Project vision
JupyterHub is a dependable tool used by humans that reduces the complexity of JupyterHub is a dependable tool used by humans that reduces the complexity of
@@ -58,20 +58,19 @@ creating the environment in which a piece of software can be executed.
These "Now" items are considered active areas of focus for the project: These "Now" items are considered active areas of focus for the project:
* HubShare - a sharing service for use with JupyterHub. - HubShare - a sharing service for use with JupyterHub.
* Users should be able to: - Users should be able to:
- Push a project to other users. - Push a project to other users.
- Get a checkout of a project from other users. - Get a checkout of a project from other users.
- Push updates to a published project. - Push updates to a published project.
- Pull updates from a published project. - Pull updates from a published project.
- Manage conflicts/merges by simply picking a version (our/theirs) - Manage conflicts/merges by simply picking a version (our/theirs)
- Get a checkout of a project from the internet. These steps are completely different from saving notebooks/files. - Get a checkout of a project from the internet. These steps are completely different from saving notebooks/files.
- Have directories that are managed by git completely separately from our stuff. - Have directories that are managed by git completely separately from our stuff.
- Look at pushed content that they have access to without an explicit pull. - Look at pushed content that they have access to without an explicit pull.
- Define and manage teams of users. - Define and manage teams of users.
- Adding/removing a user to/from a team gives/removes them access to all projects that team has access to. - Adding/removing a user to/from a team gives/removes them access to all projects that team has access to.
- Build other services, such as static HTML publishing and dashboarding on top of these things. - Build other services, such as static HTML publishing and dashboarding on top of these things.
### Soon ### Soon
@@ -79,11 +78,10 @@ These "Soon" items are under discussion. Once an item reaches the point of an
actionable plan, the item will be moved to the "Now" section. Typically, actionable plan, the item will be moved to the "Now" section. Typically,
these will be moved at a future review of the roadmap. these will be moved at a future review of the roadmap.
* resource monitoring and management: - resource monitoring and management:
- (prometheus?) API for resource monitoring - (prometheus?) API for resource monitoring
- tracking activity on single-user servers instead of the proxy - tracking activity on single-user servers instead of the proxy
- notes and activity tracking per API token - notes and activity tracking per API token
### Later ### Later
@@ -92,6 +90,6 @@ time there is no active plan for an item. The project would like to find the
resources and time to discuss these ideas. resources and time to discuss these ideas.
- real-time collaboration - real-time collaboration
- Enter into real-time collaboration mode for a project that starts a shared execution context. - Enter into real-time collaboration mode for a project that starts a shared execution context.
- Once the single-user notebook package supports realtime collaboration, - Once the single-user notebook package supports realtime collaboration,
implement sharing mechanism integrated into the Hub. implement sharing mechanism integrated into the Hub.

57
docs/source/gallery-jhub-deployments.md
View File

@@ -8,23 +8,25 @@ high performance computing.
Please submit pull requests to update information or to add new institutions or uses. Please submit pull requests to update information or to add new institutions or uses.
## Academic Institutions, Research Labs, and Supercomputer Centers ## Academic Institutions, Research Labs, and Supercomputer Centers
### University of California Berkeley ### University of California Berkeley
- [BIDS - Berkeley Institute for Data Science](https://bids.berkeley.edu/) - [BIDS - Berkeley Institute for Data Science](https://bids.berkeley.edu/)
- [Teaching with Jupyter notebooks and JupyterHub](https://bids.berkeley.edu/resources/videos/teaching-ipythonjupyter-notebooks-and-jupyterhub)
- [Teaching with Jupyter notebooks and JupyterHub](https://bids.berkeley.edu/resources/videos/teaching-ipythonjupyter-notebooks-and-jupyterhub)
- [Data 8](http://data8.org/) - [Data 8](http://data8.org/)
- [GitHub organization](https://github.com/data-8)
- [GitHub organization](https://github.com/data-8)
- [NERSC](http://www.nersc.gov/) - [NERSC](http://www.nersc.gov/)
- [Press release on Jupyter and Cori](http://www.nersc.gov/news-publications/nersc-news/nersc-center-news/2016/jupyter-notebooks-will-open-up-new-possibilities-on-nerscs-cori-supercomputer/)
- [Moving and sharing data](https://www.nersc.gov/assets/Uploads/03-MovingAndSharingData-Cholia.pdf) - [Press release on Jupyter and Cori](http://www.nersc.gov/news-publications/nersc-news/nersc-center-news/2016/jupyter-notebooks-will-open-up-new-possibilities-on-nerscs-cori-supercomputer/)
- [Moving and sharing data](https://www.nersc.gov/assets/Uploads/03-MovingAndSharingData-Cholia.pdf)
- [Research IT](http://research-it.berkeley.edu) - [Research IT](http://research-it.berkeley.edu)
- [JupyterHub server supports campus research computation](http://research-it.berkeley.edu/blog/17/01/24/free-fully-loaded-jupyterhub-server-supports-campus-research-computation) - [JupyterHub server supports campus research computation](http://research-it.berkeley.edu/blog/17/01/24/free-fully-loaded-jupyterhub-server-supports-campus-research-computation)
### University of California Davis ### University of California Davis
@@ -62,20 +64,21 @@ easy to do with RStudio too.
### Clemson University ### Clemson University
- Advanced Computing - Advanced Computing
- [Palmetto cluster and JupyterHub](http://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html) - [Palmetto cluster and JupyterHub](http://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html)
### University of Colorado Boulder ### University of Colorado Boulder
- (CU Research Computing) CURC - (CU Research Computing) CURC
- [JupyterHub User Guide](https://www.rc.colorado.edu/support/user-guide/jupyterhub.html)
- Slurm job dispatched on Crestone compute cluster - [JupyterHub User Guide](https://www.rc.colorado.edu/support/user-guide/jupyterhub.html)
- log troubleshooting - Slurm job dispatched on Crestone compute cluster
- Profiles in IPython Clusters tab - log troubleshooting
- [Parallel Processing with JupyterHub tutorial](https://www.rc.colorado.edu/support/examples-and-tutorials/parallel-processing-with-jupyterhub.html) - Profiles in IPython Clusters tab
- [Parallel Programming with JupyterHub document](https://www.rc.colorado.edu/book/export/html/833) - [Parallel Processing with JupyterHub tutorial](https://www.rc.colorado.edu/support/examples-and-tutorials/parallel-processing-with-jupyterhub.html)
- [Parallel Programming with JupyterHub document](https://www.rc.colorado.edu/book/export/html/833)
- Earth Lab at CU - Earth Lab at CU
- [Tutorial on Parallel R on JupyterHub](https://earthdatascience.org/tutorials/parallel-r-on-jupyterhub/) - [Tutorial on Parallel R on JupyterHub](https://earthdatascience.org/tutorials/parallel-r-on-jupyterhub/)
### George Washington University ### George Washington University
@@ -112,7 +115,7 @@ easy to do with RStudio too.
### Paderborn University ### Paderborn University
- [Data Science (DICE) group](https://dice.cs.uni-paderborn.de/) - [Data Science (DICE) group](https://dice.cs.uni-paderborn.de/)
- [nbgraderutils](https://github.com/dice-group/nbgraderutils): Use JupyterHub + nbgrader + iJava kernel for online Java exercises. Used in lecture Statistical Natural Language Processing. - [nbgraderutils](https://github.com/dice-group/nbgraderutils): Use JupyterHub + nbgrader + iJava kernel for online Java exercises. Used in lecture Statistical Natural Language Processing.
### Penn State University ### Penn State University
@@ -125,27 +128,28 @@ easy to do with RStudio too.
### University of California San Diego ### University of California San Diego
- San Diego Supercomputer Center - Andrea Zonca - San Diego Supercomputer Center - Andrea Zonca
- [Deploy JupyterHub on a Supercomputer with SSH](https://zonca.github.io/2017/05/jupyterhub-hpc-batchspawner-ssh.html)
- [Run Jupyterhub on a Supercomputer](https://zonca.github.io/2015/04/jupyterhub-hpc.html) - [Deploy JupyterHub on a Supercomputer with SSH](https://zonca.github.io/2017/05/jupyterhub-hpc-batchspawner-ssh.html)
- [Deploy JupyterHub on a VM for a Workshop](https://zonca.github.io/2016/04/jupyterhub-sdsc-cloud.html) - [Run Jupyterhub on a Supercomputer](https://zonca.github.io/2015/04/jupyterhub-hpc.html)
- [Customize your Python environment in Jupyterhub](https://zonca.github.io/2017/02/customize-python-environment-jupyterhub.html) - [Deploy JupyterHub on a VM for a Workshop](https://zonca.github.io/2016/04/jupyterhub-sdsc-cloud.html)
- [Jupyterhub deployment on multiple nodes with Docker Swarm](https://zonca.github.io/2016/05/jupyterhub-docker-swarm.html) - [Customize your Python environment in Jupyterhub](https://zonca.github.io/2017/02/customize-python-environment-jupyterhub.html)
- [Sample deployment of Jupyterhub in HPC on SDSC Comet](https://zonca.github.io/2017/02/sample-deployment-jupyterhub-hpc.html) - [Jupyterhub deployment on multiple nodes with Docker Swarm](https://zonca.github.io/2016/05/jupyterhub-docker-swarm.html)
- [Sample deployment of Jupyterhub in HPC on SDSC Comet](https://zonca.github.io/2017/02/sample-deployment-jupyterhub-hpc.html)
- Educational Technology Services - Paul Jamason - Educational Technology Services - Paul Jamason
- [jupyterhub.ucsd.edu](https://jupyterhub.ucsd.edu) - [jupyterhub.ucsd.edu](https://jupyterhub.ucsd.edu)
### TACC University of Texas ### TACC University of Texas
### Texas A&M ### Texas A&M
- Kristen Thyng - Oceanography - Kristen Thyng - Oceanography
- [Teaching with JupyterHub and nbgrader](http://kristenthyng.com/blog/2016/09/07/jupyterhub+nbgrader/) - [Teaching with JupyterHub and nbgrader](http://kristenthyng.com/blog/2016/09/07/jupyterhub+nbgrader/)
### Elucidata ### Elucidata
- What's new in Jupyter Notebooks @[Elucidata](https://elucidata.io/):
- Using Jupyter Notebooks with Jupyterhub on GCP, managed by GKE - What's new in Jupyter Notebooks @[Elucidata](https://elucidata.io/):
- https://medium.com/elucidata/why-you-should-be-using-a-jupyter-notebook-8385a4ccd93d - Using Jupyter Notebooks with Jupyterhub on GCP, managed by GKE - https://medium.com/elucidata/why-you-should-be-using-a-jupyter-notebook-8385a4ccd93d
## Service Providers ## Service Providers
@@ -175,7 +179,6 @@ easy to do with RStudio too.
- [Deploying JupyterHub on Hadoop](https://jupyterhub-on-hadoop.readthedocs.io) - [Deploying JupyterHub on Hadoop](https://jupyterhub-on-hadoop.readthedocs.io)
## Miscellaneous ## Miscellaneous
- https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1 - https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1

10
docs/source/getting-started/authenticators-users-basics.md
View File

@@ -9,7 +9,6 @@ with an account and password on the system will be allowed to login.
You can restrict which users are allowed to login with a set, You can restrict which users are allowed to login with a set,
`Authenticator.allowed_users`: `Authenticator.allowed_users`:
```python ```python
c.Authenticator.allowed_users = {'mal', 'zoe', 'inara', 'kaylee'} c.Authenticator.allowed_users = {'mal', 'zoe', 'inara', 'kaylee'}
``` ```
@@ -28,6 +27,7 @@ A set of initial admin users, `admin_users` can configured be as follows:
```python ```python
c.Authenticator.admin_users = {'mal', 'zoe'} c.Authenticator.admin_users = {'mal', 'zoe'}
``` ```
Users in the admin set are automatically added to the user `allowed_users` set, Users in the admin set are automatically added to the user `allowed_users` set,
if they are not already present. if they are not already present.
@@ -44,8 +44,8 @@ c.PAMAuthenticator.admin_groups = {'wheel'}
Since the default `JupyterHub.admin_access` setting is False, the admins Since the default `JupyterHub.admin_access` setting is False, the admins
do not have permission to log in to the single user notebook servers do not have permission to log in to the single user notebook servers
owned by *other users*. If `JupyterHub.admin_access` is set to True, owned by _other users_. If `JupyterHub.admin_access` is set to True,
then admins have permission to log in *as other users* on their then admins have permission to log in _as other users_ on their
respective machines, for debugging. **As a courtesy, you should make respective machines, for debugging. **As a courtesy, you should make
sure your users know if admin_access is enabled.** sure your users know if admin_access is enabled.**
@@ -115,5 +115,5 @@ To set a global password, add this to the config file:
c.DummyAuthenticator.password = "some_password" c.DummyAuthenticator.password = "some_password"
``` ```
[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module [pam]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
[OAuthenticator]: https://github.com/jupyterhub/oauthenticator [oauthenticator]: https://github.com/jupyterhub/oauthenticator

12
docs/source/getting-started/config-basics.md
View File

@@ -56,7 +56,7 @@ To display all command line options that are available for configuration:
``` ```
Configuration using the command line options is done when launching JupyterHub. Configuration using the command line options is done when launching JupyterHub.
For example, to start JupyterHub on ``10.0.1.2:443`` with https, you For example, to start JupyterHub on `10.0.1.2:443` with https, you
would enter: would enter:
```bash ```bash
@@ -88,13 +88,13 @@ meant as illustration, are:
## Run the proxy separately ## Run the proxy separately
This is *not* strictly necessary, but useful in many cases. If you This is _not_ strictly necessary, but useful in many cases. If you
use a custom proxy (e.g. Traefik), this also not needed. use a custom proxy (e.g. Traefik), this also not needed.
Connections to user servers go through the proxy, and *not* the hub Connections to user servers go through the proxy, and _not_ the hub
itself. If the proxy stays running when the hub restarts (for itself. If the proxy stays running when the hub restarts (for
maintenance, re-configuration, etc.), then use connections are not maintenance, re-configuration, etc.), then use connections are not
interrupted. For simplicity, by default the hub starts the proxy interrupted. For simplicity, by default the hub starts the proxy
automatically, so if the hub restarts, the proxy restarts, and user automatically, so if the hub restarts, the proxy restarts, and user
connections are interrupted. It is easy to run the proxy separately, connections are interrupted. It is easy to run the proxy separately,
for information see [the separate proxy page](../reference/separate-proxy). for information see [the separate proxy page](../reference/separate-proxy).

7
docs/source/getting-started/faq.md
View File

@@ -1,6 +1,5 @@
# Frequently asked questions # Frequently asked questions
### How do I share links to notebooks? ### How do I share links to notebooks?
In short, where you see `/user/name/notebooks/foo.ipynb` use `/hub/user-redirect/notebooks/foo.ipynb` (replace `/user/name` with `/hub/user-redirect`). In short, where you see `/user/name/notebooks/foo.ipynb` use `/hub/user-redirect/notebooks/foo.ipynb` (replace `/user/name` with `/hub/user-redirect`).
@@ -11,9 +10,9 @@ Your first instinct might be to copy the URL you see in the browser,
e.g. `hub.jupyter.org/user/yourname/notebooks/coolthing.ipynb`. e.g. `hub.jupyter.org/user/yourname/notebooks/coolthing.ipynb`.
However, let's break down what this URL means: However, let's break down what this URL means:
`hub.jupyter.org/user/yourname/` is the URL prefix handled by *your server*, `hub.jupyter.org/user/yourname/` is the URL prefix handled by _your server_,
which means that sharing this URL is asking the person you share the link with which means that sharing this URL is asking the person you share the link with
to come to *your server* and look at the exact same file. to come to _your server_ and look at the exact same file.
In most circumstances, this is forbidden by permissions because the person you share with does not have access to your server. In most circumstances, this is forbidden by permissions because the person you share with does not have access to your server.
What actually happens when someone visits this URL will depend on whether your server is running and other factors. What actually happens when someone visits this URL will depend on whether your server is running and other factors.
@@ -22,7 +21,7 @@ A typical situation is that you have some shared or common filesystem,
such that the same path corresponds to the same document such that the same path corresponds to the same document
(either the exact same document or another copy of it). (either the exact same document or another copy of it).
Typically, what folks want when they do sharing like this Typically, what folks want when they do sharing like this
is for each visitor to open the same file *on their own server*, is for each visitor to open the same file _on their own server_,
so Breq would open `/user/breq/notebooks/foo.ipynb` and so Breq would open `/user/breq/notebooks/foo.ipynb` and
Seivarden would open `/user/seivarden/notebooks/foo.ipynb`, etc. Seivarden would open `/user/seivarden/notebooks/foo.ipynb`, etc.

38
docs/source/getting-started/institutional-faq.md
View File

@@ -18,14 +18,14 @@ to the use-cases of large organizations.
Here is a quick breakdown of these three tools: Here is a quick breakdown of these three tools:
* **The Jupyter Notebook** is a document specification (the `.ipynb`) file that interweaves - **The Jupyter Notebook** is a document specification (the `.ipynb`) file that interweaves
narrative text with code cells and their outputs. It is also a graphical interface narrative text with code cells and their outputs. It is also a graphical interface
that allows users to edit these documents. There are also several other graphical interfaces that allows users to edit these documents. There are also several other graphical interfaces
that allow users to edit the `.ipynb` format (nteract, Jupyter Lab, Google Colab, Kaggle, etc). that allow users to edit the `.ipynb` format (nteract, Jupyter Lab, Google Colab, Kaggle, etc).
* **JupyterLab** is a flexible and extendible user interface for interactive computing. It - **JupyterLab** is a flexible and extendible user interface for interactive computing. It
has several extensions that are tailored for using Jupyter Notebooks, as well as extensions has several extensions that are tailored for using Jupyter Notebooks, as well as extensions
for other parts of the data science stack. for other parts of the data science stack.
* **JupyterHub** is an application that manages interactive computing sessions for **multiple users**. - **JupyterHub** is an application that manages interactive computing sessions for **multiple users**.
It also connects them with infrastructure those users wish to access. It can provide It also connects them with infrastructure those users wish to access. It can provide
remote access to Jupyter Notebooks and Jupyter Lab for many people. remote access to Jupyter Notebooks and Jupyter Lab for many people.
@@ -50,20 +50,20 @@ scalable infrastructure, large datasets, and high-performance computing.
JupyterHub is used at a variety of institutions in academia, JupyterHub is used at a variety of institutions in academia,
industry, and government research labs. It is most-commonly used by two kinds of groups: industry, and government research labs. It is most-commonly used by two kinds of groups:
* Small teams (e.g., data science teams, research labs, or collaborative projects) to provide a - Small teams (e.g., data science teams, research labs, or collaborative projects) to provide a
shared resource for interactive computing, collaboration, and analytics. shared resource for interactive computing, collaboration, and analytics.
* Large teams (e.g., a department, a large class, or a large group of remote users) to provide - Large teams (e.g., a department, a large class, or a large group of remote users) to provide
access to organizational hardware, data, and analytics environments at scale. access to organizational hardware, data, and analytics environments at scale.
Here are a sample of organizations that use JupyterHub: Here are a sample of organizations that use JupyterHub:
* **Universities and colleges**: UC Berkeley, UC San Diego, Cal Poly SLO, Harvard University, University of Chicago, - **Universities and colleges**: UC Berkeley, UC San Diego, Cal Poly SLO, Harvard University, University of Chicago,
University of Oslo, University of Sheffield, Université Paris Sud, University of Versailles University of Oslo, University of Sheffield, Université Paris Sud, University of Versailles
* **Research laboratories**: NASA, NCAR, NOAA, the Large Synoptic Survey Telescope, Brookhaven National Lab, - **Research laboratories**: NASA, NCAR, NOAA, the Large Synoptic Survey Telescope, Brookhaven National Lab,
Minnesota Supercomputing Institute, ALCF, CERN, Lawrence Livermore National Laboratory Minnesota Supercomputing Institute, ALCF, CERN, Lawrence Livermore National Laboratory
* **Online communities**: Pangeo, Quantopian, mybinder.org, MathHub, Open Humans - **Online communities**: Pangeo, Quantopian, mybinder.org, MathHub, Open Humans
* **Computing infrastructure providers**: NERSC, San Diego Supercomputing Center, Compute Canada - **Computing infrastructure providers**: NERSC, San Diego Supercomputing Center, Compute Canada
* **Companies**: Capital One, SANDVIK code, Globus - **Companies**: Capital One, SANDVIK code, Globus
See the [Gallery of JupyterHub deployments](../gallery-jhub-deployments.md) for See the [Gallery of JupyterHub deployments](../gallery-jhub-deployments.md) for
a more complete list of JupyterHub deployments at institutions. a more complete list of JupyterHub deployments at institutions.
@@ -95,14 +95,13 @@ The most common way to set up a JupyterHub is to use a JupyterHub distribution,
and opinionated ways to set up a JupyterHub on particular kinds of infrastructure. The two distributions and opinionated ways to set up a JupyterHub on particular kinds of infrastructure. The two distributions
that we currently suggest are: that we currently suggest are:
* [Zero to JupyterHub for Kubernetes](https://z2jh.jupyter.org) is a scalable JupyterHub deployment and - [Zero to JupyterHub for Kubernetes](https://z2jh.jupyter.org) is a scalable JupyterHub deployment and
guide that runs on Kubernetes. Better for larger or dynamic user groups (50-10,000) or more complex guide that runs on Kubernetes. Better for larger or dynamic user groups (50-10,000) or more complex
compute/data needs. compute/data needs.
* [The Littlest JupyterHub](https://tljh.jupyter.org) is a lightweight JupyterHub that runs on a single - [The Littlest JupyterHub](https://tljh.jupyter.org) is a lightweight JupyterHub that runs on a single
single machine (in the cloud or under your desk). Better for smaller usergroups (4-80) or more single machine (in the cloud or under your desk). Better for smaller usergroups (4-80) or more
lightweight computational resources. lightweight computational resources.
### Does JupyterHub run well in the cloud? ### Does JupyterHub run well in the cloud?
Yes - most deployments of JupyterHub are run via cloud infrastructure and on a variety of cloud providers. Yes - most deployments of JupyterHub are run via cloud infrastructure and on a variety of cloud providers.
@@ -123,9 +122,9 @@ The short answer: yes. JupyterHub as a standalone application has been battle-te
level for several years, and makes a number of "default" security decisions that are reasonable for most level for several years, and makes a number of "default" security decisions that are reasonable for most
users. users.
* For security considerations in the base JupyterHub application, - For security considerations in the base JupyterHub application,
[see the JupyterHub security page](https://jupyterhub.readthedocs.io/en/stable/reference/websecurity.html) [see the JupyterHub security page](https://jupyterhub.readthedocs.io/en/stable/reference/websecurity.html)
* For security considerations when deploying JupyterHub on Kubernetes, see the - For security considerations when deploying JupyterHub on Kubernetes, see the
[JupyterHub on Kubernetes security page](https://zero-to-jupyterhub.readthedocs.io/en/latest/security.html). [JupyterHub on Kubernetes security page](https://zero-to-jupyterhub.readthedocs.io/en/latest/security.html).
The longer answer: it depends on your deployment. Because JupyterHub is very flexible, it can be used The longer answer: it depends on your deployment. Because JupyterHub is very flexible, it can be used
@@ -137,15 +136,13 @@ If you are worried about security, don't hesitate to reach out to the JupyterHub
[Jupyter Community Forum](https://discourse.jupyter.org/c/jupyterhub). This community of practice has many [Jupyter Community Forum](https://discourse.jupyter.org/c/jupyterhub). This community of practice has many
individuals with experience running secure JupyterHub deployments. individuals with experience running secure JupyterHub deployments.
### Does JupyterHub provide computing or data infrastructure? ### Does JupyterHub provide computing or data infrastructure?
No - JupyterHub manages user sessions and can *control* computing infrastructure, but it does not provide these No - JupyterHub manages user sessions and can _control_ computing infrastructure, but it does not provide these
things itself. You are expected to run JupyterHub on your own infrastructure (local or in the cloud). Moreover, things itself. You are expected to run JupyterHub on your own infrastructure (local or in the cloud). Moreover,
JupyterHub has no internal concept of "data", but is designed to be able to communicate with data repositories JupyterHub has no internal concept of "data", but is designed to be able to communicate with data repositories
(again, either locally or remotely) for use within interactive computing sessions. (again, either locally or remotely) for use within interactive computing sessions.
### How do I manage users? ### How do I manage users?
JupyterHub offers a few options for managing your users. Upon setting up a JupyterHub, you can choose what JupyterHub offers a few options for managing your users. Upon setting up a JupyterHub, you can choose what
@@ -154,7 +151,7 @@ email address, or choose a username / password when they first log-in, or offloa
another service such as an organization's OAuth. another service such as an organization's OAuth.
The users of a JupyterHub are stored locally, and can be modified manually by an administrator of the JupyterHub. The users of a JupyterHub are stored locally, and can be modified manually by an administrator of the JupyterHub.
Moreover, the *active* users on a JupyterHub can be found on the administrator's page. This page Moreover, the _active_ users on a JupyterHub can be found on the administrator's page. This page
gives you the abiltiy to stop or restart kernels, inspect user filesystems, and even take over user gives you the abiltiy to stop or restart kernels, inspect user filesystems, and even take over user
sessions to assist them with debugging. sessions to assist them with debugging.
@@ -182,7 +179,6 @@ connect with other infrastructure tools (like Dask or Spark). This allows users
scalable or high-performance resources from within their JupyterHub sessions. The logic of scalable or high-performance resources from within their JupyterHub sessions. The logic of
how those resources are controlled is taken care of by the non-JupyterHub application. how those resources are controlled is taken care of by the non-JupyterHub application.
### Can JupyterHub be used with my high-performance computing resources? ### Can JupyterHub be used with my high-performance computing resources?
Yes - JupyterHub can provide access to many kinds of computing infrastructure. Yes - JupyterHub can provide access to many kinds of computing infrastructure.
@@ -218,7 +214,6 @@ the technologies your JupyterHub will use (e.g., dev-ops knowledge with cloud co
In general, the base JupyterHub deployment is not the bottleneck for setup, it is connecting In general, the base JupyterHub deployment is not the bottleneck for setup, it is connecting
your JupyterHub with the various services and tools that you wish to provide to your users. your JupyterHub with the various services and tools that you wish to provide to your users.
### How well does JupyterHub scale? What are JupyterHub's limitations? ### How well does JupyterHub scale? What are JupyterHub's limitations?
JupyterHub works well at both a small scale (e.g., a single VM or machine) as well as a JupyterHub works well at both a small scale (e.g., a single VM or machine) as well as a
@@ -227,7 +222,6 @@ for user bases as large as 10,000. The scalability of JupyterHub largely depends
infrastructure on which it is deployed. JupyterHub has been designed to be lightweight and infrastructure on which it is deployed. JupyterHub has been designed to be lightweight and
flexible, so you can tailor your JupyterHub deployment to your needs. flexible, so you can tailor your JupyterHub deployment to your needs.
### Is JupyterHub resilient? What happens when a machine goes down? ### Is JupyterHub resilient? What happens when a machine goes down?
For JupyterHubs that are deployed in a containerized environment (e.g., Kubernetes), it is For JupyterHubs that are deployed in a containerized environment (e.g., Kubernetes), it is

8
docs/source/getting-started/networking-basics.md
View File

@@ -11,7 +11,7 @@ This section will help you with basic proxy and network configuration to:
The Proxy's main IP address setting determines where JupyterHub is available to users. The Proxy's main IP address setting determines where JupyterHub is available to users.
By default, JupyterHub is configured to be available on all network interfaces By default, JupyterHub is configured to be available on all network interfaces
(`''`) on port 8000. *Note*: Use of `'*'` is discouraged for IP configuration; (`''`) on port 8000. _Note_: Use of `'*'` is discouraged for IP configuration;
instead, use of `'0.0.0.0'` is preferred. instead, use of `'0.0.0.0'` is preferred.
Changing the Proxy's main IP address and port can be done with the following Changing the Proxy's main IP address and port can be done with the following
@@ -74,7 +74,7 @@ The Hub service listens only on `localhost` (port 8081) by default.
The Hub needs to be accessible from both the proxy and all Spawners. The Hub needs to be accessible from both the proxy and all Spawners.
When spawning local servers, an IP address setting of `localhost` is fine. When spawning local servers, an IP address setting of `localhost` is fine.
If *either* the Proxy *or* (more likely) the Spawners will be remote or If _either_ the Proxy _or_ (more likely) the Spawners will be remote or
isolated in containers, the Hub must listen on an IP that is accessible. isolated in containers, the Hub must listen on an IP that is accessible.
```python ```python
@@ -93,9 +93,9 @@ c.JupyterHub.hub_connect_ip = '10.0.1.4' # ip as seen on the docker network. Ca
## Adjusting the hub's URL ## Adjusting the hub's URL
The hub will most commonly be running on a hostname of its own. If it The hub will most commonly be running on a hostname of its own. If it
is not – for example, if the hub is being reverse-proxied and being is not – for example, if the hub is being reverse-proxied and being
exposed at a URL such as `https://proxy.example.org/jupyter/` – then exposed at a URL such as `https://proxy.example.org/jupyter/` – then
you will need to tell JupyterHub the base URL of the service. In such you will need to tell JupyterHub the base URL of the service. In such
a case, it is both necessary and sufficient to set a case, it is both necessary and sufficient to set
`c.JupyterHub.base_url = '/jupyter/'` in the configuration. `c.JupyterHub.base_url = '/jupyter/'` in the configuration.

4
docs/source/getting-started/services-basics.md
View File

@@ -16,8 +16,8 @@ document will:
- clarify that API tokens can be used to authenticate to - clarify that API tokens can be used to authenticate to
single-user servers as of [version 0.8.0](../changelog) single-user servers as of [version 0.8.0](../changelog)
- show how the [jupyterhub_idle_culler][] script can be: - show how the [jupyterhub_idle_culler][] script can be:
- used in a Hub-managed service - used in a Hub-managed service
- run as a standalone script - run as a standalone script
Both examples for `jupyterhub_idle_culler` will communicate tasks to the Both examples for `jupyterhub_idle_culler` will communicate tasks to the
Hub via the REST API. Hub via the REST API.

17
docs/source/installation-guide-hard.md
View File

@@ -12,7 +12,6 @@ script. However, instead of bundling all these step for you into one installer,
This makes it easy to customize any part (e.g. if you want to run other services on the same system and need to make them This makes it easy to customize any part (e.g. if you want to run other services on the same system and need to make them
work together), as well as giving you full control and understanding of your setup. work together), as well as giving you full control and understanding of your setup.
## Prerequisites ## Prerequisites
Your own server with administrator (root) access. This could be a local machine, a remotely hosted one, or a cloud instance Your own server with administrator (root) access. This could be a local machine, a remotely hosted one, or a cloud instance
@@ -22,7 +21,6 @@ through the command line - useful if you log into your machine remotely using SS
This tutorial was tested on **Ubuntu 18.04**. No other Linux distributions have been tested, but the instructions This tutorial was tested on **Ubuntu 18.04**. No other Linux distributions have been tested, but the instructions
should be reasonably straightforward to adapt. should be reasonably straightforward to adapt.
## Goals ## Goals
JupyterLab enables access to a multiple 'kernels', each one being a given environment for a given language. The most JupyterLab enables access to a multiple 'kernels', each one being a given environment for a given language. The most
@@ -39,7 +37,6 @@ JupyterHub+JupyterLab as a 'app' or webservice, which will connect to the kernel
- We will show how users can create their own private conda environments, where they can install whatever they like. - We will show how users can create their own private conda environments, where they can install whatever they like.
The default JupyterHub Authenticator uses PAM to authenticate system users with their username and password. One can The default JupyterHub Authenticator uses PAM to authenticate system users with their username and password. One can
[choose the authenticator](https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#authenticators) [choose the authenticator](https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#authenticators)
that best suits their needs. In this guide we will use the default Authenticator because it makes it easy for everyone to manage data that best suits their needs. In this guide we will use the default Authenticator because it makes it easy for everyone to manage data
@@ -103,11 +100,13 @@ First create the folder for the JupyterHub configuration and navigate to it:
sudo mkdir -p /opt/jupyterhub/etc/jupyterhub/ sudo mkdir -p /opt/jupyterhub/etc/jupyterhub/
cd /opt/jupyterhub/etc/jupyterhub/ cd /opt/jupyterhub/etc/jupyterhub/
``` ```
Then generate the default configuration file Then generate the default configuration file
```sh ```sh
sudo /opt/jupyterhub/bin/jupyterhub --generate-config sudo /opt/jupyterhub/bin/jupyterhub --generate-config
``` ```
This will produce the default configuration file `/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py` This will produce the default configuration file `/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py`
You will need to edit the configuration file to make the JupyterLab interface by the default. You will need to edit the configuration file to make the JupyterLab interface by the default.
@@ -130,6 +129,7 @@ sudo mkdir -p /opt/jupyterhub/etc/systemd
``` ```
Then create the following text file using your [favourite editor](https://micro-editor.github.io/) at Then create the following text file using your [favourite editor](https://micro-editor.github.io/) at
```sh ```sh
/opt/jupyterhub/etc/systemd/jupyterhub.service /opt/jupyterhub/etc/systemd/jupyterhub.service
``` ```
@@ -198,6 +198,7 @@ this means they will get automatic updates with the rest of the system. Setup re
instructions are copied from [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/rpm-debian.html): instructions are copied from [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/rpm-debian.html):
Install Anacononda public gpg key to trusted store Install Anacononda public gpg key to trusted store
```sh ```sh
curl https://repo.anaconda.com/pkgs/misc/gpgkeys/anaconda.asc | gpg --dearmor > conda.gpg curl https://repo.anaconda.com/pkgs/misc/gpgkeys/anaconda.asc | gpg --dearmor > conda.gpg
sudo install -o root -g root -m 644 conda.gpg /etc/apt/trusted.gpg.d/ sudo install -o root -g root -m 644 conda.gpg /etc/apt/trusted.gpg.d/
@@ -228,6 +229,7 @@ sudo ln -s /opt/conda/etc/profile.d/conda.sh /etc/profile.d/conda.sh
### Install a default conda environment for all users ### Install a default conda environment for all users
First create a folder for conda envs (might exist already): First create a folder for conda envs (might exist already):
```sh ```sh
sudo mkdir /opt/conda/envs/ sudo mkdir /opt/conda/envs/
``` ```
@@ -254,12 +256,12 @@ might be used by other services, or if you want to modify the JupyterHub install
```sh ```sh
sudo /opt/conda/envs/python/bin/python -m ipykernel install --prefix /usr/local/ --name 'python' --display-name "Python (default)" sudo /opt/conda/envs/python/bin/python -m ipykernel install --prefix /usr/local/ --name 'python' --display-name "Python (default)"
```` ```
### Setting up users' own conda environments ### Setting up users' own conda environments
There is relatively little for the administrator to do here, as users will have to set up their own environments using the shell. There is relatively little for the administrator to do here, as users will have to set up their own environments using the shell.
On login they should run `conda init` or `/opt/conda/bin/conda`. The can then use conda to set up their environment, On login they should run `conda init` or `/opt/conda/bin/conda`. The can then use conda to set up their environment,
although they must also install `ipykernel`. Once done, they can enable their kernel using: although they must also install `ipykernel`. Once done, they can enable their kernel using:
```sh ```sh
@@ -268,7 +270,6 @@ although they must also install `ipykernel`. Once done, they can enable their ke
This will place the kernel spec into their home folder, where Jupyter will look for it on startup. This will place the kernel spec into their home folder, where Jupyter will look for it on startup.
## Setting up a reverse proxy ## Setting up a reverse proxy
The guide so far results in JupyterHub running on port 8000. It is not generally advisable to run open web services in The guide so far results in JupyterHub running on port 8000. It is not generally advisable to run open web services in
@@ -281,6 +282,7 @@ this way - instead, use a reverse proxy running on standard HTTP/HTTPS ports.
> Firewalls may be set up using `ufw` or `firewalld` and combined with `fail2ban`. > Firewalls may be set up using `ufw` or `firewalld` and combined with `fail2ban`.
### Using Nginx ### Using Nginx
Nginx is a mature and established web server and reverse proxy and is easy to install using `sudo apt install nginx`. Nginx is a mature and established web server and reverse proxy and is easy to install using `sudo apt install nginx`.
Details on using Nginx as a reverse proxy can be found elsewhere. Here, we will only outline the additional steps needed Details on using Nginx as a reverse proxy can be found elsewhere. Here, we will only outline the additional steps needed
to setup JupyterHub with Nginx and host it at a given URL e.g. `<your-server-ip-or-url>/jupyter`. to setup JupyterHub with Nginx and host it at a given URL e.g. `<your-server-ip-or-url>/jupyter`.
@@ -316,7 +318,7 @@ Add the following snippet to your nginx configuration file (e.g. `/etc/nginx/sit
} }
``` ```
Also add this snippet before the *server* block: Also add this snippet before the _server_ block:
``` ```
map $http_upgrade $connection_upgrade { map $http_upgrade $connection_upgrade {
@@ -337,7 +339,6 @@ If there are no errors, you can restart the Nginx service for the new configurat
sudo systemctl restart nginx.service sudo systemctl restart nginx.service
``` ```
## Getting started using your new JupyterHub ## Getting started using your new JupyterHub
Once you have setup JupyterHub and Nginx proxy as described, you can browse to your JupyterHub IP or URL Once you have setup JupyterHub and Nginx proxy as described, you can browse to your JupyterHub IP or URL

14
docs/source/quickstart.md
View File

@@ -12,23 +12,23 @@ Before installing JupyterHub, you will need:
- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node), - [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
using your operating system's package manager. using your operating system's package manager.
* If you are using **`conda`**, the nodejs and npm dependencies will be installed for - If you are using **`conda`**, the nodejs and npm dependencies will be installed for
you by conda. you by conda.
* If you are using **`pip`**, install a recent version of - If you are using **`pip`**, install a recent version of
[nodejs/npm](https://docs.npmjs.com/getting-started/installing-node). [nodejs/npm](https://docs.npmjs.com/getting-started/installing-node).
For example, install it on Linux (Debian/Ubuntu) using: For example, install it on Linux (Debian/Ubuntu) using:
``` ```
sudo apt-get install npm nodejs-legacy sudo apt-get install npm nodejs-legacy
``` ```
The `nodejs-legacy` package installs the `node` executable and is currently The `nodejs-legacy` package installs the `node` executable and is currently
required for npm to work on Debian/Ubuntu. required for npm to work on Debian/Ubuntu.
- A [pluggable authentication module (PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module) - A [pluggable authentication module (PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module)
to use the [default Authenticator](./getting-started/authenticators-users-basics.md). 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 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. using the operating system's package manager.
- TLS certificate and key for HTTPS communication - TLS certificate and key for HTTPS communication
- Domain name - Domain name
@@ -78,12 +78,12 @@ Visit `https://localhost:8000` in your browser, and sign in with your unix
credentials. credentials.
To **allow multiple users to sign in** to the Hub server, you must start To **allow multiple users to sign in** to the Hub server, you must start
`jupyterhub` as a *privileged user*, such as root: `jupyterhub` as a _privileged user_, such as root:
```bash ```bash
sudo jupyterhub sudo jupyterhub
``` ```
The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges) 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 describes how to run the server as a _less privileged user_. This requires
additional configuration of the system. additional configuration of the system.

22
docs/source/reference/authenticators.md
View File

@@ -89,7 +89,6 @@ class DictionaryAuthenticator(Authenticator):
return data['username'] return data['username']
``` ```
#### Normalize usernames #### Normalize usernames
Since the Authenticator and Spawner both use the same username, Since the Authenticator and Spawner both use the same username,
@@ -111,11 +110,10 @@ When using `PAMAuthenticator`, you can set
normalize usernames using PAM (basically round-tripping them: username normalize usernames using PAM (basically round-tripping them: username
to uid to username), which is useful in case you use some external to uid to username), which is useful in case you use some external
service that allows multiple usernames mapping to the same user (such service that allows multiple usernames mapping to the same user (such
as ActiveDirectory, yes, this really happens). When as ActiveDirectory, yes, this really happens). When
`pam_normalize_username` is on, usernames are *not* normalized to `pam_normalize_username` is on, usernames are _not_ normalized to
lowercase. lowercase.
#### Validate usernames #### Validate usernames
In most cases, there is a very limited set of acceptable usernames. In most cases, there is a very limited set of acceptable usernames.
@@ -132,7 +130,6 @@ To only allow usernames that start with 'w':
c.Authenticator.username_pattern = r'w.*' c.Authenticator.username_pattern = r'w.*'
``` ```
### How to write a custom authenticator ### How to write a custom authenticator
You can use custom Authenticator subclasses to enable authentication You can use custom Authenticator subclasses to enable authentication
@@ -145,7 +142,6 @@ and [post_spawn_stop(user, spawner)][], are hooks that can be used to do
auth-related startup (e.g. opening PAM sessions) and cleanup auth-related startup (e.g. opening PAM sessions) and cleanup
(e.g. closing PAM sessions). (e.g. closing PAM sessions).
See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators). See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
If you are interested in writing a custom authenticator, you can read If you are interested in writing a custom authenticator, you can read
@@ -186,7 +182,6 @@ Additionally, configurable attributes for your authenticator will
appear in jupyterhub help output and auto-generated configuration files appear in jupyterhub help output and auto-generated configuration files
via `jupyterhub --generate-config`. via `jupyterhub --generate-config`.
### Authentication state ### Authentication state
JupyterHub 0.8 adds the ability to persist state related to authentication, JupyterHub 0.8 adds the ability to persist state related to authentication,
@@ -220,12 +215,10 @@ To store auth_state, two conditions must be met:
export JUPYTERHUB_CRYPT_KEY=$(openssl rand -hex 32) export JUPYTERHUB_CRYPT_KEY=$(openssl rand -hex 32)
``` ```
JupyterHub uses [Fernet](https://cryptography.io/en/latest/fernet/) to encrypt auth_state. JupyterHub uses [Fernet](https://cryptography.io/en/latest/fernet/) to encrypt auth_state.
To facilitate key-rotation, `JUPYTERHUB_CRYPT_KEY` may be a semicolon-separated list of encryption keys. To facilitate key-rotation, `JUPYTERHUB_CRYPT_KEY` may be a semicolon-separated list of encryption keys.
If there are multiple keys present, the **first** key is always used to persist any new auth_state. If there are multiple keys present, the **first** key is always used to persist any new auth_state.
#### Using auth_state #### Using auth_state
Typically, if `auth_state` is persisted it is desirable to affect the Spawner environment in some way. Typically, if `auth_state` is persisted it is desirable to affect the Spawner environment in some way.
@@ -266,11 +259,10 @@ PAM session.
Beginning with version 0.8, JupyterHub is an OAuth provider. Beginning with version 0.8, JupyterHub is an OAuth provider.
[authenticator]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/auth.py
[Authenticator]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/auth.py [pam]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module [oauth]: https://en.wikipedia.org/wiki/OAuth
[OAuth]: https://en.wikipedia.org/wiki/OAuth [github oauth]: https://developer.github.com/v3/oauth/
[GitHub OAuth]: https://developer.github.com/v3/oauth/ [oauthenticator]: https://github.com/jupyterhub/oauthenticator
[OAuthenticator]: https://github.com/jupyterhub/oauthenticator
[pre_spawn_start(user, spawner)]: https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.pre_spawn_start [pre_spawn_start(user, spawner)]: https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.pre_spawn_start
[post_spawn_stop(user, spawner)]: https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.post_spawn_stop [post_spawn_stop(user, spawner)]: https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.post_spawn_stop

17
docs/source/reference/config-ghoauth.md
View File

@@ -3,18 +3,17 @@
In this example, we show a configuration file for a fairly standard JupyterHub In this example, we show a configuration file for a fairly standard JupyterHub
deployment with the following assumptions: deployment with the following assumptions:
* Running JupyterHub on a single cloud server - Running JupyterHub on a single cloud server
* Using SSL on the standard HTTPS port 443 - Using SSL on the standard HTTPS port 443
* Using GitHub OAuth (using oauthenticator) for login - Using GitHub OAuth (using oauthenticator) for login
* Using the default spawner (to configure other spawners, uncomment and edit - Using the default spawner (to configure other spawners, uncomment and edit
`spawner_class` as well as follow the instructions for your desired spawner) `spawner_class` as well as follow the instructions for your desired spawner)
* Users exist locally on the server - Users exist locally on the server
* Users' notebooks to be served from `~/assignments` to allow users to browse - Users' notebooks to be served from `~/assignments` to allow users to browse
for notebooks within other users' home directories for notebooks within other users' home directories
* You want the landing page for each user to be a `Welcome.ipynb` notebook in - You want the landing page for each user to be a `Welcome.ipynb` notebook in
their assignments directory. their assignments directory.
* All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`. - All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`.
The `jupyterhub_config.py` file would have these settings: The `jupyterhub_config.py` file would have these settings:

33
docs/source/reference/config-proxy.md
View File

@@ -6,12 +6,12 @@ SSL port `443`. This could be useful if the JupyterHub server machine is also
hosting other domains or content on `443`. The goal in this example is to hosting other domains or content on `443`. The goal in this example is to
satisfy the following: satisfy the following:
* JupyterHub is running on a server, accessed *only* via `HUB.DOMAIN.TLD:443` - JupyterHub is running on a server, accessed _only_ via `HUB.DOMAIN.TLD:443`
* On the same machine, `NO_HUB.DOMAIN.TLD` strictly serves different content, - On the same machine, `NO_HUB.DOMAIN.TLD` strictly serves different content,
also on port `443` also on port `443`
* `nginx` or `apache` is used as the public access point (which means that - `nginx` or `apache` is used as the public access point (which means that
only nginx/apache will bind to `443`) only nginx/apache will bind to `443`)
* After testing, the server in question should be able to score at least an A on the - 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/) 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 needed JupyterHub configuration in `jupyterhub_config.py`:
@@ -144,6 +144,7 @@ Now restart `nginx`, restart the JupyterHub, and enjoy accessing
`https://NO_HUB.DOMAIN.TLD`. `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 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.
@@ -155,8 +156,8 @@ semanage port -a -t http_port_t -p tcp 8000
setsebool -P httpd_can_network_relay 1 setsebool -P httpd_can_network_relay 1
setsebool -P httpd_can_network_connect 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 ## Apache
@@ -211,22 +212,24 @@ Listen 443
</VirtualHost> </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 the jupyterhub under /jhub/ or other location please use the below configurations:
- JupyterHub running locally at http://127.0.0.1:8000/jhub/ or other location - JupyterHub running locally at http://127.0.0.1:8000/jhub/ or other location
httpd.conf amendments: httpd.conf amendments:
```bash ```bash
RewriteRule /jhub/(.*) ws://127.0.0.1:8000/jhub/$1 [NE.P,L] RewriteRule /jhub/(.*) ws://127.0.0.1:8000/jhub/$1 [NE.P,L]
RewriteRule /jhub/(.*) http://127.0.0.1:8000/jhub/$1 [NE,P,L] RewriteRule /jhub/(.*) http://127.0.0.1:8000/jhub/$1 [NE,P,L]
ProxyPass /jhub/ http://127.0.0.1:8000/jhub/ ProxyPass /jhub/ http://127.0.0.1:8000/jhub/
ProxyPassReverse /jhub/ http://127.0.0.1:8000/jhub/ ProxyPassReverse /jhub/ http://127.0.0.1:8000/jhub/
``` ```
jupyterhub_config.py amendments: jupyterhub_config.py amendments:
```bash
--The public facing URL of the whole JupyterHub application. ```bash
--This is the address on which the proxy will bind. Sets protocol, ip, base_url --The public facing URL of the whole JupyterHub application.
c.JupyterHub.bind_url = 'http://127.0.0.1:8000/jhub/' --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/'
```

21
docs/source/reference/config-sudo.md
View File

@@ -9,7 +9,7 @@ Only do this if you are very sure you must.
There are many Authenticators and Spawners available for JupyterHub. Some, such There are many Authenticators and Spawners available for JupyterHub. Some, such
as DockerSpawner or OAuthenticator, do not need any elevated permissions. This as DockerSpawner or OAuthenticator, do not need any elevated permissions. This
document describes how to get the full default behavior of JupyterHub while document describes how to get the full default behavior of JupyterHub while
running notebook servers as real system users on a shared system without running notebook servers as real system users on a shared system without
running the Hub itself as root. running the Hub itself as root.
Since JupyterHub needs to spawn processes as other users, the simplest way Since JupyterHub needs to spawn processes as other users, the simplest way
@@ -50,10 +50,9 @@ To do this we add to `/etc/sudoers` (use `visudo` for safe editing of sudoers):
- specify the list of users `JUPYTER_USERS` for whom `rhea` can spawn servers - specify the list of users `JUPYTER_USERS` for whom `rhea` can spawn servers
- set the command `JUPYTER_CMD` that `rhea` can execute on behalf of users - set the command `JUPYTER_CMD` that `rhea` can execute on behalf of users
- give `rhea` permission to run `JUPYTER_CMD` on behalf of `JUPYTER_USERS` - give `rhea` permission to run `JUPYTER_CMD` on behalf of `JUPYTER_USERS`
without entering a password without entering a password
For example: For example:
```bash ```bash
@@ -91,16 +90,16 @@ $ adduser -G jupyterhub newuser
Test that the new user doesn't need to enter a password to run the sudospawner Test that the new user doesn't need to enter a password to run the sudospawner
command. command.
This should prompt for your password to switch to rhea, but *not* prompt for This should prompt for your password to switch to rhea, but _not_ prompt for
any password for the second switch. It should show some help output about any password for the second switch. It should show some help output about
logging options: logging options:
```bash ```bash
$ sudo -u rhea sudo -n -u $USER /usr/local/bin/sudospawner --help $ sudo -u rhea sudo -n -u $USER /usr/local/bin/sudospawner --help
Usage: /usr/local/bin/sudospawner [OPTIONS] Usage: /usr/local/bin/sudospawner [OPTIONS]
Options: Options:
--help show this help information --help show this help information
... ...
``` ```
@@ -151,12 +150,13 @@ We want our new user to be able to read the shadow passwords, so add it to the s
$ sudo usermod -a -G shadow rhea $ sudo usermod -a -G shadow rhea
``` ```
If you want jupyterhub to serve pages on a restricted port (such as port 80 for http), If you want jupyterhub to serve pages on a restricted port (such as port 80 for http),
then you will need to give `node` permission to do so: then you will need to give `node` permission to do so:
```bash ```bash
sudo setcap 'cap_net_bind_service=+ep' /usr/bin/node sudo setcap 'cap_net_bind_service=+ep' /usr/bin/node
``` ```
However, you may want to further understand the consequences of this. However, you may want to further understand the consequences of this.
You may also be interested in limiting the amount of CPU any process can use You may also be interested in limiting the amount of CPU any process can use
@@ -165,7 +165,6 @@ distributions' packaging system. This can be used to keep any user's process
from using too much CPU cycles. You can configure it accoring to [these from using too much CPU cycles. You can configure it accoring to [these
instructions](http://ubuntuforums.org/showthread.php?t=992706). instructions](http://ubuntuforums.org/showthread.php?t=992706).
### Shadow group (FreeBSD) ### Shadow group (FreeBSD)
**NOTE:** This has not been tested and may not work as expected. **NOTE:** This has not been tested and may not work as expected.
@@ -186,7 +185,7 @@ $ sudo chgrp shadow /etc/master.passwd
$ sudo chmod g+r /etc/master.passwd $ sudo chmod g+r /etc/master.passwd
``` ```
We want our new user to be able to read the shadow passwords, so add it to the We want our new user to be able to read the shadow passwords, so add it to the
shadow group: shadow group:
```bash ```bash
@@ -220,7 +219,7 @@ Finally, start the server as our newly configured user, `rhea`:
```bash ```bash
$ cd /etc/jupyterhub $ cd /etc/jupyterhub
$ sudo -u rhea jupyterhub --JupyterHub.spawner_class=sudospawner.SudoSpawner $ sudo -u rhea jupyterhub --JupyterHub.spawner_class=sudospawner.SudoSpawner
``` ```
And try logging in. And try logging in.
@@ -228,7 +227,7 @@ And try logging in.
If you still get a generic `Permission denied` `PermissionError`, it's possible SELinux is blocking you. If you still get a generic `Permission denied` `PermissionError`, it's possible SELinux is blocking you.
Here's how you can make a module to allow this. Here's how you can make a module to allow this.
First, put this in a file named `sudo_exec_selinux.te`: First, put this in a file named `sudo_exec_selinux.te`:
```bash ```bash
module sudo_exec_selinux 1.1; module sudo_exec_selinux 1.1;

16
docs/source/reference/config-user-env.md
View File

@@ -22,20 +22,18 @@ This section will focus on user environments, including:
- Installing kernelspecs - Installing kernelspecs
- Using containers vs. multi-user hosts - Using containers vs. multi-user hosts
## Installing packages ## Installing packages
To make packages available to users, you generally will install packages To make packages available to users, you generally will install packages
system-wide or in a shared environment. system-wide or in a shared environment.
This installation location should always be in the same environment that This installation location should always be in the same environment that
`jupyterhub-singleuser` itself is installed in, and must be *readable and `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 executable_ by your users. If you want users to be able to install additional
packages, it must also be *writable* by your users. packages, it must also be _writable_ by your users.
If you are using a standard system Python install, you would use: If you are using a standard system Python install, you would use:
```bash ```bash
sudo python3 -m pip install numpy sudo python3 -m pip install numpy
``` ```
@@ -47,7 +45,6 @@ You may also use conda to install packages. If you do, you should make sure
that the conda environment has appropriate permissions for users to be able to that the conda environment has appropriate permissions for users to be able to
run Python code in the env. run Python code in the env.
## Configuring Jupyter and IPython ## Configuring Jupyter and IPython
[Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/config_overview.html) [Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/config_overview.html)
@@ -64,6 +61,7 @@ users. It's generally more efficient to configure user environments "system-wide
and it's a good idea to avoid creating files in users' home directories. and it's a good idea to avoid creating files in users' home directories.
The typical locations for these config files are: The typical locations for these config files are:
- **system-wide** in `/etc/{jupyter|ipython}` - **system-wide** in `/etc/{jupyter|ipython}`
- **env-wide** (environment wide) in `{sys.prefix}/etc/{jupyter|ipython}`. - **env-wide** (environment wide) in `{sys.prefix}/etc/{jupyter|ipython}`.
@@ -91,7 +89,6 @@ c.MappingKernelManager.cull_idle_timeout = 20 * 60
c.MappingKernelManager.cull_interval = 2 * 60 c.MappingKernelManager.cull_interval = 2 * 60
``` ```
## Installing kernelspecs ## Installing kernelspecs
You may have multiple Jupyter kernels installed and want to make sure that You may have multiple Jupyter kernels installed and want to make sure that
@@ -119,7 +116,6 @@ sure are available, I can install their specs system-wide (in /usr/local) with:
/path/to/python2 -m IPython kernel install --prefix=/usr/local /path/to/python2 -m IPython kernel install --prefix=/usr/local
``` ```
## Multi-user hosts vs. Containers ## Multi-user hosts vs. Containers
There are two broad categories of user environments that depend on what There are two broad categories of user environments that depend on what
@@ -141,8 +137,8 @@ When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or
DockerSpawner), the 'system-wide' environment is really the container image DockerSpawner), the 'system-wide' environment is really the container image
which you are using for users. which you are using for users.
In both cases, you want to *avoid putting configuration in user home In both cases, you want to _avoid putting configuration in user home
directories* because users can change those configuration settings. Also, directories_ because users can change those configuration settings. Also,
home directories typically persist once they are created, so they are home directories typically persist once they are created, so they are
difficult for admins to update later. difficult for admins to update later.

4
docs/source/reference/database.md
View File

@@ -46,8 +46,8 @@ additional configuration required for MySQL that is not needed for PostgreSQL.
- You should use the `pymysql` sqlalchemy provider (the other one, MySQLdb, - You should use the `pymysql` sqlalchemy provider (the other one, MySQLdb,
isn't available for py3). isn't available for py3).
- You also need to set `pool_recycle` to some value (typically 60 - 300) - You also need to set `pool_recycle` to some value (typically 60 - 300)
which depends on your MySQL setup. This is necessary since MySQL kills which depends on your MySQL setup. This is necessary since MySQL kills
connections serverside if they've been idle for a while, and the connection connections serverside if they've been idle for a while, and the connection
from the hub will be idle for longer than most connections. This behavior from the hub will be idle for longer than most connections. This behavior
will lead to frustrating 'the connection has gone away' errors from will lead to frustrating 'the connection has gone away' errors from

6
docs/source/reference/proxy.md
View File

@@ -54,7 +54,7 @@ class MyProxy(Proxy):
"""Stop the proxy""" """Stop the proxy"""
``` ```
These methods **may** be coroutines. These methods **may** be coroutines.
`c.Proxy.should_start` is a configurable flag that determines whether the `c.Proxy.should_start` is a configurable flag that determines whether the
Hub should call these methods when the Hub itself starts and stops. Hub should call these methods when the Hub itself starts and stops.
@@ -103,7 +103,7 @@ route to be proxied, such as `/user/name/`. A routespec will:
When adding a route, JupyterHub may pass a JSON-serializable dict as a `data` When adding a route, JupyterHub may pass a JSON-serializable dict as a `data`
argument that should be attached to the proxy route. When that route is argument that should be attached to the proxy route. When that route is
retrieved, the `data` argument should be returned as well. If your proxy retrieved, the `data` argument should be returned as well. If your proxy
implementation doesn't support storing data attached to routes, then your implementation doesn't support storing data attached to routes, then your
Python wrapper may have to handle storing the `data` piece itself, e.g in a Python wrapper may have to handle storing the `data` piece itself, e.g in a
simple file or database. simple file or database.
@@ -136,7 +136,7 @@ async def delete_route(self, routespec):
### Retrieving routes ### Retrieving routes
For retrieval, you only *need* to implement a single method that retrieves all For retrieval, you only _need_ to implement a single method that retrieves all
routes. The return value for this function should be a dictionary, keyed by routes. The return value for this function should be a dictionary, keyed by
`routespect`, of dicts whose keys are the same three arguments passed to `routespect`, of dicts whose keys are the same three arguments passed to
`add_route` (`routespec`, `target`, `data`) `add_route` (`routespec`, `target`, `data`)

10
docs/source/reference/rest.md
View File

@@ -169,7 +169,7 @@ curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/us
``` ```
With the named-server functionality, it's now possible to launch more than one With the named-server functionality, it's now possible to launch more than one
specifically named servers against a given user. This could be used, for instance, specifically named servers against a given user. This could be used, for instance,
to launch each server based on a different image. to launch each server based on a different image.
First you must enable named-servers by including the following setting in the `jupyterhub_config.py` file. First you must enable named-servers by including the following setting in the `jupyterhub_config.py` file.
@@ -187,6 +187,7 @@ hub:
``` ```
With that setting in place, a new named-server is activated like this: With that setting in place, a new named-server is activated like this:
```bash ```bash
curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverA>" curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverA>"
curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverB>" curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverB>"
@@ -201,7 +202,6 @@ will need to be able to handle the case of multiple servers per user and ensure
uniqueness of names, particularly if servers are spawned via docker containers uniqueness of names, particularly if servers are spawned via docker containers
or kubernetes pods. or kubernetes pods.
## Learn more about the API ## Learn more about the API
You can see the full [JupyterHub REST API][] for details. This REST API Spec can You can see the full [JupyterHub REST API][] for details. This REST API Spec can
@@ -210,6 +210,6 @@ Both resources contain the same information and differ only in its display.
Note: The Swagger specification is being renamed the [OpenAPI Initiative][]. Note: The Swagger specification is being renamed the [OpenAPI Initiative][].
[interactive style on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default [interactive style on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
[OpenAPI Initiative]: https://www.openapis.org/ [openapi initiative]: https://www.openapis.org/
[JupyterHub REST API]: ./rest-api [jupyterhub rest api]: ./rest-api
[Jupyter Notebook REST API]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml [jupyter notebook rest api]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml

32
docs/source/reference/separate-proxy.md
View File

@@ -1,28 +1,26 @@
# Running proxy separately from the hub # Running proxy separately from the hub
## Background ## Background
The thing which users directly connect to is the proxy, by default The thing which users directly connect to is the proxy, by default
`configurable-http-proxy`. The proxy either redirects users to the `configurable-http-proxy`. The proxy either redirects users to the
hub (for login and managing servers), or to their own single-user hub (for login and managing servers), or to their own single-user
servers. Thus, as long as the proxy stays running, access to existing servers. Thus, as long as the proxy stays running, access to existing
servers continues, even if the hub itself restarts or goes down. servers continues, even if the hub itself restarts or goes down.
When you first configure the hub, you may not even realize this When you first configure the hub, you may not even realize this
because the proxy is automatically managed by the hub. This is great because the proxy is automatically managed by the hub. This is great
for getting started and even most use, but everytime you restart the for getting started and even most use, but everytime you restart the
hub, all user connections also get restarted. But it's also simple to hub, all user connections also get restarted. But it's also simple to
run the proxy as a service separate from the hub, so that you are free run the proxy as a service separate from the hub, so that you are free
to reconfigure the hub while only interrupting users who are currently to reconfigure the hub while only interrupting users who are currently
actively starting the hub. actively starting the hub.
The default JupyterHub proxy is The default JupyterHub proxy is
[configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy), [configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy),
and that page has some docs. If you are using a different proxy, such and that page has some docs. If you are using a different proxy, such
as Traefik, these instructions are probably not relevant to you. as Traefik, these instructions are probably not relevant to you.
## Configuration options ## Configuration options
`c.JupyterHub.cleanup_servers = False` should be set, which tells the `c.JupyterHub.cleanup_servers = False` should be set, which tells the
@@ -37,24 +35,20 @@ it yourself).
token for authenticating communication with the proxy. token for authenticating communication with the proxy.
`c.ConfigurableHTTPProxy.api_url = 'http://localhost:8001'` should be `c.ConfigurableHTTPProxy.api_url = 'http://localhost:8001'` should be
set to the URL which the hub uses to connect *to the proxy's API*. set to the URL which the hub uses to connect _to the proxy's API_.
## Proxy configuration ## Proxy configuration
You need to configure a service to start the proxy. An example You need to configure a service to start the proxy. An example
command line for this is `configurable-http-proxy --ip=127.0.0.1 command line for this is `configurable-http-proxy --ip=127.0.0.1 --port=8000 --api-ip=127.0.0.1 --api-port=8001 --default-target=http://localhost:8081 --error-target=http://localhost:8081/hub/error`. (Details for how to
--port=8000 --api-ip=127.0.0.1 --api-port=8001
--default-target=http://localhost:8081
--error-target=http://localhost:8081/hub/error`. (Details for how to
do this is out of scope for this tutorial - for example it might be a do this is out of scope for this tutorial - for example it might be a
systemd service on within another docker cotainer). The proxy has no systemd service on within another docker cotainer). The proxy has no
configuration files, all configuration is via the command line and configuration files, all configuration is via the command line and
environment variables. environment variables.
`--api-ip` and `--api-port` (which tells the proxy where to listen) should match the hub's `ConfigurableHTTPProxy.api_url`. `--api-ip` and `--api-port` (which tells the proxy where to listen) should match the hub's `ConfigurableHTTPProxy.api_url`.
`--ip`, `-port`, and other options configure the *user* connections to the proxy. `--ip`, `-port`, and other options configure the _user_ connections to the proxy.
`--default-target` and `--error-target` should point to the hub, and used when users navigate to the proxy originally. `--default-target` and `--error-target` should point to the hub, and used when users navigate to the proxy originally.
@@ -63,18 +57,16 @@ match the token given to `c.ConfigurableHTTPProxy.auth_token`.
You should check the [configurable-http-proxy You should check the [configurable-http-proxy
options](https://github.com/jupyterhub/configurable-http-proxy) to see options](https://github.com/jupyterhub/configurable-http-proxy) to see
what other options are needed, for example SSL options. Note that what other options are needed, for example SSL options. Note that
these are configured in the hub if the hub is starting the proxy - you these are configured in the hub if the hub is starting the proxy - you
need to move the options to here. need to move the options to here.
## Docker image ## Docker image
You can use [jupyterhub configurable-http-proxy docker You can use [jupyterhub configurable-http-proxy docker
image](https://hub.docker.com/r/jupyterhub/configurable-http-proxy/) image](https://hub.docker.com/r/jupyterhub/configurable-http-proxy/)
to run the proxy. to run the proxy.
## See also ## See also
* [jupyterhub configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy) - [jupyterhub configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy)

78
docs/source/reference/services.md
View File

@@ -45,17 +45,14 @@ A Service may have the following properties:
- `url: str (default - None)` - The URL where the service is/should be. If a - `url: str (default - None)` - The URL where the service is/should be. If a
url is specified for where the Service runs its own web server, url is specified for where the Service runs its own web server,
the service will be added to the proxy at `/services/:name` the service will be added to the proxy at `/services/:name`
- `api_token: str (default - None)` - For Externally-Managed Services you need to specify - `api_token: str (default - None)` - For Externally-Managed Services you need to specify
an API token to perform API requests to the Hub an API token to perform API requests to the Hub
If a service is also to be managed by the Hub, it has a few extra options: If a service is also to be managed by the Hub, it has a few extra options:
- `command: (str/Popen list)` - Command for JupyterHub to spawn the service. - `command: (str/Popen list)` - Command for JupyterHub to spawn the service. - Only use this if the service should be a subprocess. - If command is not specified, the Service is assumed to be managed
- Only use this if the service should be a subprocess. externally. - If a command is specified for launching the Service, the Service will
- If command is not specified, the Service is assumed to be managed be started and managed by the Hub.
externally.
- If a command is specified for launching the Service, the Service will
be started and managed by the Hub.
- `environment: dict` - additional environment variables for the Service. - `environment: dict` - additional environment variables for the Service.
- `user: str` - the name of a system user to manage the Service. If - `user: str` - the name of a system user to manage the Service. If
unspecified, run as the same user as the Hub. unspecified, run as the same user as the Hub.
@@ -103,9 +100,9 @@ parameters, which describe the environment needed to start the Service process:
- `environment: dict` - additional environment variables for the Service. - `environment: dict` - additional environment variables for the Service.
- `user: str` - name of the user to run the server if different from the Hub. - `user: str` - name of the user to run the server if different from the Hub.
Requires Hub to be root. Requires Hub to be root.
- `cwd: path` directory in which to run the Service, if different from the - `cwd: path` directory in which to run the Service, if different from the
Hub directory. Hub directory.
The Hub will pass the following environment variables to launch the Service: The Hub will pass the following environment variables to launch the Service:
@@ -199,16 +196,16 @@ can be used by services. You may go beyond this reference implementation and
create custom hub-authenticating clients and services. We describe the process create custom hub-authenticating clients and services. We describe the process
below. below.
The reference, or base, implementation is the [`HubAuth`][HubAuth] class, The reference, or base, implementation is the [`HubAuth`][hubauth] class,
which implements the requests to the Hub. which implements the requests to the Hub.
To use HubAuth, you must set the `.api_token`, either programmatically when constructing the class, To use HubAuth, you must set the `.api_token`, either programmatically when constructing the class,
or via the `JUPYTERHUB_API_TOKEN` environment variable. or via the `JUPYTERHUB_API_TOKEN` environment variable.
Most of the logic for authentication implementation is found in the Most of the logic for authentication implementation is found in the
[`HubAuth.user_for_cookie`][HubAuth.user_for_cookie] [`HubAuth.user_for_cookie`][hubauth.user_for_cookie]
and in the and in the
[`HubAuth.user_for_token`][HubAuth.user_for_token] [`HubAuth.user_for_token`][hubauth.user_for_token]
methods, which makes a request of the Hub, and returns: methods, which makes a request of the Hub, and returns:
- None, if no user could be identified, or - None, if no user could be identified, or
@@ -285,11 +282,10 @@ def whoami(user):
) )
``` ```
### Authenticating tornado services with JupyterHub ### Authenticating tornado services with JupyterHub
Since most Jupyter services are written with tornado, Since most Jupyter services are written with tornado,
we include a mixin class, [`HubAuthenticated`][HubAuthenticated], we include a mixin class, [`HubAuthenticated`][hubauthenticated],
for quickly authenticating your own tornado services with JupyterHub. for quickly authenticating your own tornado services with JupyterHub.
Tornado's `@web.authenticated` method calls a Handler's `.get_current_user` Tornado's `@web.authenticated` method calls a Handler's `.get_current_user`
@@ -310,7 +306,6 @@ class MyHandler(HubAuthenticated, web.RequestHandler):
... ...
``` ```
The HubAuth will automatically load the desired configuration from the Service The HubAuth will automatically load the desired configuration from the Service
environment variables. environment variables.
@@ -320,44 +315,42 @@ username and user group list, respectively. If a user matches neither the user
list nor the group list, they will not be allowed access. If both are left list nor the group list, they will not be allowed access. If both are left
undefined, then any user will be allowed. undefined, then any user will be allowed.
### Implementing your own Authentication with JupyterHub ### Implementing your own Authentication with JupyterHub
If you don't want to use the reference implementation If you don't want to use the reference implementation
(e.g. you find the implementation a poor fit for your Flask app), (e.g. you find the implementation a poor fit for your Flask app),
you can implement authentication via the Hub yourself. you can implement authentication via the Hub yourself.
We recommend looking at the [`HubAuth`][HubAuth] class implementation for reference, We recommend looking at the [`HubAuth`][hubauth] class implementation for reference,
and taking note of the following process: and taking note of the following process:
1. retrieve the cookie `jupyterhub-services` from the request. 1. retrieve the cookie `jupyterhub-services` from the request.
2. Make an API request `GET /hub/api/authorizations/cookie/jupyterhub-services/cookie-value`, 2. Make an API request `GET /hub/api/authorizations/cookie/jupyterhub-services/cookie-value`,
where cookie-value is the url-encoded value of the `jupyterhub-services` cookie. where cookie-value is the url-encoded value of the `jupyterhub-services` cookie.
This request must be authenticated with a Hub API token in the `Authorization` header, This request must be authenticated with a Hub API token in the `Authorization` header,
for example using the `api_token` from your [external service's configuration](#externally-managed-services). for example using the `api_token` from your [external service's configuration](#externally-managed-services).
For example, with [requests][]: For example, with [requests][]:
```python ```python
r = requests.get( r = requests.get(
'/'.join(["http://127.0.0.1:8081/hub/api", '/'.join(["http://127.0.0.1:8081/hub/api",
"authorizations/cookie/jupyterhub-services", "authorizations/cookie/jupyterhub-services",
quote(encrypted_cookie, safe=''), quote(encrypted_cookie, safe=''),
]), ]),
headers = { headers = {
'Authorization' : 'token %s' % api_token, 'Authorization' : 'token %s' % api_token,
}, },
) )
r.raise_for_status() r.raise_for_status()
user = r.json() user = r.json()
``` ```
3. On success, the reply will be a JSON model describing the user: 3. On success, the reply will be a JSON model describing the user:
```json ```json
{ {
"name": "inara", "name": "inara",
"groups": ["serenity", "guild"], "groups": ["serenity", "guild"]
} }
``` ```
@@ -367,12 +360,11 @@ and an example of its configuration is found [here](https://github.com/jupyter/n
nbviewer can also be run as a Hub-Managed Service as described [nbviewer README][nbviewer example] nbviewer can also be run as a Hub-Managed Service as described [nbviewer README][nbviewer example]
section on securing the notebook viewer. section on securing the notebook viewer.
[requests]: http://docs.python-requests.org/en/master/ [requests]: http://docs.python-requests.org/en/master/
[services_auth]: ../api/services.auth.html [services_auth]: ../api/services.auth.html
[HubAuth]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth [hubauth]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth
[HubAuth.user_for_cookie]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth.user_for_cookie [hubauth.user_for_cookie]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth.user_for_cookie
[HubAuth.user_for_token]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth.user_for_token [hubauth.user_for_token]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth.user_for_token
[HubAuthenticated]: ../api/services.auth.html#jupyterhub.services.auth.HubAuthenticated [hubauthenticated]: ../api/services.auth.html#jupyterhub.services.auth.HubAuthenticated
[nbviewer example]: https://github.com/jupyter/nbviewer#securing-the-notebook-viewer [nbviewer example]: https://github.com/jupyter/nbviewer#securing-the-notebook-viewer
[jupyterhub_idle_culler]: https://github.com/jupyterhub/jupyterhub-idle-culler [jupyterhub_idle_culler]: https://github.com/jupyterhub/jupyterhub-idle-culler

25
docs/source/reference/spawners.md
View File

@@ -8,18 +8,17 @@ and a custom Spawner needs to be able to take three actions:
- poll whether the process is still running - poll whether the process is still running
- stop the process - stop the process
## Examples ## Examples
Custom Spawners for JupyterHub can be found on the [JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Spawners). Custom Spawners for JupyterHub can be found on the [JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Spawners).
Some examples include: Some examples include:
- [DockerSpawner](https://github.com/jupyterhub/dockerspawner) for spawning user servers in Docker containers - [DockerSpawner](https://github.com/jupyterhub/dockerspawner) for spawning user servers in Docker containers
* `dockerspawner.DockerSpawner` for spawning identical Docker containers for - `dockerspawner.DockerSpawner` for spawning identical Docker containers for
each users each users
* `dockerspawner.SystemUserSpawner` for spawning Docker containers with an - `dockerspawner.SystemUserSpawner` for spawning Docker containers with an
environment and home directory for each users environment and home directory for each users
* both `DockerSpawner` and `SystemUserSpawner` also work with Docker Swarm for - both `DockerSpawner` and `SystemUserSpawner` also work with Docker Swarm for
launching containers on remote machines launching containers on remote machines
- [SudoSpawner](https://github.com/jupyterhub/sudospawner) enables JupyterHub to - [SudoSpawner](https://github.com/jupyterhub/sudospawner) enables JupyterHub to
run without being root, by spawning an intermediate process via `sudo` run without being root, by spawning an intermediate process via `sudo`
@@ -30,7 +29,6 @@ Some examples include:
- [SSHSpawner](https://github.com/NERSC/sshspawner) to spawn notebooks - [SSHSpawner](https://github.com/NERSC/sshspawner) to spawn notebooks
on a remote server using SSH on a remote server using SSH
## Spawner control methods ## Spawner control methods
### Spawner.start ### Spawner.start
@@ -41,7 +39,7 @@ an object encapsulating the user's name, authentication, and server info.
The return value of `Spawner.start` should be the (ip, port) of the running server. The return value of `Spawner.start` should be the (ip, port) of the running server.
**NOTE:** When writing coroutines, *never* `yield` in between a database change and a commit. **NOTE:** When writing coroutines, _never_ `yield` in between a database change and a commit.
Most `Spawner.start` functions will look similar to this example: Most `Spawner.start` functions will look similar to this example:
@@ -80,7 +78,6 @@ to check if the local process is still running. On Windows, it uses `psutil.pid_
`Spawner.stop` should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting. `Spawner.stop` should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
## Spawner state ## Spawner state
JupyterHub should be able to stop and restart without tearing down JupyterHub should be able to stop and restart without tearing down
@@ -112,7 +109,6 @@ def clear_state(self):
self.pid = 0 self.pid = 0
``` ```
## Spawner options form ## Spawner options form
(new in 0.4) (new in 0.4)
@@ -170,8 +166,7 @@ which would return:
When `Spawner.start` is called, this dictionary is accessible as `self.user_options`. When `Spawner.start` is called, this dictionary is accessible as `self.user_options`.
[spawner]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/spawner.py
[Spawner]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/spawner.py
## Writing a custom spawner ## Writing a custom spawner
@@ -212,7 +207,6 @@ Additionally, configurable attributes for your spawner will
appear in jupyterhub help output and auto-generated configuration files appear in jupyterhub help output and auto-generated configuration files
via `jupyterhub --generate-config`. via `jupyterhub --generate-config`.
## Spawners, resource limits, and guarantees (Optional) ## Spawners, resource limits, and guarantees (Optional)
Some spawners of the single-user notebook servers allow setting limits or Some spawners of the single-user notebook servers allow setting limits or
@@ -224,10 +218,9 @@ support for them**. For example, LocalProcessSpawner, the default
spawner, does not support limits and guarantees. One of the spawners spawner, does not support limits and guarantees. One of the spawners
that supports limits and guarantees is the `systemdspawner`. that supports limits and guarantees is the `systemdspawner`.
### Memory Limits & Guarantees ### Memory Limits & Guarantees
`c.Spawner.mem_limit`: A **limit** specifies the *maximum amount of memory* `c.Spawner.mem_limit`: A **limit** specifies the _maximum amount of memory_
that may be allocated, though there is no promise that the maximum amount will that may be allocated, though there is no promise that the maximum amount will
be available. In supported spawners, you can set `c.Spawner.mem_limit` to be available. In supported spawners, you can set `c.Spawner.mem_limit` to
limit the total amount of memory that a single-user notebook server can limit the total amount of memory that a single-user notebook server can
@@ -235,8 +228,8 @@ allocate. Attempting to use more memory than this limit will cause errors. The
single-user notebook server can discover its own memory limit by looking at single-user notebook server can discover its own memory limit by looking at
the environment variable `MEM_LIMIT`, which is specified in absolute bytes. the environment variable `MEM_LIMIT`, which is specified in absolute bytes.
`c.Spawner.mem_guarantee`: Sometimes, a **guarantee** of a *minimum amount of `c.Spawner.mem_guarantee`: Sometimes, a **guarantee** of a _minimum amount of
memory* is desirable. In this case, you can set `c.Spawner.mem_guarantee` to memory_ is desirable. In this case, you can set `c.Spawner.mem_guarantee` to
to provide a guarantee that at minimum this much memory will always be to provide a guarantee that at minimum this much memory will always be
available for the single-user notebook server to use. The environment variable available for the single-user notebook server to use. The environment variable
`MEM_GUARANTEE` will also be set in the single-user notebook server. `MEM_GUARANTEE` will also be set in the single-user notebook server.
@@ -271,7 +264,7 @@ utilize these certs, there are two methods of interest on the base `Spawner`
class: `.create_certs` and `.move_certs`. class: `.create_certs` and `.move_certs`.
The first method, `.create_certs` will sign a key-cert pair using an internally The first method, `.create_certs` will sign a key-cert pair using an internally
trusted authority for notebooks. During this process, `.create_certs` can trusted authority for notebooks. During this process, `.create_certs` can
apply `ip` and `dns` name information to the cert via an `alt_names` `kwarg`. apply `ip` and `dns` name information to the cert via an `alt_names` `kwarg`.
This is used for certificate authentication (verification). Without proper This is used for certificate authentication (verification). Without proper
verification, the `Notebook` will be unable to communicate with the `Hub` and verification, the `Notebook` will be unable to communicate with the `Hub` and

27
docs/source/reference/templates.md
View File

@@ -1,8 +1,8 @@
# Working with templates and UI # Working with templates and UI
The pages of the JupyterHub application are generated from The pages of the JupyterHub application are generated from
[Jinja](http://jinja.pocoo.org/) templates. These allow the header, for [Jinja](http://jinja.pocoo.org/) templates. These allow the header, for
example, to be defined once and incorporated into all pages. By providing example, to be defined once and incorporated into all pages. By providing
your own templates, you can have complete control over JupyterHub's your own templates, you can have complete control over JupyterHub's
appearance. appearance.
@@ -20,7 +20,7 @@ or as few templates as you desire.
Jinja provides a mechanism to [extend templates](http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance). Jinja provides a mechanism to [extend templates](http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance).
A base template can define a `block`, and child templates can replace or A base template can define a `block`, and child templates can replace or
supplement the material in the block. The supplement the material in the block. The
[JupyterHub templates](https://github.com/jupyterhub/jupyterhub/tree/master/share/jupyterhub/templates) [JupyterHub templates](https://github.com/jupyterhub/jupyterhub/tree/master/share/jupyterhub/templates)
make extensive use of blocks, which allows you to customize parts of the make extensive use of blocks, which allows you to customize parts of the
interface easily. interface easily.
@@ -32,8 +32,8 @@ In general, a child template can extend a base template, `page.html`, by beginni
``` ```
This works, unless you are trying to extend the default template for the same This works, unless you are trying to extend the default template for the same
file name. Starting in version 0.9, you may refer to the base file with a file name. Starting in version 0.9, you may refer to the base file with a
`templates/` prefix. Thus, if you are writing a custom `page.html`, start the `templates/` prefix. Thus, if you are writing a custom `page.html`, start the
file with this block: file with this block:
```html ```html
@@ -41,7 +41,7 @@ file with this block:
``` ```
By defining `block`s with same name as in the base template, child templates By defining `block`s with same name as in the base template, child templates
can replace those sections with custom content. The content from the base can replace those sections with custom content. The content from the base
template can be included with the `{{ super() }}` directive. template can be included with the `{{ super() }}` directive.
### Example ### Example
@@ -52,10 +52,7 @@ text about the server starting up, place this content in a file named
`JupyterHub.template_paths` configuration option. `JupyterHub.template_paths` configuration option.
```html ```html
{% extends "templates/spawn_pending.html" %} {% extends "templates/spawn_pending.html" %} {% block message %} {{ super() }}
{% block message %}
{{ super() }}
<p>Patience is a virtue.</p> <p>Patience is a virtue.</p>
{% endblock %} {% endblock %}
``` ```
@@ -69,9 +66,8 @@ To add announcements to be displayed on a page, you have two options:
### Announcement Configuration Variables ### Announcement Configuration Variables
If you set the configuration variable `JupyterHub.template_vars = If you set the configuration variable `JupyterHub.template_vars = {'announcement': 'some_text'}`, the given `some_text` will be placed on
{'announcement': 'some_text'}`, the given `some_text` will be placed on the top of all pages. The more specific variables
the top of all pages. The more specific variables
`announcement_login`, `announcement_spawn`, `announcement_home`, and `announcement_login`, `announcement_spawn`, `announcement_home`, and
`announcement_logout` are more specific and only show on their `announcement_logout` are more specific and only show on their
respective pages (overriding the global `announcement` variable). respective pages (overriding the global `announcement` variable).
@@ -79,13 +75,12 @@ Note that changing these variables require a restart, unlike direct
template extension. template extension.
You can get the same effect by extending templates, which allows you You can get the same effect by extending templates, which allows you
to update the messages without restarting. Set to update the messages without restarting. Set
`c.JupyterHub.template_paths` as mentioned above, and then create a `c.JupyterHub.template_paths` as mentioned above, and then create a
template (for example, `login.html`) with: template (for example, `login.html`) with:
```html ```html
{% extends "templates/login.html" %} {% extends "templates/login.html" %} {% set announcement = 'some message' %}
{% set announcement = 'some message' %}
``` ```
Extending `page.html` puts the message on all pages, but note that Extending `page.html` puts the message on all pages, but note that

20
docs/source/reference/urls.md
View File

@@ -11,8 +11,6 @@ All authenticated handlers redirect to `/hub/login` to login users
prior to being redirected back to the originating page. prior to being redirected back to the originating page.
The returned request should preserve all query parameters. The returned request should preserve all query parameters.
## `/` ## `/`
The top-level request is always a simple redirect to `/hub/`, The top-level request is always a simple redirect to `/hub/`,
@@ -61,7 +59,7 @@ for starting and stopping the user's server.
If named servers are enabled, there will be some additional If named servers are enabled, there will be some additional
tools for management of named servers. tools for management of named servers.
*Version added: 1.0* named server UI is new in 1.0. _Version added: 1.0_ named server UI is new in 1.0.
## `/hub/login` ## `/hub/login`
@@ -111,7 +109,7 @@ not the Hub.
The username is the first part and, if using named servers, The username is the first part and, if using named servers,
the server name is the second part. the server name is the second part.
If the user's server is *not* running, this will be redirected to `/hub/user/:username/...` If the user's server is _not_ running, this will be redirected to `/hub/user/:username/...`
## `/hub/user/:username[/:servername]` ## `/hub/user/:username[/:servername]`
@@ -123,8 +121,8 @@ Handling this URL is the most complicated condition in JupyterHub,
because there can be many states: because there can be many states:
1. server is not active 1. server is not active
a. user matches a. user matches
b. user doesn't match b. user doesn't match
2. server is ready 2. server is ready
3. server is pending, but not ready 3. server is pending, but not ready
@@ -146,7 +144,7 @@ without additional user action (i.e. clicking the link on the page)
![Visiting a URL for a server that's not running](../images/not-running.png) ![Visiting a URL for a server that's not running](../images/not-running.png)
*Version changed: 1.0* _Version changed: 1.0_
Prior to 1.0, this URL itself was responsible for spawning servers, Prior to 1.0, this URL itself was responsible for spawning servers,
and served the progress page if it was pending, and served the progress page if it was pending,
@@ -165,7 +163,7 @@ indicating how to spawn the server.
This is meant to help applications such as JupyterLab This is meant to help applications such as JupyterLab
that are connected to a server that has stopped. that are connected to a server that has stopped.
*Version changed: 1.0* _Version changed: 1.0_
JupyterHub 0.9 failed these API requests with status 404, JupyterHub 0.9 failed these API requests with status 404,
but 1.0 uses 503. but 1.0 uses 503.
@@ -207,12 +205,12 @@ and a POST request will trigger the actual spawn and redirect.
![The spawn form](../images/spawn-form.png) ![The spawn form](../images/spawn-form.png)
*Version added: 1.0* _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. Prior to 1.0, only `/hub/spawn` was recognized for the default server.
*Version changed: 1.0* _Version changed: 1.0_
Prior to 1.0, this page redirected back to `/hub/user/:username`, Prior to 1.0, this page redirected back to `/hub/user/:username`,
which was responsible for triggering spawn and rendering progress, etc. which was responsible for triggering spawn and rendering progress, etc.
@@ -221,7 +219,7 @@ which was responsible for triggering spawn and rendering progress, etc.
![The spawn pending page](../images/spawn-pending.png) ![The spawn pending page](../images/spawn-pending.png)
*Version added: 1.0* this URL is new in JupyterHub 1.0. _Version added: 1.0_ this URL is new in JupyterHub 1.0.
This page renders the progress view for the given spawn request. This page renders the progress view for the given spawn request.
Once the server is ready, Once the server is ready,

19
docs/source/reference/websecurity.md
View File

@@ -12,17 +12,17 @@ works.
## Semi-trusted and untrusted users ## Semi-trusted and untrusted users
JupyterHub is designed to be a *simple multi-user server for modestly sized JupyterHub is designed to be a _simple multi-user server for modestly sized
groups* of **semi-trusted** users. While the design reflects serving semi-trusted groups_ of **semi-trusted** users. While the design reflects serving semi-trusted
users, JupyterHub is not necessarily unsuitable for serving **untrusted** users. users, JupyterHub is not necessarily unsuitable for serving **untrusted** users.
Using JupyterHub with **untrusted** users does mean more work by the Using JupyterHub with **untrusted** users does mean more work by the
administrator. Much care is required to secure a Hub, with extra caution on administrator. Much care is required to secure a Hub, with extra caution on
protecting users from each other as the Hub is serving untrusted users. protecting users from each other as the Hub is serving untrusted users.
One aspect of JupyterHub's *design simplicity* for **semi-trusted** users is that One aspect of JupyterHub's _design simplicity_ for **semi-trusted** users is that
the Hub and single-user servers are placed in a *single domain*, behind a the Hub and single-user servers are placed in a _single domain_, behind a
[*proxy*][configurable-http-proxy]. If the Hub is serving untrusted [_proxy_][configurable-http-proxy]. If the Hub is serving untrusted
users, many of the web's cross-site protections are not applied between users, many of the web's cross-site protections are not applied between
single-user servers and the Hub, or between single-user servers and each single-user servers and the Hub, or between single-user servers and each
other, since browsers see the whole thing (proxy, Hub, and single user other, since browsers see the whole thing (proxy, Hub, and single user
@@ -40,7 +40,7 @@ server.
To protect all users from each other, JupyterHub administrators must To protect all users from each other, JupyterHub administrators must
ensure that: ensure that:
* A user **does not have permission** to modify their single-user notebook server, - A user **does not have permission** to modify their single-user notebook server,
including: including:
- A user **may not** install new packages in the Python environment that runs - A user **may not** install new packages in the Python environment that runs
their single-user server. their single-user server.
@@ -49,11 +49,11 @@ ensure that:
directory that precedes the directory containing `jupyterhub-singleuser`. directory that precedes the directory containing `jupyterhub-singleuser`.
- A user may not modify environment variables (e.g. PATH, PYTHONPATH) for - A user may not modify environment variables (e.g. PATH, PYTHONPATH) for
their single-user server. their single-user server.
* A user **may not** modify the configuration of the notebook server - A user **may not** modify the configuration of the notebook server
(the `~/.jupyter` or `JUPYTER_CONFIG_DIR` directory). (the `~/.jupyter` or `JUPYTER_CONFIG_DIR` directory).
If any additional services are run on the same domain as the Hub, the services If any additional services are run on the same domain as the Hub, the services
**must never** display user-authored HTML that is neither *sanitized* nor *sandboxed* **must never** display user-authored HTML that is neither _sanitized_ nor _sandboxed_
(e.g. IFramed) to any user that lacks authentication as the author of a file. (e.g. IFramed) to any user that lacks authentication as the author of a file.
## Mitigate security issues ## Mitigate security issues
@@ -85,7 +85,7 @@ admin must enforce.
### Prevent spawners from evaluating shell configuration files ### Prevent spawners from evaluating shell configuration files
For most Spawners, `PATH` is not something users can influence, but care should For most Spawners, `PATH` is not something users can influence, but care should
be taken to ensure that the Spawner does *not* evaluate shell configuration be taken to ensure that the Spawner does _not_ evaluate shell configuration
files prior to launching the server. files prior to launching the server.
### Isolate packages using virtualenv ### Isolate packages using virtualenv
@@ -125,7 +125,6 @@ versions up to date.
A handy website for testing your deployment is A handy website for testing your deployment is
[Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html). [Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html).
[configurable-http-proxy]: https://github.com/jupyterhub/configurable-http-proxy [configurable-http-proxy]: https://github.com/jupyterhub/configurable-http-proxy
## Vulnerability reporting ## Vulnerability reporting

48
docs/source/troubleshooting.md
View File

@@ -4,17 +4,20 @@ 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 provide links for identifying the cause of the
problem and how to resolve it. problem and how to resolve it.
[*Behavior*](#behavior) [_Behavior_](#behavior)
- JupyterHub proxy fails to start - JupyterHub proxy fails to start
- sudospawner fails to run - sudospawner fails to run
- What is the default behavior when none of the lists (admin, allowed, - What is the default behavior when none of the lists (admin, allowed,
allowed groups) are set? allowed groups) are set?
- JupyterHub Docker container not accessible at localhost - JupyterHub Docker container not accessible at localhost
[*Errors*](#errors) [_Errors_](#errors)
- 500 error after spawning my single-user server - 500 error after spawning my single-user server
[*How do I...?*](#how-do-i) [_How do I...?_](#how-do-i)
- Use a chained SSL certificate - Use a chained SSL certificate
- Install JupyterHub without a network connection - Install JupyterHub without a network connection
- I want access to the whole filesystem, but still default users to their home directory - I want access to the whole filesystem, but still default users to their home directory
@@ -25,7 +28,7 @@ problem and how to resolve it.
- Toree integration with HDFS rack awareness script - Toree integration with HDFS rack awareness script
- Where do I find Docker images and Dockerfiles related to JupyterHub? - Where do I find Docker images and Dockerfiles related to JupyterHub?
[*Troubleshooting commands*](#troubleshooting-commands) [_Troubleshooting commands_](#troubleshooting-commands)
## Behavior ## Behavior
@@ -34,8 +37,8 @@ problem and how to resolve it.
If you have tried to start the JupyterHub proxy and it fails to start: If you have tried to start the JupyterHub proxy and it fails to start:
- check if the JupyterHub IP configuration setting is - check if the JupyterHub IP configuration setting is
``c.JupyterHub.ip = '*'``; if it is, try ``c.JupyterHub.ip = ''`` `c.JupyterHub.ip = '*'`; if it is, try `c.JupyterHub.ip = ''`
- Try starting with ``jupyterhub --ip=0.0.0.0`` - Try starting with `jupyterhub --ip=0.0.0.0`
**Note**: If this occurs on Ubuntu/Debian, check that the you are using a **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 recent version of node. Some versions of Ubuntu/Debian come with a version
@@ -66,13 +69,13 @@ things like inspect other users' servers, or modify the user list at runtime).
### JupyterHub Docker container not accessible at localhost ### JupyterHub Docker container not accessible at localhost
Even though the command to start your Docker container exposes port 8000 Even though the command to start your Docker container exposes port 8000
(`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`), (`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 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 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 tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this
command: command:
`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000` `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?
@@ -108,7 +111,7 @@ sudo MY_ENV=abc123 \
### How can I view the logs for JupyterHub or the user's Notebook servers when using the DockerSpawner? ### 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: 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 docker logs hub
@@ -132,11 +135,11 @@ There are two likely reasons for this:
1. The single-user server cannot connect to the Hub's API (networking 1. The single-user server cannot connect to the Hub's API (networking
configuration problems) configuration problems)
2. The single-user server cannot *authenticate* its requests (invalid token) 2. The single-user server cannot _authenticate_ its requests (invalid token)
#### Symptoms #### Symptoms
The main symptom is a failure to load *any* page served by the single-user The main symptom is a failure to load _any_ page served by the single-user
server, met with a 500 error. This is typically the first page at `/user/<your_name>` server, met with a 500 error. This is typically the first page at `/user/<your_name>`
after logging in or clicking "Start my server". When a single-user notebook server after logging in or clicking "Start my server". When a single-user notebook server
receives a request, the notebook server makes an API request to the Hub to receives a request, the notebook server makes an API request to the Hub to
@@ -198,15 +201,15 @@ your server again.
##### Proxy settings (403 GET) ##### 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 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`.
### Launching Jupyter Notebooks to run as an externally managed JupyterHub service with the `jupyterhub-singleuser` command returns a `JUPYTERHUB_API_TOKEN` error ### 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: [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. - **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 grading assignments.
* **Private Dashboards**: share dashboards with certain group members. - **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). 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).
@@ -250,7 +253,6 @@ You would then set in your `jupyterhub_config.py` file the `ssl_key` and
c.JupyterHub.ssl_cert = your_host-chained.crt c.JupyterHub.ssl_cert = your_host-chained.crt
c.JupyterHub.ssl_key = your_host.key c.JupyterHub.ssl_key = your_host.key
#### Example #### Example
Your certificate provider gives you the following files: `example_host.crt`, Your certificate provider gives you the following files: `example_host.crt`,
@@ -402,8 +404,8 @@ SyntaxError: Missing parentheses in call to 'print'
In order to resolve this issue, there are two potential options. 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 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 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). 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). 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? ### Where do I find Docker images and Dockerfiles related to JupyterHub?

42
examples/bootstrap-script/README.md
View File

@@ -1,34 +1,34 @@
# Bootstrapping your users # Bootstrapping your users
Before spawning a notebook to the user, it could be useful to Before spawning a notebook to the user, it could be useful to
do some preparation work in a bootstrapping process. do some preparation work in a bootstrapping process.
Common use cases are: Common use cases are:
*Providing writeable storage for LDAP users* _Providing writeable storage for LDAP users_
Your Jupyterhub is configured to use the LDAPAuthenticator and DockerSpawer. Your Jupyterhub is configured to use the LDAPAuthenticator and DockerSpawer.
* The user has no file directory on the host since your are using LDAP. - The user has no file directory on the host since your are using LDAP.
* When a user has no directory and DockerSpawner wants to mount a volume, - When a user has no directory and DockerSpawner wants to mount a volume,
the spawner will use docker to create a directory. the spawner will use docker to create a directory.
Since the docker daemon is running as root, the generated directory for the volume Since the docker daemon is running as root, the generated directory for the volume
mount will not be writeable by the `jovyan` user inside of the container. mount will not be writeable by the `jovyan` user inside of the container.
For the directory to be useful to the user, the permissions on the directory For the directory to be useful to the user, the permissions on the directory
need to be modified for the user to have write access. need to be modified for the user to have write access.
*Prepopulating Content* _Prepopulating Content_
Another use would be to copy initial content, such as tutorial files or reference Another use would be to copy initial content, such as tutorial files or reference
material, into the user's space when a notebook server is newly spawned. material, into the user's space when a notebook server is newly spawned.
You can define your own bootstrap process by implementing a `pre_spawn_hook` on any spawner. You can define your own bootstrap process by implementing a `pre_spawn_hook` on any spawner.
The Spawner itself is passed as parameter to your hook and you can easily get the contextual information out of the spawning process. The Spawner itself is passed as parameter to your hook and you can easily get the contextual information out of the spawning process.
Similarly, there may be cases where you would like to clean up after a spawner stops. Similarly, there may be cases where you would like to clean up after a spawner stops.
You may implement a `post_stop_hook` that is always executed after the spawner stops. You may implement a `post_stop_hook` that is always executed after the spawner stops.
If you implement a hook, make sure that it is *idempotent*. It will be executed every time If you implement a hook, make sure that it is _idempotent_. It will be executed every time
a notebook server is spawned to the user. That means you should somehow a notebook server is spawned to the user. That means you should somehow
ensure that things which should run only once are not running again and again. ensure that things which should run only once are not running again and again.
For example, before you create a directory, check if it exists. For example, before you create a directory, check if it exists.
@@ -41,13 +41,13 @@ Create a directory for the user, if none exists
```python ```python
# in jupyterhub_config.py # in jupyterhub_config.py
import os import os
def create_dir_hook(spawner): def create_dir_hook(spawner):
username = spawner.user.name # get the username username = spawner.user.name # get the username
volume_path = os.path.join('/volumes/jupyterhub', username) volume_path = os.path.join('/volumes/jupyterhub', username)
if not os.path.exists(volume_path): if not os.path.exists(volume_path):
# create a directory with umask 0755 # create a directory with umask 0755
# hub and container user must have the same UID to be writeable # hub and container user must have the same UID to be writeable
# still readable by other users on the system # still readable by other users on the system
os.mkdir(volume_path, 0o755) os.mkdir(volume_path, 0o755)
@@ -83,17 +83,17 @@ in a new file in `/etc/sudoers.d`, or simply in `/etc/sudoers`.
All new home directories will be created from `/etc/skel`, so make sure to place any custom homedir-contents in there. All new home directories will be created from `/etc/skel`, so make sure to place any custom homedir-contents in there.
### Example #3 - Run a shell script ### Example #3 - Run a shell script
You can specify a plain ole' shell script (or any other executable) to be run You can specify a plain ole' shell script (or any other executable) to be run
by the bootstrap process. by the bootstrap process.
For example, you can execute a shell script and as first parameter pass the name For example, you can execute a shell script and as first parameter pass the name
of the user: of the user:
```python ```python
# in jupyterhub_config.py # in jupyterhub_config.py
from subprocess import check_call from subprocess import check_call
import os import os
def my_script_hook(spawner): def my_script_hook(spawner):
@@ -106,7 +106,7 @@ c.Spawner.pre_spawn_hook = my_script_hook
``` ```
Here's an example on what you could do in your shell script. See also Here's an example on what you could do in your shell script. See also
`/examples/bootstrap-script/` `/examples/bootstrap-script/`
```bash ```bash
@@ -126,7 +126,7 @@ fi
# This example script will do the following: # This example script will do the following:
# - create one directory for the user $USER in a BASE_DIRECTORY (see below) # - create one directory for the user $USER in a BASE_DIRECTORY (see below)
# - create a "tutorials" directory within and download and unzip # - create a "tutorials" directory within and download and unzip
# the PythonDataScienceHandbook from GitHub # the PythonDataScienceHandbook from GitHub
# Start the Bootstrap Process # Start the Bootstrap Process

67
examples/external-oauth/README.md
View File

@@ -16,63 +16,62 @@ implementations in other web servers or languages.
## Run the example ## Run the example
1. generate an API token: 1. generate an API token:
export JUPYTERHUB_API_TOKEN=$(openssl rand -hex 32) export JUPYTERHUB_API_TOKEN=$(openssl rand -hex 32)
2. launch a version of the the whoami service. 2. launch a version of the the whoami service.
For `whoami-oauth`: For `whoami-oauth`:
bash launch-service.sh & bash launch-service.sh &
or for `whoami-oauth-basic`: or for `whoami-oauth-basic`:
bash launch-service-basic.sh & bash launch-service-basic.sh &
3. Launch JupyterHub: 3. Launch JupyterHub:
jupyterhub jupyterhub
4. Visit http://127.0.0.1:5555/ 4. Visit http://127.0.0.1:5555/
After logging in with your local-system credentials, you should see a JSON dump of your user info: After logging in with your local-system credentials, you should see a JSON dump of your user info:
```json ```json
{ {
"admin": false, "admin": false,
"last_activity": "2016-05-27T14:05:18.016372", "last_activity": "2016-05-27T14:05:18.016372",
"name": "queequeg", "name": "queequeg",
"pending": null, "pending": null,
"server": "/user/queequeg" "server": "/user/queequeg"
} }
``` ```
The essential pieces for using JupyterHub as an OAuth provider are: The essential pieces for using JupyterHub as an OAuth provider are:
1. registering your service with jupyterhub: 1. registering your service with jupyterhub:
```python ```python
c.JupyterHub.services = [ c.JupyterHub.services = [
{ {
# the name of your service # the name of your service
# should be simple and unique. # should be simple and unique.
# mostly used to identify your service in logging # mostly used to identify your service in logging
"name": "my-service", "name": "my-service",
# the oauth client id of your service # the oauth client id of your service
# must be unique but isn't private # must be unique but isn't private
# can be randomly generated or hand-written # can be randomly generated or hand-written
"oauth_client_id": "abc123", "oauth_client_id": "abc123",
# the API token and client secret of the service # the API token and client secret of the service
# should be generated securely, # should be generated securely,
# e.g. via `openssl rand -hex 32` # e.g. via `openssl rand -hex 32`
"api_token": "abc123...", "api_token": "abc123...",
# the redirect target for jupyterhub to send users # the redirect target for jupyterhub to send users
# after successful authentication # after successful authentication
"oauth_redirect_uri": "https://service-host/oauth_callback" "oauth_redirect_uri": "https://service-host/oauth_callback"
} }
] ]
``` ```
2. Telling your service how to authenticate with JupyterHub. 2. Telling your service how to authenticate with JupyterHub.

16
examples/postgres/README.md
View File

@@ -4,14 +4,14 @@ This example shows how you can connect Jupyterhub to a Postgres database
instead of the default SQLite backend. instead of the default SQLite backend.
### Running Postgres with Jupyterhub on the host. ### Running Postgres with Jupyterhub on the host.
0. Uncomment and replace `ENV JPY_PSQL_PASSWORD arglebargle` with your own 0. Uncomment and replace `ENV JPY_PSQL_PASSWORD arglebargle` with your own
password in the Dockerfile for `examples/postgres/db`. (Alternatively, pass password in the Dockerfile for `examples/postgres/db`. (Alternatively, pass
-e `JPY_PSQL_PASSWORD=<password>` when you start the db container.) -e `JPY_PSQL_PASSWORD=<password>` when you start the db container.)
1. `cd` to the root of your jupyterhub repo. 1. `cd` to the root of your jupyterhub repo.
2. Build the postgres image with `docker build -t jupyterhub-postgres-db 2. Build the postgres image with `docker build -t jupyterhub-postgres-db examples/postgres/db`. This may take a minute or two the first time it's
examples/postgres/db`. This may take a minute or two the first time it's
run. run.
3. Run the db image with `docker run -d -p 5433:5432 jupyterhub-postgres-db`. 3. Run the db image with `docker run -d -p 5433:5432 jupyterhub-postgres-db`.
@@ -24,24 +24,22 @@ instead of the default SQLite backend.
5. Log in as the user running jupyterhub on your host machine. 5. Log in as the user running jupyterhub on your host machine.
### Running Postgres with Containerized Jupyterhub. ### Running Postgres with Containerized Jupyterhub.
0. Do steps 0-2 in from the above section, ensuring that the values set/passed 0. Do steps 0-2 in from the above section, ensuring that the values set/passed
for `JPY_PSQL_PASSWORD` match for the hub and db containers. for `JPY_PSQL_PASSWORD` match for the hub and db containers.
1. Build the hub image with `docker build -t jupyterhub-postgres-hub 1. Build the hub image with `docker build -t jupyterhub-postgres-hub examples/postgres/hub`. This may take a minute or two the first time it's
examples/postgres/hub`. This may take a minute or two the first time it's
run. run.
2. Run the db image with `docker run -d --name=jpy-db 2. Run the db image with `docker run -d --name=jpy-db jupyterhub-postgres`. Note that, unlike when connecting to a host machine
jupyterhub-postgres`. Note that, unlike when connecting to a host machine
jupyterhub, we don't specify a port-forwarding scheme here, but we do need jupyterhub, we don't specify a port-forwarding scheme here, but we do need
to specify a name for the container. to specify a name for the container.
3. Run the containerized hub with `docker run -it --link jpy-db:postgres 3. Run the containerized hub with `docker run -it --link jpy-db:postgres jupyterhub-postgres-hub`. This instructs docker to run the hub container
jupyterhub-postgres-hub`. This instructs docker to run the hub container
with a link to the already-running db container, which will forward with a link to the already-running db container, which will forward
environment and connection information from the DB to the hub. environment and connection information from the DB to the hub.
4. Log in as one of the users defined in the `examples/postgres/hub/` 4. Log in as one of the users defined in the `examples/postgres/hub/`
Dockerfile. By default `rhea` is the server's admin user, `io` and Dockerfile. By default `rhea` is the server's admin user, `io` and
`ganymede` are non-admin users, and all users' passwords are their `ganymede` are non-admin users, and all users' passwords are their
usernames. usernames.

11
examples/service-announcement/README.md
View File

@@ -1,4 +1,3 @@
# Simple Announcement Service Example # Simple Announcement Service Example
This is a simple service that allows administrators to manage announcements This is a simple service that allows administrators to manage announcements
@@ -16,10 +15,10 @@ configuration file something like:
] ]
This starts the announcements service up at `/services/announcement` when This starts the announcements service up at `/services/announcement` when
JupyterHub launches. By default the announcement text is empty. JupyterHub launches. By default the announcement text is empty.
The `announcement` module has a configurable port (default 8888) and an API The `announcement` module has a configurable port (default 8888) and an API
prefix setting. By default the API prefix is `JUPYTERHUB_SERVICE_PREFIX` if prefix setting. By default the API prefix is `JUPYTERHUB_SERVICE_PREFIX` if
that environment variable is set or `/` if it is not. that environment variable is set or `/` if it is not.
## Managing the Announcement ## Managing the Announcement
@@ -42,7 +41,7 @@ Anyone can read the announcement:
The time the announcement was posted is recorded in the `timestamp` field and The time the announcement was posted is recorded in the `timestamp` field and
the user who posted the announcement is recorded in the `user` field. the user who posted the announcement is recorded in the `user` field.
To clear the announcement text, just DELETE. Only admin users can do this. To clear the announcement text, just DELETE. Only admin users can do this.
$ curl -X POST -H "Authorization: token <token>" \ $ curl -X POST -H "Authorization: token <token>" \
https://.../services/announcement https://.../services/announcement
@@ -50,11 +49,11 @@ To clear the announcement text, just DELETE. Only admin users can do this.
## Seeing the Announcement in JupyterHub ## Seeing the Announcement in JupyterHub
To be able to render the announcement, include the provide `page.html` template To be able to render the announcement, include the provide `page.html` template
that extends the base `page.html` template. Set `c.JupyterHub.template_paths` that extends the base `page.html` template. Set `c.JupyterHub.template_paths`
in JupyterHub's configuration to include the path to the extending template. in JupyterHub's configuration to include the path to the extending template.
The template changes the `announcement` element and does a JQuery `$.get()` call The template changes the `announcement` element and does a JQuery `$.get()` call
to retrieve the announcement text. to retrieve the announcement text.
JupyterHub's configurable announcement template variables can be set for various JupyterHub's configurable announcement template variables can be set for various
pages like login, logout, spawn, and home. Including the template provided in pages like login, logout, spawn, and home. Including the template provided in
this example overrides all of those. this example overrides all of those.

15
examples/service-announcement/templates/page.html
View File

@@ -1,14 +1,9 @@
{% extends "templates/page.html" %} {% extends "templates/page.html" %} {% block announcement %}
{% block announcement %} <div class="container text-center announcement"></div>
<div class="container text-center announcement"> {% endblock %} {% block script %} {{ super() }}
</div>
{% endblock %}
{% block script %}
{{ super() }}
<script> <script>
$.get("/services/announcement/", function(data) { $.get("/services/announcement/", function (data) {
$(".announcement").html(data["announcement"]); $(".announcement").html(data["announcement"]);
}); });
</script> </script>
{% endblock %} {% endblock %}

6
examples/service-notebook/README.md
View File

@@ -17,8 +17,8 @@ and the name of the shared-notebook service.
In the external example, some extra steps are required to set up supervisor: In the external example, some extra steps are required to set up supervisor:
1. select a system user to run the service. This is a user on the system, and does not need to be a Hub user. Add this to the user field in `shared-notebook.conf`, replacing `someuser`. 1. select a system user to run the service. This is a user on the system, and does not need to be a Hub user. Add this to the user field in `shared-notebook.conf`, replacing `someuser`.
2. generate a secret token for authentication, and replace the `super-secret` fields in `shared-notebook-service` and `jupyterhub_config.py` 2. generate a secret token for authentication, and replace the `super-secret` fields in `shared-notebook-service` and `jupyterhub_config.py`
3. install `shared-notebook-service` somewhere on your system, and update `/path/to/shared-notebook-service` to the absolute path of this destination 3. install `shared-notebook-service` somewhere on your system, and update `/path/to/shared-notebook-service` to the absolute path of this destination
3. copy `shared-notebook.conf` to `/etc/supervisor/conf.d/` 4. copy `shared-notebook.conf` to `/etc/supervisor/conf.d/`
4. `supervisorctl reload` 5. `supervisorctl reload`

15
examples/service-whoami-flask/README.md
View File

@@ -4,21 +4,21 @@ Uses `jupyterhub.services.HubAuth` to authenticate requests with the Hub in a [f
## Run ## Run
1. Launch JupyterHub and the `whoami service` with 1. Launch JupyterHub and the `whoami service` with
jupyterhub --ip=127.0.0.1 jupyterhub --ip=127.0.0.1
2. Visit http://127.0.0.1:8000/services/whoami/ or http://127.0.0.1:8000/services/whoami-oauth/ 2. Visit http://127.0.0.1:8000/services/whoami/ or http://127.0.0.1:8000/services/whoami-oauth/
After logging in with your local-system credentials, you should see a JSON dump of your user info: After logging in with your local-system credentials, you should see a JSON dump of your user info:
```json ```json
{ {
"admin": false, "admin": false,
"last_activity": "2016-05-27T14:05:18.016372", "last_activity": "2016-05-27T14:05:18.016372",
"name": "queequeg", "name": "queequeg",
"pending": null, "pending": null,
"server": "/user/queequeg" "server": "/user/queequeg"
} }
``` ```
@@ -29,5 +29,4 @@ A similar service could be run externally, by setting the JupyterHub service env
JUPYTERHUB_API_TOKEN JUPYTERHUB_API_TOKEN
JUPYTERHUB_SERVICE_PREFIX JUPYTERHUB_SERVICE_PREFIX
[flask]: http://flask.pocoo.org [flask]: http://flask.pocoo.org

14
examples/service-whoami/README.md
View File

@@ -6,21 +6,21 @@ There is an implementation each of cookie-based `HubAuthenticated` and OAuth-bas
## Run ## Run
1. Launch JupyterHub and the `whoami service` with 1. Launch JupyterHub and the `whoami service` with
jupyterhub --ip=127.0.0.1 jupyterhub --ip=127.0.0.1
2. Visit http://127.0.0.1:8000/services/whoami or http://127.0.0.1:8000/services/whoami-oauth 2. Visit http://127.0.0.1:8000/services/whoami or http://127.0.0.1:8000/services/whoami-oauth
After logging in with your local-system credentials, you should see a JSON dump of your user info: After logging in with your local-system credentials, you should see a JSON dump of your user info:
```json ```json
{ {
"admin": false, "admin": false,
"last_activity": "2016-05-27T14:05:18.016372", "last_activity": "2016-05-27T14:05:18.016372",
"name": "queequeg", "name": "queequeg",
"pending": null, "pending": null,
"server": "/user/queequeg" "server": "/user/queequeg"
} }
``` ```

12
jupyterhub/event-schemas/server-actions/v1.yaml
View File

@@ -19,14 +19,14 @@ description: |
2. Events are only recorded when an action succeeds. 2. Events are only recorded when an action succeeds.
type: object type: object
required: required:
- action - action
- username - username
- servername - servername
properties: properties:
action: action:
enum: enum:
- start - start
- stop - stop
description: | description: |
Action performed by JupyterHub. Action performed by JupyterHub.
@@ -36,7 +36,7 @@ properties:
1. start 1. start
A user's server was successfully started A user's server was successfully started
2. stop 2. stop
A user's server was successfully stopped A user's server was successfully stopped
username: username:

1
readthedocs.yml
View File

@@ -13,7 +13,6 @@ python:
path: . path: .
- requirements: docs/requirements.txt - requirements: docs/requirements.txt
formats: formats:
- htmlzip - htmlzip
- epub - epub

77
share/jupyterhub/static/js/admin.js
View File

@@ -1,7 +1,7 @@
// Copyright (c) Jupyter Development Team. // Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License. // Distributed under the terms of the Modified BSD License.
require(["jquery", "moment", "jhapi", "utils"], function( require(["jquery", "moment", "jhapi", "utils"], function (
$, $,
moment, moment,
JHAPI, JHAPI,
@@ -51,41 +51,41 @@ require(["jquery", "moment", "jhapi", "utils"], function(
window.location = window.location.pathname + "?" + query.join("&"); window.location = window.location.pathname + "?" + query.join("&");
} }
$("th").map(function(i, th) { $("th").map(function (i, th) {
th = $(th); th = $(th);
var col = th.data("sort"); var col = th.data("sort");
if (!col || col.length === 0) { if (!col || col.length === 0) {
return; return;
} }
var order = th.find("i").hasClass("fa-sort-desc") ? "asc" : "desc"; var order = th.find("i").hasClass("fa-sort-desc") ? "asc" : "desc";
th.find("a").click(function() { th.find("a").click(function () {
resort(col, order); resort(col, order);
}); });
}); });
$(".time-col").map(function(i, el) { $(".time-col").map(function (i, el) {
// convert ISO datestamps to nice momentjs ones // convert ISO datestamps to nice momentjs ones
el = $(el); el = $(el);
var m = moment(new Date(el.text().trim())); var m = moment(new Date(el.text().trim()));
el.text(m.isValid() ? m.fromNow() : "Never"); el.text(m.isValid() ? m.fromNow() : "Never");
}); });
$(".stop-server").click(function() { $(".stop-server").click(function () {
var el = $(this); var el = $(this);
var row = getRow(el); var row = getRow(el);
var serverName = row.data("server-name"); var serverName = row.data("server-name");
var user = row.data("user"); var user = row.data("user");
el.text("stopping..."); el.text("stopping...");
var stop = function(options) { var stop = function (options) {
return api.stop_server(user, options); return api.stop_server(user, options);
}; };
if (serverName !== "") { if (serverName !== "") {
stop = function(options) { stop = function (options) {
return api.stop_named_server(user, serverName, options); return api.stop_named_server(user, serverName, options);
}; };
} }
stop({ stop({
success: function() { success: function () {
el.text("stop " + serverName).addClass("hidden"); el.text("stop " + serverName).addClass("hidden");
row.find(".access-server").addClass("hidden"); row.find(".access-server").addClass("hidden");
row.find(".start-server").removeClass("hidden"); row.find(".start-server").removeClass("hidden");
@@ -93,20 +93,20 @@ require(["jquery", "moment", "jhapi", "utils"], function(
}); });
}); });
$(".delete-server").click(function() { $(".delete-server").click(function () {
var el = $(this); var el = $(this);
var row = getRow(el); var row = getRow(el);
var serverName = row.data("server-name"); var serverName = row.data("server-name");
var user = row.data("user"); var user = row.data("user");
el.text("deleting..."); el.text("deleting...");
api.delete_named_server(user, serverName, { api.delete_named_server(user, serverName, {
success: function() { success: function () {
row.remove(); row.remove();
}, },
}); });
}); });
$(".access-server").map(function(i, el) { $(".access-server").map(function (i, el) {
el = $(el); el = $(el);
var row = getRow(el); var row = getRow(el);
var user = row.data("user"); var user = row.data("user");
@@ -120,7 +120,7 @@ require(["jquery", "moment", "jhapi", "utils"], function(
if (admin_access && options_form) { if (admin_access && options_form) {
// if admin access and options form are enabled // if admin access and options form are enabled
// link to spawn page instead of making API requests // link to spawn page instead of making API requests
$(".start-server").map(function(i, el) { $(".start-server").map(function (i, el) {
el = $(el); el = $(el);
var row = getRow(el); var row = getRow(el);
var user = row.data("user"); var user = row.data("user");
@@ -134,22 +134,22 @@ require(["jquery", "moment", "jhapi", "utils"], function(
// since it would mean opening a bunch of tabs // since it would mean opening a bunch of tabs
$("#start-all-servers").addClass("hidden"); $("#start-all-servers").addClass("hidden");
} else { } else {
$(".start-server").click(function() { $(".start-server").click(function () {
var el = $(this); var el = $(this);
var row = getRow(el); var row = getRow(el);
var user = row.data("user"); var user = row.data("user");
var serverName = row.data("server-name"); var serverName = row.data("server-name");
el.text("starting..."); el.text("starting...");
var start = function(options) { var start = function (options) {
return api.start_server(user, options); return api.start_server(user, options);
}; };
if (serverName !== "") { if (serverName !== "") {
start = function(options) { start = function (options) {
return api.start_named_server(user, serverName, options); return api.start_named_server(user, serverName, options);
}; };
} }
start({ start({
success: function() { success: function () {
el.text("start " + serverName).addClass("hidden"); el.text("start " + serverName).addClass("hidden");
row.find(".stop-server").removeClass("hidden"); row.find(".stop-server").removeClass("hidden");
row.find(".access-server").removeClass("hidden"); row.find(".access-server").removeClass("hidden");
@@ -158,7 +158,7 @@ require(["jquery", "moment", "jhapi", "utils"], function(
}); });
} }
$(".edit-user").click(function() { $(".edit-user").click(function () {
var el = $(this); var el = $(this);
var row = getRow(el); var row = getRow(el);
var user = row.data("user"); var user = row.data("user");
@@ -172,7 +172,7 @@ require(["jquery", "moment", "jhapi", "utils"], function(
$("#edit-user-dialog") $("#edit-user-dialog")
.find(".save-button") .find(".save-button")
.click(function() { .click(function () {
var dialog = $("#edit-user-dialog"); var dialog = $("#edit-user-dialog");
var user = dialog.data("user"); var user = dialog.data("user");
var name = dialog.find(".username-input").val(); var name = dialog.find(".username-input").val();
@@ -184,14 +184,14 @@ require(["jquery", "moment", "jhapi", "utils"], function(
name: name, name: name,
}, },
{ {
success: function() { success: function () {
window.location.reload(); window.location.reload();
}, },
} }
); );
}); });
$(".delete-user").click(function() { $(".delete-user").click(function () {
var el = $(this); var el = $(this);
var row = getRow(el); var row = getRow(el);
var user = row.data("user"); var user = row.data("user");
@@ -202,18 +202,18 @@ require(["jquery", "moment", "jhapi", "utils"], function(
$("#delete-user-dialog") $("#delete-user-dialog")
.find(".delete-button") .find(".delete-button")
.click(function() { .click(function () {
var dialog = $("#delete-user-dialog"); var dialog = $("#delete-user-dialog");
var username = dialog.find(".delete-username").text(); var username = dialog.find(".delete-username").text();
console.log("deleting", username); console.log("deleting", username);
api.delete_user(username, { api.delete_user(username, {
success: function() { success: function () {
window.location.reload(); window.location.reload();
}, },
}); });
}); });
$("#add-users").click(function() { $("#add-users").click(function () {
var dialog = $("#add-users-dialog"); var dialog = $("#add-users-dialog");
dialog.find(".username-input").val(""); dialog.find(".username-input").val("");
dialog.find(".admin-checkbox").prop("checked", false); dialog.find(".admin-checkbox").prop("checked", false);
@@ -222,15 +222,12 @@ require(["jquery", "moment", "jhapi", "utils"], function(
$("#add-users-dialog") $("#add-users-dialog")
.find(".save-button") .find(".save-button")
.click(function() { .click(function () {
var dialog = $("#add-users-dialog"); var dialog = $("#add-users-dialog");
var lines = dialog var lines = dialog.find(".username-input").val().split("\n");
.find(".username-input")
.val()
.split("\n");
var admin = dialog.find(".admin-checkbox").prop("checked"); var admin = dialog.find(".admin-checkbox").prop("checked");
var usernames = []; var usernames = [];
lines.map(function(line) { lines.map(function (line) {
var username = line.trim(); var username = line.trim();
if (username.length) { if (username.length) {
usernames.push(username); usernames.push(username);
@@ -241,47 +238,45 @@ require(["jquery", "moment", "jhapi", "utils"], function(
usernames, usernames,
{ admin: admin }, { admin: admin },
{ {
success: function() { success: function () {
window.location.reload(); window.location.reload();
}, },
} }
); );
}); });
$("#stop-all-servers").click(function() { $("#stop-all-servers").click(function () {
$("#stop-all-servers-dialog").modal(); $("#stop-all-servers-dialog").modal();
}); });
$("#start-all-servers").click(function() { $("#start-all-servers").click(function () {
$("#start-all-servers-dialog").modal(); $("#start-all-servers-dialog").modal();
}); });
$("#stop-all-servers-dialog") $("#stop-all-servers-dialog")
.find(".stop-all-button") .find(".stop-all-button")
.click(function() { .click(function () {
// stop all clicks all the active stop buttons // stop all clicks all the active stop buttons
$(".stop-server") $(".stop-server").not(".hidden").click();
.not(".hidden")
.click();
}); });
function start(el) { function start(el) {
return function() { return function () {
$(el).click(); $(el).click();
}; };
} }
$("#start-all-servers-dialog") $("#start-all-servers-dialog")
.find(".start-all-button") .find(".start-all-button")
.click(function() { .click(function () {
$(".start-server") $(".start-server")
.not(".hidden") .not(".hidden")
.each(function(i) { .each(function (i) {
setTimeout(start(this), i * 500); setTimeout(start(this), i * 500);
}); });
}); });
$("#shutdown-hub").click(function() { $("#shutdown-hub").click(function () {
var dialog = $("#shutdown-hub-dialog"); var dialog = $("#shutdown-hub-dialog");
dialog.find("input[type=checkbox]").prop("checked", true); dialog.find("input[type=checkbox]").prop("checked", true);
dialog.modal(); dialog.modal();
@@ -289,7 +284,7 @@ require(["jquery", "moment", "jhapi", "utils"], function(
$("#shutdown-hub-dialog") $("#shutdown-hub-dialog")
.find(".shutdown-button") .find(".shutdown-button")
.click(function() { .click(function () {
var dialog = $("#shutdown-hub-dialog"); var dialog = $("#shutdown-hub-dialog");
var servers = dialog.find(".shutdown-servers-checkbox").prop("checked"); var servers = dialog.find(".shutdown-servers-checkbox").prop("checked");
var proxy = dialog.find(".shutdown-proxy-checkbox").prop("checked"); var proxy = dialog.find(".shutdown-proxy-checkbox").prop("checked");

25
share/jupyterhub/static/js/home.js
View File

@@ -1,11 +1,7 @@
// Copyright (c) Jupyter Development Team. // Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License. // Distributed under the terms of the Modified BSD License.
require(["jquery", "moment", "jhapi"], function( require(["jquery", "moment", "jhapi"], function ($, moment, JHAPI) {
$,
moment,
JHAPI
) {
"use strict"; "use strict";
var base_url = window.jhdata.base_url; var base_url = window.jhdata.base_url;
@@ -22,10 +18,7 @@ require(["jquery", "moment", "jhapi"], function(
} }
function disableRow(row) { function disableRow(row) {
row row.find(".btn").attr("disabled", true).off("click");
.find(".btn")
.attr("disabled", true)
.off("click");
} }
function enableRow(row, running) { function enableRow(row, running) {
@@ -68,7 +61,7 @@ require(["jquery", "moment", "jhapi"], function(
// request // request
api.stop_named_server(user, serverName, { api.stop_named_server(user, serverName, {
success: function() { success: function () {
enableRow(row, false); enableRow(row, false);
}, },
}); });
@@ -83,22 +76,22 @@ require(["jquery", "moment", "jhapi"], function(
// request // request
api.delete_named_server(user, serverName, { api.delete_named_server(user, serverName, {
success: function() { success: function () {
row.remove(); row.remove();
}, },
}); });
} }
// initial state: hook up click events // initial state: hook up click events
$("#stop").click(function() { $("#stop").click(function () {
$("#start") $("#start")
.attr("disabled", true) .attr("disabled", true)
.attr("title", "Your server is stopping") .attr("title", "Your server is stopping")
.click(function() { .click(function () {
return false; return false;
}); });
api.stop_server(user, { api.stop_server(user, {
success: function() { success: function () {
$("#stop").hide(); $("#stop").hide();
$("#start") $("#start")
.text("Start My Server") .text("Start My Server")
@@ -111,7 +104,7 @@ require(["jquery", "moment", "jhapi"], function(
}); });
$(".new-server-btn").click(startServer); $(".new-server-btn").click(startServer);
$(".new-server-name").on('keypress', function(e) { $(".new-server-name").on("keypress", function (e) {
if (e.which === 13) { if (e.which === 13) {
startServer.call(this); startServer.call(this);
} }
@@ -121,7 +114,7 @@ require(["jquery", "moment", "jhapi"], function(
$(".delete-server").click(deleteServer); $(".delete-server").click(deleteServer);
// render timestamps // render timestamps
$(".time-col").map(function(i, el) { $(".time-col").map(function (i, el) {
// convert ISO datestamps to nice momentjs ones // convert ISO datestamps to nice momentjs ones
el = $(el); el = $(el);
var m = moment(new Date(el.text().trim())); var m = moment(new Date(el.text().trim()));

40
share/jupyterhub/static/js/jhapi.js
View File

@@ -1,10 +1,10 @@
// Copyright (c) Jupyter Development Team. // Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License. // Distributed under the terms of the Modified BSD License.
define(["jquery", "utils"], function($, utils) { define(["jquery", "utils"], function ($, utils) {
"use strict"; "use strict";
var JHAPI = function(base_url) { var JHAPI = function (base_url) {
this.base_url = base_url; this.base_url = base_url;
}; };
@@ -18,21 +18,21 @@ define(["jquery", "utils"], function($, utils) {
error: utils.ajax_error_dialog, error: utils.ajax_error_dialog,
}; };
var update = function(d1, d2) { var update = function (d1, d2) {
$.map(d2, function(i, key) { $.map(d2, function (i, key) {
d1[key] = d2[key]; d1[key] = d2[key];
}); });
return d1; return d1;
}; };
var ajax_defaults = function(options) { var ajax_defaults = function (options) {
var d = {}; var d = {};
update(d, default_options); update(d, default_options);
update(d, options); update(d, options);
return d; return d;
}; };
JHAPI.prototype.api_request = function(path, options) { JHAPI.prototype.api_request = function (path, options) {
options = options || {}; options = options || {};
options = ajax_defaults(options || {}); options = ajax_defaults(options || {});
var url = utils.url_path_join( var url = utils.url_path_join(
@@ -43,13 +43,13 @@ define(["jquery", "utils"], function($, utils) {
$.ajax(url, options); $.ajax(url, options);
}; };
JHAPI.prototype.start_server = function(user, options) { JHAPI.prototype.start_server = function (user, options) {
options = options || {}; options = options || {};
options = update(options, { type: "POST", dataType: null }); options = update(options, { type: "POST", dataType: null });
this.api_request(utils.url_path_join("users", user, "server"), options); this.api_request(utils.url_path_join("users", user, "server"), options);
}; };
JHAPI.prototype.start_named_server = function(user, server_name, options) { JHAPI.prototype.start_named_server = function (user, server_name, options) {
options = options || {}; options = options || {};
options = update(options, { type: "POST", dataType: null }); options = update(options, { type: "POST", dataType: null });
this.api_request( this.api_request(
@@ -58,13 +58,13 @@ define(["jquery", "utils"], function($, utils) {
); );
}; };
JHAPI.prototype.stop_server = function(user, options) { JHAPI.prototype.stop_server = function (user, options) {
options = options || {}; options = options || {};
options = update(options, { type: "DELETE", dataType: null }); options = update(options, { type: "DELETE", dataType: null });
this.api_request(utils.url_path_join("users", user, "server"), options); this.api_request(utils.url_path_join("users", user, "server"), options);
}; };
JHAPI.prototype.stop_named_server = function(user, server_name, options) { JHAPI.prototype.stop_named_server = function (user, server_name, options) {
options = options || {}; options = options || {};
options = update(options, { type: "DELETE", dataType: null }); options = update(options, { type: "DELETE", dataType: null });
this.api_request( this.api_request(
@@ -73,21 +73,21 @@ define(["jquery", "utils"], function($, utils) {
); );
}; };
JHAPI.prototype.delete_named_server = function(user, server_name, options) { JHAPI.prototype.delete_named_server = function (user, server_name, options) {
options = options || {}; options = options || {};
options.data = JSON.stringify({ remove: true }); options.data = JSON.stringify({ remove: true });
return this.stop_named_server(user, server_name, options); return this.stop_named_server(user, server_name, options);
}; };
JHAPI.prototype.list_users = function(options) { JHAPI.prototype.list_users = function (options) {
this.api_request("users", options); this.api_request("users", options);
}; };
JHAPI.prototype.get_user = function(user, options) { JHAPI.prototype.get_user = function (user, options) {
this.api_request(utils.url_path_join("users", user), options); this.api_request(utils.url_path_join("users", user), options);
}; };
JHAPI.prototype.add_users = function(usernames, userinfo, options) { JHAPI.prototype.add_users = function (usernames, userinfo, options) {
options = options || {}; options = options || {};
var data = update(userinfo, { usernames: usernames }); var data = update(userinfo, { usernames: usernames });
options = update(options, { options = update(options, {
@@ -99,7 +99,7 @@ define(["jquery", "utils"], function($, utils) {
this.api_request("users", options); this.api_request("users", options);
}; };
JHAPI.prototype.edit_user = function(user, userinfo, options) { JHAPI.prototype.edit_user = function (user, userinfo, options) {
options = options || {}; options = options || {};
options = update(options, { options = update(options, {
type: "PATCH", type: "PATCH",
@@ -110,7 +110,7 @@ define(["jquery", "utils"], function($, utils) {
this.api_request(utils.url_path_join("users", user), options); this.api_request(utils.url_path_join("users", user), options);
}; };
JHAPI.prototype.admin_access = function(user, options) { JHAPI.prototype.admin_access = function (user, options) {
options = options || {}; options = options || {};
options = update(options, { options = update(options, {
type: "POST", type: "POST",
@@ -123,13 +123,13 @@ define(["jquery", "utils"], function($, utils) {
); );
}; };
JHAPI.prototype.delete_user = function(user, options) { JHAPI.prototype.delete_user = function (user, options) {
options = options || {}; options = options || {};
options = update(options, { type: "DELETE", dataType: null }); options = update(options, { type: "DELETE", dataType: null });
this.api_request(utils.url_path_join("users", user), options); this.api_request(utils.url_path_join("users", user), options);
}; };
JHAPI.prototype.request_token = function(user, props, options) { JHAPI.prototype.request_token = function (user, props, options) {
options = options || {}; options = options || {};
options = update(options, { type: "POST" }); options = update(options, { type: "POST" });
if (props) { if (props) {
@@ -138,7 +138,7 @@ define(["jquery", "utils"], function($, utils) {
this.api_request(utils.url_path_join("users", user, "tokens"), options); this.api_request(utils.url_path_join("users", user, "tokens"), options);
}; };
JHAPI.prototype.revoke_token = function(user, token_id, options) { JHAPI.prototype.revoke_token = function (user, token_id, options) {
options = options || {}; options = options || {};
options = update(options, { type: "DELETE" }); options = update(options, { type: "DELETE" });
this.api_request( this.api_request(
@@ -147,7 +147,7 @@ define(["jquery", "utils"], function($, utils) {
); );
}; };
JHAPI.prototype.shutdown_hub = function(data, options) { JHAPI.prototype.shutdown_hub = function (data, options) {
options = options || {}; options = options || {};
options = update(options, { type: "POST" }); options = update(options, { type: "POST" });
if (data) { if (data) {

10
share/jupyterhub/static/js/not_running.js
View File

@@ -1,13 +1,13 @@
// Copyright (c) Jupyter Development Team. // Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License. // Distributed under the terms of the Modified BSD License.
require(["jquery", "utils"], function($, utils) { require(["jquery", "utils"], function ($, utils) {
"use strict"; "use strict";
var hash = utils.parse_url(window.location.href).hash; var hash = utils.parse_url(window.location.href).hash;
if (hash !== undefined && hash !== '') { if (hash !== undefined && hash !== "") {
var el = $("#start"); var el = $("#start");
var current_spawn_url = el.attr("href"); var current_spawn_url = el.attr("href");
el.attr("href", current_spawn_url + hash); el.attr("href", current_spawn_url + hash);
} }
}); });

12
share/jupyterhub/static/js/token.js
View File

@@ -1,21 +1,21 @@
// Copyright (c) Jupyter Development Team. // Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License. // Distributed under the terms of the Modified BSD License.
require(["jquery", "jhapi", "moment"], function($, JHAPI, moment) { require(["jquery", "jhapi", "moment"], function ($, JHAPI, moment) {
"use strict"; "use strict";
var base_url = window.jhdata.base_url; var base_url = window.jhdata.base_url;
var user = window.jhdata.user; var user = window.jhdata.user;
var api = new JHAPI(base_url); var api = new JHAPI(base_url);
$(".time-col").map(function(i, el) { $(".time-col").map(function (i, el) {
// convert ISO datestamps to nice momentjs ones // convert ISO datestamps to nice momentjs ones
el = $(el); el = $(el);
var m = moment(new Date(el.text().trim())); var m = moment(new Date(el.text().trim()));
el.text(m.isValid() ? m.fromNow() : el.text()); el.text(m.isValid() ? m.fromNow() : el.text());
}); });
$("#request-token-form").submit(function() { $("#request-token-form").submit(function () {
var note = $("#token-note").val(); var note = $("#token-note").val();
if (!note.length) { if (!note.length) {
note = "Requested via token page"; note = "Requested via token page";
@@ -24,7 +24,7 @@ require(["jquery", "jhapi", "moment"], function($, JHAPI, moment) {
user, user,
{ note: note }, { note: note },
{ {
success: function(reply) { success: function (reply) {
$("#token-result").text(reply.token); $("#token-result").text(reply.token);
$("#token-area").show(); $("#token-area").show();
}, },
@@ -40,12 +40,12 @@ require(["jquery", "jhapi", "moment"], function($, JHAPI, moment) {
return element; return element;
} }
$(".revoke-token-btn").click(function() { $(".revoke-token-btn").click(function () {
var el = $(this); var el = $(this);
var row = get_token_row(el); var row = get_token_row(el);
el.attr("disabled", true); el.attr("disabled", true);
api.revoke_token(user, row.data("token-id"), { api.revoke_token(user, row.data("token-id"), {
success: function(reply) { success: function (reply) {
row.remove(); row.remove();
}, },
}); });

33
share/jupyterhub/static/js/utils.js
View File

@@ -5,10 +5,10 @@
// Modifications Copyright (c) Jupyter Development Team. // Modifications Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License. // Distributed under the terms of the Modified BSD License.
define(["jquery"], function($) { define(["jquery"], function ($) {
"use strict"; "use strict";
var url_path_join = function() { var url_path_join = function () {
// join a sequence of url components with '/' // join a sequence of url components with '/'
var url = ""; var url = "";
for (var i = 0; i < arguments.length; i++) { for (var i = 0; i < arguments.length; i++) {
@@ -25,7 +25,7 @@ define(["jquery"], function($) {
return url; return url;
}; };
var parse_url = function(url) { var parse_url = function (url) {
// an `a` element with an href allows attr-access to the parsed segments of a URL // an `a` element with an href allows attr-access to the parsed segments of a URL
// a = parse_url("http://localhost:8888/path/name#hash") // a = parse_url("http://localhost:8888/path/name#hash")
// a.protocol = "http:" // a.protocol = "http:"
@@ -39,29 +39,24 @@ define(["jquery"], function($) {
return a; return a;
}; };
var encode_uri_components = function(uri) { var encode_uri_components = function (uri) {
// encode just the components of a multi-segment uri, // encode just the components of a multi-segment uri,
// leaving '/' separators // leaving '/' separators
return uri return uri.split("/").map(encodeURIComponent).join("/");
.split("/")
.map(encodeURIComponent)
.join("/");
}; };
var url_join_encode = function() { var url_join_encode = function () {
// join a sequence of url components with '/', // join a sequence of url components with '/',
// encoding each component with encodeURIComponent // encoding each component with encodeURIComponent
return encode_uri_components(url_path_join.apply(null, arguments)); return encode_uri_components(url_path_join.apply(null, arguments));
}; };
var escape_html = function(text) { var escape_html = function (text) {
// escape text to HTML // escape text to HTML
return $("<div/>") return $("<div/>").text(text).html();
.text(text)
.html();
}; };
var get_body_data = function(key) { var get_body_data = function (key) {
// get a url-encoded item from body.data and decode it // get a url-encoded item from body.data and decode it
// we should never have any encoded URLs anywhere else in code // we should never have any encoded URLs anywhere else in code
// until we are building an actual request // until we are building an actual request
@@ -69,7 +64,7 @@ define(["jquery"], function($) {
}; };
// http://stackoverflow.com/questions/2400935/browser-detection-in-javascript // http://stackoverflow.com/questions/2400935/browser-detection-in-javascript
var browser = (function() { var browser = (function () {
if (typeof navigator === "undefined") { if (typeof navigator === "undefined") {
// navigator undefined in node // navigator undefined in node
return "None"; return "None";
@@ -86,7 +81,7 @@ define(["jquery"], function($) {
})(); })();
// http://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript // http://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript
var platform = (function() { var platform = (function () {
if (typeof navigator === "undefined") { if (typeof navigator === "undefined") {
// navigator undefined in node // navigator undefined in node
return "None"; return "None";
@@ -99,7 +94,7 @@ define(["jquery"], function($) {
return OSName; return OSName;
})(); })();
var ajax_error_msg = function(jqXHR) { var ajax_error_msg = function (jqXHR) {
// Return a JSON error message if there is one, // Return a JSON error message if there is one,
// otherwise the basic HTTP status text. // otherwise the basic HTTP status text.
if (jqXHR.responseJSON && jqXHR.responseJSON.message) { if (jqXHR.responseJSON && jqXHR.responseJSON.message) {
@@ -109,7 +104,7 @@ define(["jquery"], function($) {
} }
}; };
var log_ajax_error = function(jqXHR, status, error) { var log_ajax_error = function (jqXHR, status, error) {
// log ajax failures with informative messages // log ajax failures with informative messages
var msg = "API request failed (" + jqXHR.status + "): "; var msg = "API request failed (" + jqXHR.status + "): ";
console.log(jqXHR); console.log(jqXHR);
@@ -118,7 +113,7 @@ define(["jquery"], function($) {
return msg; return msg;
}; };
var ajax_error_dialog = function(jqXHR, status, error) { var ajax_error_dialog = function (jqXHR, status, error) {
console.log("ajax dialog", arguments); console.log("ajax dialog", arguments);
var msg = log_ajax_error(jqXHR, status, error); var msg = log_ajax_error(jqXHR, status, error);
var dialog = $("#error-dialog"); var dialog = $("#error-dialog");

103
share/jupyterhub/static/less/login.less
View File

@@ -1,59 +1,62 @@
#login-main { #login-main {
display: table; display: table;
height: 80vh; height: 80vh;
& #insecure-login-warning{ & #insecure-login-warning {
.bg-warning(); .bg-warning();
padding:10px; padding: 10px;
} }
.service-login {
text-align: center;
display: table-cell;
vertical-align: middle;
margin: auto auto 20% auto;
}
form { .service-login {
display: table-cell; text-align: center;
vertical-align: middle; display: table-cell;
margin: auto auto 20% auto; vertical-align: middle;
width: 350px; margin: auto auto 20% auto;
font-size: large; }
}
.input-group, input[type=text], button { form {
width: 100%; display: table-cell;
} vertical-align: middle;
margin: auto auto 20% auto;
width: 350px;
font-size: large;
}
input[type=submit] { .input-group,
margin-top: 0px; input[type="text"],
} button {
width: 100%;
.form-control:focus, input[type=submit]:focus { }
box-shadow: inset 0 1px 1px rgba(0,0,0,.075), 0 0 8px @jupyter-orange;
border-color: @jupyter-orange;
outline-color: @jupyter-orange;
}
.login_error { input[type="submit"] {
color: orangered; margin-top: 0px;
font-weight: bold; }
text-align: center;
}
.auth-form-header { .form-control:focus,
padding: 10px 20px; input[type="submit"]:focus {
color: #fff; box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075), 0 0 8px @jupyter-orange;
background: @jupyter-orange; border-color: @jupyter-orange;
border-radius: @border-radius-large @border-radius-large 0 0; outline-color: @jupyter-orange;
} }
.auth-form-body { .login_error {
padding: 20px; color: orangered;
font-size: 14px; font-weight: bold;
border: thin silver solid; text-align: center;
border-top: none; }
border-radius: 0 0 @border-radius-large @border-radius-large;
} .auth-form-header {
padding: 10px 20px;
color: #fff;
background: @jupyter-orange;
border-radius: @border-radius-large @border-radius-large 0 0;
}
.auth-form-body {
padding: 20px;
font-size: 14px;
border: thin silver solid;
border-top: none;
border-radius: 0 0 @border-radius-large @border-radius-large;
}
} }

22
share/jupyterhub/static/less/page.less
View File

@@ -49,18 +49,16 @@
// background: rgba(66, 165, 245, 0.2); // background: rgba(66, 165, 245, 0.2);
// } // }
.feedback { .feedback {
&-container { &-container {
margin-top: 16px; margin-top: 16px;
}
&-widget {
padding: 5px 0px 0px 6px;
i {
font-size: 2em;
color: lightgrey;
} }
}
&-widget {
padding: 5px 0px 0px 6px;
i {
font-size: 2em;
color: lightgrey;
}
}
} }

2
share/jupyterhub/static/less/style.less
View File

@@ -12,7 +12,7 @@
* *
*/ */
@import "../components/font-awesome/less/font-awesome.less"; @import "../components/font-awesome/less/font-awesome.less";
@fa-font-path: "../components/font-awesome/fonts"; @fa-font-path: "../components/font-awesome/fonts";
/*! /*!
* *

4
share/jupyterhub/static/less/variables.less
View File

@@ -4,8 +4,8 @@
@navbar-height: 40px; @navbar-height: 40px;
@grid-float-breakpoint: @screen-xs-min; @grid-float-breakpoint: @screen-xs-min;
@jupyter-orange: #F37524; @jupyter-orange: #f37524;
@jupyter-red: #E34F21; @jupyter-red: #e34f21;
// color blind-friendly alternative to red/green // color blind-friendly alternative to red/green
// from 5-class RdYlBu via colorbrewer.org // from 5-class RdYlBu via colorbrewer.org
// eliminate distinction between 'primary' and 'success' // eliminate distinction between 'primary' and 'success'

2
singleuser/README.md
View File

@@ -31,6 +31,6 @@ This particular image runs as the `jovyan` user, with home directory at `/home/j
## Note on persistence ## Note on persistence
This home directory, `/home/jovyan`, is *not* persistent by default, This home directory, `/home/jovyan`, is _not_ persistent by default,
so some configuration is required unless the directory is to be used so some configuration is required unless the directory is to be used
with temporary or demonstration JupyterHub deployments. with temporary or demonstration JupyterHub deployments.