Deploy authenticated static websites along the hub
Deploy authenticated static websites along the hub#
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
You can enable this with the following config in the
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
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.
staticWebsite.ingress.path should not have a trailing slash.
Here’s a sample that hosts the data8 textbook under
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
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 keybutton. 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.yamlfile 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_filesfor the hub in the cluster’s
cluster.yamlso 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 are set appropriately, and do a deployment
to pull in the private repo!