📚 Same functionality. Better performance for you. 📚

Over the past few months, we've been improving Binder's architecture and infrastructure. We're retiring this repo as it will no longer be actively developed. Future development will occur under the JupyterHub organization.

• All development of the Binder technology will occur in the binderhub repo
• Documentation for users will occur in the jupyterhub binder repo
• All conversations and chat for users will occur in the jupyterhub binder gitter channel

Thanks for updating your bookmarked links.

A binder-deploy implementation that launches containers on a Kubernetes cluster

The deploy API defines how Binder templates can be launched on any container management system. In our production environment, all templates are launched on a Kubernetes cluster using this module.

By default, containers are transient and are culled after one hour of inactivity.

When containers are first deployed (through POSTing to /applications/<template name>), they are assigned an id but not a location. Once the location has been assigned (generally 5-10s after the container has been scheduled), the client can redirect to that location. After the initial deployment command, the location can be determined by polling the /applications/<template name>/<id> endpoint.

The simplest way to run the binder-build server is through the binder-control module, which manages the server's lifecycle and service (the database and logging system) dependencies. Additionally, binder-control uses the PM2 process manager to monitor/restart the server in the event of failures. In binder-control, the deploy server can be started with with custom configuration parameters through

binder-control deploy-kubernetes start --api-key=<key> --config=/path/to/config

It will also be started with reasonable defaults through

binder-control start-all

If you'd prefer to use binder-build in standalone mode:

git clone [email protected]:binder-project/binder-deploy-kubernetes
cd binder-deploy-kubernetes
npm i && npm start

The deploy portion of the Binder API consists of the following endpoints:

Get the status of a single deployed template with a given ID

GET /applications/binder-project-example-requirements/84b8f9e8d573e73016fa2c14bad86a4d HTTP 1.1

returns

{
  "id": "84b8f9e8d573e73016fa2c14bad86a4d",
  "template-name": "binder-project-example-requirements",
  "location": "104.197.56.211/user/84b8f9e8d573e73016fa2c14bad86a4d",
  "status": "deleted"
}

Get the status of all deployed templates for a template name

GET /applications/binder-project-example-requirements HTTP 1.1
Authorization: 880df8bbabdf4b48f412208938c220fe

returns

[
  {
    "id": "74156d847a6bc8e07c64a43aaed53514",
    "template-name": "binder-project-example-requirements",
    "location": "104.197.56.211/user/74156d847a6bc8e07c64a43aaed53514",
    "status": "deleted"
  },
  ...
  {
    "id": "880aa1c3798c32ad6fc120267e3ae610",
    "template-name": "binder-project-example-requirements",
    "location": "104.197.56.211/user/880aa1c3798c32ad6fc120267e3ae610",
    "status": "deleted"
  }
]

Launch a new instance of a template

POST /applications/binder-project-example-requirements
Content-Type: application/json

returns

{
  "id": "a16653059942e2ef2b1c7b458d6a2463"
}

The best way to interact with the deploy server is through the binder-client. Once the client has been installed, all endpoints are accessible either programmatically or through the CLI. For example:

From JS

var binder = require('binder-client')
binder.deploy.status(<deployment options>, function (err, status) {
  ...
})

From the CLI

binder deploy status <image-name> --api-key=<key> --host=<host> --port=<port>