1. Create your cloud resources

BinderHub is built to run on top of Kubernetes, a distributed cluster manager. It uses a JupyterHub to launch/manage user servers, as well as a docker registry to cache images.

To create your own BinderHub, you’ll first need to set up a properly configured Kubernetes Cluster on the cloud, and then configure the various components correctly. The following instructions will assist you in doing so.

1.1. Setting up Kubernetes on Google Cloud

Note

BinderHub is built to be cloud agnostic, and can run on various cloud providers (as well as bare metal). However, here we only provide instructions for Google Cloud as it has been the most extensively-tested. If you would like to help with adding instructions for other cloud providers, please contact us!

1.2. Install Helm

Helm, the package manager for Kubernetes, is a useful tool to install, upgrade and manage applications on a Kubernetes cluster. We will be using Helm to install and manage JupyterHub on our cluster.

Helm works by initializing itself both locally (on your computer) and remotely (on your kubernetes cluster). When you run helm commands, your local helm client sends instructions to the Tiller, which exists on your Kubernetes cluster, and is controlled by the server-side helm install.

1.2.1. Installation

The simplest way to install helm is to run Helm’s installer script at a terminal:

curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash

Alternative methods for helm installation exist if you prefer to install without using the script.

1.2.2. Initialization

After installing helm on your machine, initialize helm on your Kubernetes cluster. At a terminal for your local machine (or within an interactive cloud shell from your provider), enter:

  1. Set up a ServiceAccount for use by Tiller, the server side component of helm.

    kubectl --namespace kube-system create serviceaccount tiller
    

    Azure AKS: If you’re on Azure AKS, you should now skip directly to step 3.**

  2. Give the ServiceAccount RBAC full permissions to manage the cluster.

    While most clusters have RBAC enabled and you need this line, you must skip this step if your kubernetes cluster does not have RBAC enabled (for example, if you are using Azure AKS).

    kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount=kube-system:tiller
    
  3. Set up Helm on the cluster.

    helm init --service-account tiller
    

This command only needs to run once per Kubernetes cluster.

Note

The local and remote version of helm must be the same in order to ensure they can talk to each other. If you wish to run helm commands from a new computer than the one used to run the commands above, you must re-initialize it by running the following modified version of the init command:

helm init --client-only --service-account tiller

This will initialize helm locally, according to the version that is running remotely on the cluster. Note that this requires kubectl to point to the correct kubernetes cluster. See the kubernetes context manager for more details.

1.2.3. Verify

You can verify that you have the correct version and that it installed properly by running:

helm version

It should provide output like:

Client: &version.Version{SemVer:"v2.8.1", GitCommit:"46d9ea82e2c925186e1fc620a8320ce1314cbb02", GitTreeState:"clean"}
Server: &version.Version{SemVer:"v2.8.1", GitCommit:"46d9ea82e2c925186e1fc620a8320ce1314cbb02", GitTreeState:"clean"}

Make sure you have at least version 2.8.1!

If you receive an error that the Server is unreachable, do another helm version in 15-30 seconds, and it should display the Server version.

1.2.4. Secure Helm

Ensure that tiller is secure from access inside the cluster:

kubectl --namespace=kube-system patch deployment tiller-deploy --type=json --patch='[{"op": "add", "path": "/spec/template/spec/containers/0/command", "value": ["/tiller", "--listen=localhost:44134"]}]'

Now that you’ve installed Kubernetes and Helm, it’s time to Set up the container registry.