|
|
|
@ -3,6 +3,14 @@
|
|
|
|
|
Example of running [JupyterHub](https://github.com/jupyter/jupyterhub)
|
|
|
|
|
with [GitHub OAuth](https://developer.github.com/v3/oauth/) for authentication.
|
|
|
|
|
|
|
|
|
|
By default, this image uses `oauthenticator.GitHub`, but you can use a different class by setting `OAUTH_CLASS` in your environment.
|
|
|
|
|
Other configuration parameters, including specific values for your oauth class, can be configured via environment variables.
|
|
|
|
|
For convenience, we include instructions for GITLAB and GITHUB below.
|
|
|
|
|
|
|
|
|
|
This image uses `DockerSpawner` to launch user servers.
|
|
|
|
|
The result is that each user gets their own isolated container in the server, using the docker image specified in the config.
|
|
|
|
|
For other options (e.g. Kubernetes or local), check out: https://github.com/jupyterhub/jupyterhub#spawners
|
|
|
|
|
|
|
|
|
|
## Variables
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@ -14,7 +22,7 @@ OAUTH_CALLBACK_URL=http://hub.cluster.gsi.dit.upm.es/hub/oauth_callback
|
|
|
|
|
HOST_HOMEDIR=/mnt/home/{username} # {username} will be replaced by the actual OAuth user
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Gitlab variables:
|
|
|
|
|
### Git lab variables:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
GITLAB_HOST=https://lab.cluster.gsi.dit.upm.es/
|
|
|
|
@ -25,7 +33,7 @@ DATASETS_DIR=/home/datasets # READ ONLY
|
|
|
|
|
COMMON_DIR=/home/common # To share files between users
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## GitHub variables:
|
|
|
|
|
### GitHub variables:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
GITHUB_CLIENT_ID=GHId
|
|
|
|
@ -33,7 +41,33 @@ GITHUB_CLIENT_SECRET=GHSecret
|
|
|
|
|
OAUTH_CLASS=oauthenticator.github.GitHubOAuthenticator
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## build
|
|
|
|
|
|
|
|
|
|
## Docker-compose
|
|
|
|
|
|
|
|
|
|
This repository includes a docker-compose file to automate building and running the image.
|
|
|
|
|
To use it, save your environment variables to `.env`.
|
|
|
|
|
|
|
|
|
|
Then, just build the image and run an instance with a single command:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
docker-compose run --build
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Docker-swarm
|
|
|
|
|
|
|
|
|
|
DockerSpawner works with the old docker-swarm standalone mode, just by mounting your swarm socket to `/var/run/docker.sock`. e.g.:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
-v "/var/run/swarm.sock:/var/run/docker.sock"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If you are using the new swarm mode in docker, you might want to check out this issue: https://github.com/jupyterhub/dockerspawner/issues/215
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Manual instructions
|
|
|
|
|
### Build
|
|
|
|
|
|
|
|
|
|
Build the container with:
|
|
|
|
|
|
|
|
|
@ -43,12 +77,7 @@ Alternatively:
|
|
|
|
|
|
|
|
|
|
docker build -t gsiupm/jupyter-oauth:testing .
|
|
|
|
|
|
|
|
|
|
### ssl
|
|
|
|
|
|
|
|
|
|
To run the server on HTTPS, put your ssl key and cert in ssl/ssl.key and
|
|
|
|
|
ssl/ssl.cert.
|
|
|
|
|
|
|
|
|
|
## run
|
|
|
|
|
### Run
|
|
|
|
|
|
|
|
|
|
Add your oauth client id, client secret, and callback URL to your `env file` (i.e. `.env`).
|
|
|
|
|
Once you have built the container, you can run it with:
|
|
|
|
@ -60,3 +89,31 @@ Alternatively:
|
|
|
|
|
docker run -it -p 8000:8000 --env-file=env gsiupm/jupyter-oauth:testing
|
|
|
|
|
|
|
|
|
|
Which will run the Jupyter server.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### SSL
|
|
|
|
|
|
|
|
|
|
To run the server on HTTPS, put your ssl key and cert in ssl/ssl.key and
|
|
|
|
|
ssl/ssl.cert.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Useful tweaks
|
|
|
|
|
|
|
|
|
|
You can add resource limits, e.g.:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
c.Spawner.mem_limit = '10G'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Known issues
|
|
|
|
|
|
|
|
|
|
If you recreate the jupyterhub image, the token for the jupyterhub server will change, and it may have trouble connecting to user containers.
|
|
|
|
|
We've tried setting the token manually in the config, but it did not work.
|
|
|
|
|
|
|
|
|
|
As a workaround, you could remove the containers and access them again:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
docker ps -a | grep 'jupyter-' | cut -d' ' -f1 | xargs docker rm
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Unfortunately, **all unsaved work will be lost**
|
|
|
|
|