Skip to content
Automatically deploy a BinderHub to Google Cloud!
Shell Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
Dockerfile
LICENSE
README.md
config-template.yaml
deploy.sh
info.sh
logs.sh
secret-template.yaml
setup.sh
teardown.sh
template-config.json
upgrade.sh

README.md

Automatically deploy a BinderHub to Google Cloud

mit_license_badge

BinderHub is a cloud-based, multi-server technology used for hosting repoducible computing environments and interactive Jupyter Notebooks built from code repositories.

This repo contains a set of scripts to automatically deploy a BinderHub onto Google Cloud, and connect a DockerHub container registry, so that you can host your own Binder service.

This repo is based on the following set of deployment scripts for Google Cloud: nicain/binder-deploy

Table of Contents


Usage

This repo can be run locally, by pulling and executing the container image, or as "Platform as a Service" through the "Cloud Run" button in the "Cloud Run" Button section.

To use these scripts locally, clone this repo and change into the directory.

git clone https://github.com/alan-turing-institute/binderhub-deploy-gke.git
cd binderhub-deploy-gke

To make the scripts executable and then run them, do the following:

chmod 700 <script-name>.sh
./<script-name>.sh

[NOTE: The above command is UNIX specific. If you are running Windows 10, this blog post discusses using a bash shell in Windows.]

To build the BinderHub, you should run setup.sh first (to install the required command line tools), then deploy.sh (which will build the BinderHub). Once the BinderHub is deployed, you can run logs.sh and info.sh to get the JupyterHub logs and IP addresses respectively. teardown.sh should only be used to delete your BinderHub deployment.

You need to create a file called config.json which has the format described in the code block below. Fill the quotation marks with your desired namespaces, etc. config.json is git-ignored so sensitive information, such as passwords, cannot not be pushed to GitHub.

  • For a list of available data centre zones, see here.
  • For a list of available Linux Virtual Machines, see here.
  • The versions of the BinderHub Helm Chart can be found here and are of the form 0.2.0-<commit-hash>. It is advised to select the most recent version unless you specifically require an older one.
{
  "gcloud": {
    "project": "",            // Google Cloud project
    "zone": "",               // Zone to deploy resources to
    "node_count": 1,          // Number of nodes to deploy
    "machine_type": "",       // Type of machine to deploy
    "service_account": null,  // Google Cloud Service Account
    "key_file": null          // Path to key file for Service log in
  },
  "binderhub": {
    "name": "",               // Name of your BinderHub
    "version": "",            // Helm chart version to deploy, should be 0.2.0-<commit-hash>
    "contact_email": ""       // Email for letsencrypt https certificate. CANNOT be left blank.
  },
  "docker": {
    "username": null,         // Docker username (can be supplied at runtime)
    "password": null,         // Docker password (can be supplied at runtime)
    "org": null,              // A DockerHub organisation to push images to (optional)
    "image_prefix": ""        // The prefix to preprend to Docker images (e.g. "binder-prod")
  }
}

You can copy template-config.json should you require.

Please note that all entries in template-config.json must be surrounded by double quotation marks ("), with the exception of node_count.

setup.sh

This script checks whether the required command line tools are already installed. If any are missing, the script uses the system package manager or curl to install the command line interfaces (CLIs). The CLIs to be installed are:

Any dependencies that are not automatically installed by these packages will also be installed.

deploy.sh

This script reads in values from config.json and deploys a Kubernetes cluster. It then creates config.yaml and secret.yaml files, respectively, using config-template.yaml and secret-template.yaml.

The script will ask for your Docker ID and password if you haven't supplied them in the config file. The ID is your Docker username, NOT the associated email. If you have provided a Docker organisation in config.json, then Docker ID MUST be a member of this organisation.

Both a JupyterHub and BinderHub are installed via a Helm Chart onto the deployed Kubernetes cluster and the config.yaml file is updated with the JupyterHub IP address. The BinderHub is then linked to the provided DockerHub account to store the created images.

config.yaml and secret.yaml are both git-ignored so that secrets cannot be pushed back to GitHub.

The script also outputs log files (<file-name>.log) for each stage of the deployment. These files are also git-ignored.

logs.sh

This script will print the JupyterHub logs to the terminal to assist with debugging issues with the BinderHub. It reads from config.json in order to get the BinderHub name.

info.sh

This script will print the pod status of the Kubernetes cluster and the IP addresses of both the JupyterHub and BinderHub to the terminal. It reads the BinderHub name from config.json.

upgrade.sh

This script will automatically upgrade the Helm Chart deployment configuring the BinderHub and then prints the Kubernetes pods. It reads the BinderHub name and Helm Chart version from config.json.

teardown.sh

This script will purge the Helm Chart release, delete the Kubernetes namespace and then delete the Google Cloud cluster. It will read the namespaces from config.json. The user should check the Google Cloud Console to verify the resources have been deleted.

Customising your BinderHub Deployment

Customising your BinderHub deployment is as simple as editing config.yaml and/or secret.yaml and then upgrading the BinderHub Helm Chart. The Helm Chart can be upgraded by running upgrade.sh (make sure you have the CLIs installed by running setup.sh first).

The Jupyter guide to customising the underlying JupyterHub can be found here.

The BinderHub guide for changing the landing page logo can be found here.

Contributors

We would like to acknowledge and thank the following people for their contributions to this project:

You can’t perform that action at this time.