Connect with a JupyterHub installation#

The next steps describe how to connect the binderhub-service installation to a JupyterHub set up via z2jh. While any JupyterHub that can run containers will work with this, the most common setup is to use this with z2jh.

The first few steps are lifted directly from the install JupyterHub section of z2jh.

Add the z2jh chart repository to helm:

helm repo add jupyterhub https://hub.jupyter.org/helm-chart/
helm repo update

We want the binderhub to be available under http://{{hub url}}/services/binder, because that is what jupyterhub-fancy-profiles expects. Eventually we would also want authentication to work correctly. For that, we must set up binderhub as a JupyterHub Service. This provides two things:

a. Routing from {{hub url }}/services/{{ service name }} to the service, allowing us to expose the service to the external world using JupyterHub’s ingress / loadbalancer, without needing a dedicated ingress / loadbalancer for BinderHub.

b. (Eventually) Appropriate credentials for authenticated network calls between these two services.

To make this connection, we need to tell JupyterHub where to find BinderHub. Eventually this can be automatic (once this issue gets resolved). In the meantime, you can get the name of the BinderHub service by executing the following command:
```
kubectl -n <namespace> get svc -l app.kubernetes.io/name=binderhub-service
```
Make a note of the name under the NAME column, we will use it in the next step.

Create a config file, z2jh-config.yaml, to hold the config values for the JupyterHub.

hub:
  services:
    binder:
      # FIXME: ref https://github.com/2i2c-org/binderhub-service/issues/57
      # for something more readable and requiring less copy-pasting
      url: http://{{ service name from step 2}}

Find the latest version of the z2jh helm chart. The easiest way is to run the following command:
```
helm search repo jupyterhub
```
This should output a few columns. Look for the version under CHART VERSION (not APP VERSION) for jupyterhub/jupyterhub. That’s the latest z2jh chart version, and that is what we will be using.
Install the JupyterHub helm chart with the following command:
```
helm upgrade --cleanup-on-fail \
   --install <helm-release-name> jupyterhub/jupyterhub \
   --namespace <namespace> \
   --version=<chart-version> \
   --values z2jh-config.yaml \
   --wait
```
where:
- <helm-release-name> is any name you can use to refer to this image (like jupyterhub)
- <namespace> is the same namespace used for the BinderHub install
- <chart-version> is the latest stable version of the JupyterHub helm chart, determined in the previous step.
Find the external IP on which the JupyterHub is accessible:
```
kubectl -n <namespace> get svc proxy-public
```
Access the binder service by going to http://{{ external ip from step 5}}/services/binder/ (the trailing slash is important). You should see an unstyled, somewhat broken 404 page. This is great and expected. Let’s fix that.
Change BinderHub config in binderhub-service-config.yaml, telling BinderHub it should now be available under /services/binder.
```
config:
  BinderHub:
    base_url: /services/binder
```
Deploy this using the helm upgrade command from step 9 in the previous section.
Test by going to http://{{ external ip from step 5}}/services/binder/ (the trailing slash is important!) again, and you should see a styled 404 page! Success - this means BinderHub is now connected to JupyterHub, even if the end users can’t see it yet. Let’s connect them!