How to customize a JupyterHub and BinderHub landing pages

[jmunroe]

For http://agu-binder.2i2c.cloud, we want a customized landing page. The configuration for that hub includes the following:

binderhub:
  config:
    BinderHub:
      template_path: /etc/binderhub/custom/templates
      extra_static_path: /etc/binderhub/custom/static
      extra_static_url_prefix: /extra_static/
  initContainers:
    - name: git-clone-templates
      image: alpine/git
      args:
        - clone
        - --single-branch
        - --branch=master
        - --depth=1
        - --
        - https://github.com/2i2c-org/agu-binder-custom-templates
        - /etc/binderhub/custom
      securityContext:
        runAsUser: 0
      volumeMounts:
        - name: custom-templates
          mountPath: /etc/binderhub/custom
  extraVolumes:
    - name: custom-templates
      emptyDir: {}
  extraVolumeMounts:
    - name: custom-templates
      mountPath: /etc/binderhub/custom

My expectation is that by pushing changes to https://github.com/2i2c-org/agu-binder-custom-templates that should cause a change to the landing page visible at http://agu-binder.2i2c.cloud.

I assume I need to do something with deployer to trigger the appropriate helm action so cause that the template repo to be cloned again so that this hub picks up the changes and visible at http://agu-binder.2i2c.cloud.

Trying

deployer deploy 2i2c agu-binder

causes a helm upgrade

helm upgrade --install --create-namespace --wait --namespace=agu-binder agu-binder /home/jmunroe/2i2c-org/infrastructure/helm-charts/binderhub --values=/home/jmunroe/2i2c-org/infrastructure/config/clusters/2i2c/agu-binder.values.yaml --values=/tmp/tmpldq4skso

but apparently no change to http://agu-binder.2i2c.cloud. I assume this because there has been no change to the helm charts so nothing needs to be modified.

Question: how can can trigger helm to rebuild this pod so that the changes made in https://github.com/2i2c-org/agu-binder-custom-templates get picked up?

[yuvipanda]

Great question, @jmunroe! I think for our hubs' home page customization, in addition to the initcontainer, we have another container that 'syncs' changes every 5-10 minutes. That's missing here, and I'll add that today.

[yuvipanda]

In the meantime, deleting the pod should trigger a rescync. That can be done with:

# Get credentials setup for kubectl to work
deployer use-cluster-credentials 2i2c  
# Delete the binder pod, which will cause k8s to recreate it 
k --namespace agu-binder delete pod -l component=binder 

[jmunroe]

Thanks! I've made an initial pass at applying 2i2c-branding to the landing page.

Some of the "skills" required in customizing a landing page for Binderhub/JupyterHub:

• (community task) CSS/HTML experience
• (community task) knowledge about Jinja2 templating
• (community task) setting up binderhub/jupyterhub locally to be able to develop changes to the templates pages
• (2i2c task) update relevant helm charts and/or k8s to be able to deploy a changes to the infrastructure

Web dev can be "easy" if all of the tooling is already set up but can be daunting for the newcomer. Example: the binderhub template references a dist/styles.css file which isn't a single stylesheet from the binderhub code base but a generated artifact from webpack used in deploying binderhub.

Customization of landing pages (for either JupyterHub and BinderHub) could be something that our communities can be empowered to do.

Future action: develop sufficient documentation to make this possible/reasonable.

[yuvipanda]

As a feature, this is tracked in https://2i2c.productboard.com/feature-board/7803674-product-ideas/features/26289139/detail