# binder-build > A Binder module that constructs Docker images from requirements files and optionally pushes them to a registry Latest version **1.0.13** (published 2016-07-22) · MIT license · 0 weekly downloads ## Install ```sh npm install binder-build pnpm add binder-build yarn add binder-build bun add binder-build ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.0.13 | | Published | 2016-07-22 | | First published | 2016-03-30 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 20 | | Known vulnerabilities | 0 (+27 in 5 direct dependencies) | | Install scripts | yes | | GitHub stars | 3 | | Author | Andrew Osheroff | | Maintainers | andrewosh | | Keywords | binder, module, binder-build | ## Links - npm: https://www.npmjs.com/package/binder-build - Repository: https://github.com/binder-project/binder-build - Issues: https://github.com/binder-project/binder-build/issues - npm.io page: https://npm.io/package/binder-build ## Dependencies (20) - [tar](https://npm.io/package/tar.md) ^2.2.1 - [tmp](https://npm.io/package/tmp.md) 0.0.28 - [async](https://npm.io/package/async.md) ^1.4.2 - [lodash](https://npm.io/package/lodash.md) ^4.3.0 - [rimraf](https://npm.io/package/rimraf.md) ^2.5.3 - [request](https://npm.io/package/request.md) ^2.67.0 - [shelljs](https://npm.io/package/shelljs.md) ^0.5.3 - [fs-extra](https://npm.io/package/fs-extra.md) ^0.24.0 - [inherits](https://npm.io/package/inherits.md) ^2.0.1 - [mongoose](https://npm.io/package/mongoose.md) ^4.4.6 - [url-join](https://npm.io/package/url-join.md) 0.0.1 - [binder-db](https://npm.io/package/binder-db.md) ^1.0.0 - [commander](https://npm.io/package/commander.md) ^2.9.0 - [jsonschema](https://npm.io/package/jsonschema.md) ~1.0.2 - [binder-utils](https://npm.io/package/binder-utils.md) ^1.0.0 - [gunzip-maybe](https://npm.io/package/gunzip-maybe.md) ^1.3.1 - [binder-module](https://npm.io/package/binder-module.md) ^1.0.1 - [string-format](https://npm.io/package/string-format.md) ^0.5.0 - [binder-logging](https://npm.io/package/binder-logging.md) ^1.0.0 - [binder-build-core](https://npm.io/package/binder-build-core.md) ^1.0.1 ## Recent versions - 1.0.13 (latest) — 2016-07-22 - 1.0.11 — 2016-07-19 - 1.0.10 — 2016-06-20 - 1.0.9 — 2016-06-17 - 1.0.8 — 2016-06-03 - 1.0.7 — 2016-06-03 - 1.0.6 — 2016-05-11 - 1.0.5 — 2016-04-21 - 1.0.3 — 2016-03-30 - 1.0.2 — 2016-03-30 - 1.0.1 — 2016-03-30 - 1.0.0 — 2016-03-30 ## README # binder-build Build Binder images from repositories ## building an image from a repository `binder-build` implements the `build` section of the Binder API defined in [the Binder protocol](http://github.com/binder-project/binder-protocol/blob/master/index.js). 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): 1. `requirements.txt` 2. `environment.yml` 3. `Dockerfile` 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`](lib/sources). ## constructing a template from an image 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. ### install The simplest way to run the `binder-build` server is through the [`binder-control`](https://github.com/binder-project/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= --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 git@github.com:binder-project/binder-build cd binder-build npm i && npm start ``` In standalone mode, the configuration will be loaded from `conf/main.json` ### api `binder-build` exposes both the `build` and `registry` portions of the Binder API, which are composed of the following endpoints: #### build ----------------------------- 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" } ``` #### registry ------------------------------- 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": [] } ``` --------------------------------------------- ## usage The best way to interact with the build server is through the [`binder-client`](http://github.com/binder-project/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(, function (err, status) { ... }) ``` From the CLI ``` binder build status --api-key= --host= --port= ``` --- _Source: https://npm.io/package/binder-build · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._