mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
3a9c631526
While doing https://github.com/jupyterhub/jupyterhub/pull/2726, I realized we don't have a consistent way to format references inside the docs. I now have them be formatted to match the name of the file, but using `:` to separate them instead of `/` or `-`. `/` makes it ambiguous when using with markdown link syntax, as it could be a reference or a file. And using `-` is ambiguous, as that can be the name of the file itself. This PR does about half, I can do the other half later (unless someone else does).
86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
(howto:config:gh-oauth)=
|
|
|
|
# Configure GitHub OAuth
|
|
|
|
In this example, we show a configuration file for a fairly standard JupyterHub
|
|
deployment with the following assumptions:
|
|
|
|
- Running JupyterHub on a single cloud server
|
|
- Using SSL on the standard HTTPS port 443
|
|
- Using GitHub OAuth (using [OAuthenticator](https://oauthenticator.readthedocs.io/en/latest)) for login
|
|
- Using the default spawner (to configure other spawners, uncomment and edit
|
|
`spawner_class` as well as follow the instructions for your desired spawner)
|
|
- Users exist locally on the server
|
|
- Users' notebooks to be served from `~/assignments` to allow users to browse
|
|
for notebooks within other users' home directories
|
|
- You want the landing page for each user to be a `Welcome.ipynb` notebook in
|
|
their assignments directory
|
|
- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`
|
|
|
|
The `jupyterhub_config.py` file would have these settings:
|
|
|
|
```python
|
|
# jupyterhub_config.py file
|
|
c = get_config()
|
|
|
|
import os
|
|
pjoin = os.path.join
|
|
|
|
runtime_dir = os.path.join('/srv/jupyterhub')
|
|
ssl_dir = pjoin(runtime_dir, 'ssl')
|
|
if not os.path.exists(ssl_dir):
|
|
os.makedirs(ssl_dir)
|
|
|
|
# Allows multiple single-server per user
|
|
c.JupyterHub.allow_named_servers = True
|
|
|
|
# https on :443
|
|
c.JupyterHub.port = 443
|
|
c.JupyterHub.ssl_key = pjoin(ssl_dir, 'ssl.key')
|
|
c.JupyterHub.ssl_cert = pjoin(ssl_dir, 'ssl.cert')
|
|
|
|
# put the JupyterHub cookie secret and state db
|
|
# in /var/run/jupyterhub
|
|
c.JupyterHub.cookie_secret_file = pjoin(runtime_dir, 'cookie_secret')
|
|
c.JupyterHub.db_url = pjoin(runtime_dir, 'jupyterhub.sqlite')
|
|
# or `--db=/path/to/jupyterhub.sqlite` on the command-line
|
|
|
|
# use GitHub OAuthenticator for local users
|
|
c.JupyterHub.authenticator_class = 'oauthenticator.LocalGitHubOAuthenticator'
|
|
c.GitHubOAuthenticator.oauth_callback_url = os.environ['OAUTH_CALLBACK_URL']
|
|
|
|
# create system users that don't exist yet
|
|
c.LocalAuthenticator.create_system_users = True
|
|
|
|
# specify users and admin
|
|
c.Authenticator.allowed_users = {'rgbkrk', 'minrk', 'jhamrick'}
|
|
c.Authenticator.admin_users = {'jhamrick', 'rgbkrk'}
|
|
|
|
# uses the default spawner
|
|
# To use a different spawner, uncomment `spawner_class` and set to desired
|
|
# spawner (e.g. SudoSpawner). Follow instructions for desired spawner
|
|
# configuration.
|
|
# c.JupyterHub.spawner_class = 'sudospawner.SudoSpawner'
|
|
|
|
# start single-user notebook servers in ~/assignments,
|
|
# with ~/assignments/Welcome.ipynb as the default landing page
|
|
# this config could also be put in
|
|
# /etc/jupyter/jupyter_notebook_config.py
|
|
c.Spawner.notebook_dir = '~/assignments'
|
|
c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
|
|
```
|
|
|
|
Using the GitHub Authenticator requires a few additional
|
|
environment variables to be set prior to launching JupyterHub:
|
|
|
|
```bash
|
|
export GITHUB_CLIENT_ID=github_id
|
|
export GITHUB_CLIENT_SECRET=github_secret
|
|
export OAUTH_CALLBACK_URL=https://example.com/hub/oauth_callback
|
|
export CONFIGPROXY_AUTH_TOKEN=super-secret
|
|
# append log output to log file /var/log/jupyterhub.log
|
|
jupyterhub -f /etc/jupyterhub/jupyterhub_config.py &>> /var/log/jupyterhub.log
|
|
```
|
|
|
|
Visit the [Github OAuthenticator reference](https://oauthenticator.readthedocs.io/en/latest/api/gen/oauthenticator.github.html) to see the full list of options for configuring Github OAuth with JupyterHub.
|