Deploy authenticated static websites along the hub#
Warning
This feature is currently broken. Tracked in this issue.
We can deploy authenticated static websites on the same domain as the hub
that is only accessible to users who have access to the hub. The source
for these come from git repositories that should contain rendered HTML,
and will be updated every 5 minutes. They can be under any prefix on the
same domain as the hub (such as /docs
, /textbook
, etc).
You can enable this with the following config in the .values.yaml
file for your hub.
dex:
# Enable authentication
enabled: true
hubHostName: <hostname-of-hub>
staticWebsite:
enabled: true
source:
git:
repo: <url-of-git-repo>
branch: <name-of-git-branch>
ingress:
host: <hostname-of-hub>
path: <absolute-path-where-content-is-available>
jupyterhub:
hub:
services:
dex:
url: http://dex:5556
oauth_redirect_url: https://<hostname-of-hub>/services/dex/callback
oauth_no_confirm: true
display: false
oauth2-proxy:
display: false
url: http://dex:9000
Note
We manually configure the hub services instead of autogenerating them in our deploy scripts. This leads to some additional copy-pasting and duplication, but keeps our config explicit and simple.
Note
staticWebsite.ingress.path
should not have a trailing slash.
Example#
Here’s a sample that hosts the data8 textbook under https://staging.2i2c.cloud/textbook
:
dex:
enabled: true
hubHostName: staging.2i2c.cloud
staticWebsite:
enabled: true
source:
git:
repo: https://github.com/inferentialthinking/inferentialthinking.github.io
branch: master
ingress:
host: staging.2i2c.cloud
path: /textbook
jupyterhub:
hub:
services:
dex:
url: http://dex:5556
oauth_redirect_uri: https://staging.2i2c.cloud/services/dex/callback
oauth_no_confirm: true
oauth2-proxy:
url: http://dex:9000
This clones the repo,
checks out the master
branch and keeps it up to date by doing a
git pull
every 5 minutes. It is made available under /textbook
,
and requires users be logged-in to the hub before they can access it.
Using private GitHub repos#
We use git-credentials-helper to support pulling content from private repos.
Setup GitHub app#
git-credentials-helper
uses a GitHub App
to pull private repos. So you first need to create a GitHub app for each hub that wants
to pull private repos as static content.
Create a GitHub app in the 2i2c org.
Give it a descriptive name (such as ‘
static site deploy authenticator’) and description, as users will see this when authorizing access to their private repos. Disable webhooks (uncheck the ‘Active’ checkbox under ‘Webhooks’). All other textboxes can be left empty.
Under ‘Repository permissions’, select ‘Read’ for ‘Contents’.
Under ‘Where can this GitHub App be installed?’, select ‘Any account’. This will enable users to push to their own user repositories or other organization repositories, rather than just the 2i2c repos.
Create the application with the ‘Create GitHub app’ button.
Copy the numeric ‘App id’ from the app info page you should be redirected to.
Create a new private key for authentication use with the
Generate a private key
button. This should download a private key file, that you should keep safe.
Helm values configuration#
Now, we can configure our static files server to make use of the GitHub app to authenticate.
Enable the gitHub app in the
.values.yaml
file for the hub.staticWebsite: gitHubAuth: enabled: true
Create a sops-encrypted file (usually in the form of
enc-<hub-name>.secret.values.yaml
) to hold the secret values required to authenticate the GitHub app.staticWebsite: githubAuth: githubApp: id: <id-of-the-app> privateKey: | <contents-of-private-key-file>
Make sure this file is also listed under
helm_chart_values_files
for the hub in the cluster’scluster.yaml
so it is read during deployment.
Grant access to the private repo#
Finally, someone with admin rights on the private repo to be pulled needs to grant the github app we just setup access to the private repo. This is the only part that hub admins rather than 2i2c engineers need to do.
Go to the ‘Public page’ of the GitHub app created. This usually is of the form
https://github.com/apps/<name-of-app>
. You can find this in the information page of the app after you create it, under ‘Public link’Install the app in the organization the private repo is in, and grant it access only to the repo that needs to be pulled.
Do a deploy#
After all the permissions are setup, you should make sure the config under
staticWebsite.source.git.repo
and staticWebsite.source.git.repo
are set appropriately, and do a deployment
to pull in the private repo!