💨 💨 The Binder Project is moving to a new repo. 💨 💨
📚 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.
💨 💨 The Binder Project is moving to a new repo. 💨 💨
Build Binder images from repositories
binder-build implements the build section of the Binder API defined in the Binder
protocol.
The build server is responsible for converting the contents of GitHub repositories, or other
sources, into Binder-compatible Docker images and associated runtime information (such as resource
limits and hardware requirements). To do this, binder-build will search for configuration files in
the repository and will select the most appropriate file to build from based on this prioritization
(listed below in descending order; see (TODO: link) for complete descriptions of all configuration files):
requirements.txtenvironment.ymlDockerfile
Once an image has been constructed from the repo contents, it can optionally be pushed to a Docker repository so that it will be accessible from any deployment backends. In our production environment, all images are pushed to the Google Container Registry.
The list of accepted image sources (currently only GitHub) can be extended by adding a handler to
lib/sources.
Docker images do not necessarily contain enough information about a Binder's runtime environment to properly it onto a container management system. As one example, resource limits and/or hardware constraints (such as a GPU requirement), need to be stored as additional metadata. With Binder, we construct a template from an image name and this auxilliary information, and we consider this to a fully-deployable environment specification.
Templates are automatically constructed with reasonable defaults when a build is started. The template API
provides an interface for fetching all templates available for deployment, as well as for fetching a single template.
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. In
binder-control, the build server can be started with with custom configuration parameters through
binder-control build 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-build
cd binder-build
npm i && npm start
In standalone mode, the configuration will be loaded from conf/main.json
binder-build exposes both the build and registry portions of the Binder API, which are
composed of the following endpoints:
Start a new build
POST /builds/repo HTTP 1.1
Content-Type: application/json
Authorization: 880df8bbabdf4b48f412208938c220fe
{
"repository": "https://github.com/binder-project/example-requirements"
}
returns
{
"name": "binder-project-example-requirements",
"repo": "https://github.com/binder-project/example-requirements",
"phase": "fetching",
"status": "running",
"start-time": "2016-03-25T05:42:47.315Z"
}
Get the status of all builds
GET /builds/ HTTP 1.1
Authorization: 880df8bbabdf4b48f412208938c220fe
returns
[
{
"name": "binder-project-example-requirements",
"start-time": "2016-03-25T05:42:47.315Z",
"status": "completed",
"phase": "finished",
"repository": "http://github.com/binder-project/example-requirements"
},
...
{
"name": "binder-project-example-dockerfile",
"start-time": "2016-03-25T03:48:29.635Z",
"status": "completed",
"phase": "finished",
"repository": "http://github.com/binder-project/example-dockerfile"
}
]
Get the status of a single build
GET /builds/binder-project-example-requirements HTTP 1.1
returns
{
"name": "binder-project-example-requirements",
"start-time": "2016-03-25T05:42:47.315Z",
"status": "completed",
"phase": "finished",
"repository": "http://github.com/binder-project/example-requirements"
}
Get all templates
GET /templates/ HTTP 1.1
Authorization: 880df8bbabdf4b48f412208938c220fe
returns
[
{
"port": 8888,
"image-source": "gcr.io/binder-testing/binder-project-example-requirements",
"name": "binder-project-example-requirements",
"image-name": "binder-project-example-requirements",
"command": [],
"time-modified": "2016-03-28T18:55:54.631Z",
"time-created": "2016-03-28T18:55:54.631Z",
"services": []
},
{
"port": 8888,
"image-source": "gcr.io/binder-testing/binder-project-example-dockerfile",
"name": "binder-project-example-dockerfile",
"image-name": "binder-project-example-dockerfile",
"command": [],
"time-modified": "2016-03-28T18:55:54.632Z",
"time-created": "2016-03-28T18:55:54.632Z",
"services": []
}
]
Get a single template
GET /templates/binder-project-example-requirements HTTP 1.1
returns
{
"port": 8888,
"image-source": "gcr.io/binder-testing/binder-project-example-dockerfile",
"name": "binder-project-example-dockerfile",
"image-name": "binder-project-example-dockerfile",
"command": [],
"time-modified": "2016-03-28T18:55:54.632Z",
"time-created": "2016-03-28T18:55:54.632Z",
"services": []
}
The best way to interact with the build 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.build.status(<build options>, function (err, status) {
...
})
From the CLI
binder build status <image-name> --api-key=<key> --host=<host> --port=<port>