2. 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.

2.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!

Google Container Engine (confusingly abbreviated to GKE) is the simplest and most common way of setting up a Kubernetes Cluster. You may be able to receive free credits for trying it out. You will need to connect your credit card or other payment method to your google cloud account.

  1. Go to https://console.cloud.google.com and log in.

  2. Enable the Container Engine API.

  3. Use Google Cloud Shell (Google documentation) which will give you access to the gcloud command-line tool.

    Note

    Alternatively, advanced users may wish to install the gcloud command-line tool in the Google Cloud SDK. These tools send commands to Google Cloud and lets you do things like create and delete clusters.

  4. Install kubectl, which is a tool for controlling kubernetes. From Google Cloud shell (or a terminal for advanced users who have installed gcloud using the SDK), enter:

    gcloud components install kubectl
    
  5. Create a Kubernetes cluster on Google Cloud, by typing in the following command:

    gcloud container clusters create <YOUR_CLUSTER> \
        --num-nodes=3 \
        --machine-type=n1-standard-2 \
        --zone=us-central1-b
    

    where:

    • --num-nodes specifies how many computers to spin up. The higher the number, the greater the cost.
    • --machine-type specifies the amount of CPU and RAM in each node. There is a variety of types to choose from. Picking something appropriate here will have a large effect on how much you pay - smaller machines restrict the max amount of RAM each user can have access to but allow more fine-grained scaling, reducing cost. The default (n1-standard-2) has 2CPUs and 7.5G of RAM each, and might not be a good fit for all use cases!
    • --zone specifies which data center to use. Pick something that is not too far away from your users. You can find a list of them here.
  6. To test if your cluster is initialized, run:

    kubectl get node
    

    The response should list three running nodes.

Next we’ll install a few tools that are required for BinderHub to run properly.

2.2. Installing Helm

Next, we’ll install Helm. This allows us to control our Kubernetes cluster with a configuration file (called a Helm Chart). By using a Helm Chart, we can set up the cluster deployment to have the resources necessary for running BinderHub.

Run the following commands to download and install helm:

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

2.3. Set up the container registry

BinderHub will build Docker images out of GitHub repositories, and then push them to a docker registry so that JupyterHub can launch user servers based on these images.You can use any registry that you like, though this guide covers how to properly configure the Google Container Registry (gcr.io).

You need to provide BinderHub with proper credentials so it can push images to the Google Container Registry. You can do so by creating a service account that has authorization to push to Google Container Registry:

  1. Go to console.cloud.google.com
  2. Make sure your project is selected
  3. Click <top-left menu w/ three horizontal bars> -> IAM & Admin -> Service Accounts menu option
  4. Click Create service account
  5. Give your account a descriptive name such as “BinderHub-registry”
  6. Click Role -> Storage -> Storage Admin menu option
  7. Check Furnish new private key
  8. Leave key type as default of JSON
  9. Click Create

These steps will download a JSON file to your computer. The JSON file contains the password that can be used to push Docker images to the gcr.io registry.

Warning

Don’t share the contents of this JSON file with anyone. It can be used to gain access to your google cloud account!

Important

Make sure to store this JSON file as you cannot generate a second one without re-doing the steps above.

Now that our cloud resources are set up, it’s time to Set up BinderHub.