You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Erik Hollensbe 79d8303e43
Merge pull request #266 from erikh/1.9.2
3 years ago
builder builder/command/verbs.go: initialize label map 3 years ago
cli-tests builder,cli-tests: var_exists() function. 3 years ago
copy copy: integration of 3 years ago
docs docs: fixups and var usage. 3 years ago
docs-theme docs-theme: Fix z-index for search 3 years ago
fetcher builder,fetcher,layers: fix cmd/entrypoint semantics 3 years ago
image image: remove a FIXME that is no longer necessary 3 years ago
layers builder,fetcher,layers: fix cmd/entrypoint semantics 3 years ago
logger Command interpreter integration with evaluator 3 years ago
multi fetcher: always fetch the :latest tag if none specified 3 years ago
pull pull: restore pull progress when tty is enabled 3 years ago
release s/erikh/box-builder/g 3 years ago
repl builder,repl,main.go: var support 3 years ago
signal builder,layers,signal: Fix repl by passing Image context each statement 3 years ago
tar builder,tar: fix a number of issues with the copy statement 3 years ago
types types,builder,main.go: --force-color and --no-color modes! 3 years ago
util util,builder: refactor utils packages into a unified one for broader re-use 3 years ago
vendor vendor: associated vendoring updates 3 years ago
.boxignore build.rb,.gitignore: generate box-builder oci images. 3 years ago
.gitignore Theme style changed; logo added. 3 years ago version 0.5.7 3 years ago
LICENSE.txt LICENSE.txt: rename the license file 3 years ago
Makefile Makefile: add a task to update 3 years ago center README image 3 years ago
box.rb box.rb: move to 1.9.2 for new builds 3 years ago re-enable deadcode now that containers/image is gone 3 years ago
dind Dockerfile,Makefile: add Docker in Docker 4 years ago Makefile,build.rb,release: Convert to static build, move away from OS X 3 years ago version 0.5.7 3 years ago s/erikh/box-builder/g 3 years ago
main.go builder,repl,main.go: var support 3 years ago
mkdocs.yml docs: Add download page 3 years ago
mruby_config.rb Makefile,mruby_config.rb: tighten controls regarding mruby installation/compilation. 4 years ago yet again, another fix 3 years ago
vendor.conf vendor.conf,vendor: adjust deps for containers/image removal 3 years ago

Box: A Next-Generation Builder for Docker Images

Build Status Join the chat at Go Report Card

Box is a builder for docker that gives you the power of mruby, a limited, embeddable ruby. It allows for notions of conditionals, loops, and data structures for use within your builder plan. If you’ve written a Dockerfile before, writing a box build plan is easy.

Box Build Plans are Programs

Exploit this! Use functions! Set variables and constants!

run this plan with:

GOLANG_VERSION=1.7.5 box <plan file>
from "ubuntu"

# this function will create a new layer running the command inside the
# function, installing the required package.
def install_package(pkg)
  run "apt-get install '#{pkg}' -y"

run "apt-get update"
install_package "curl" # `run "apt-get install curl -y"`

# get the local environment's setting for GOLANG_VERSION, and set it here:
go_version = getenv("GOLANG_VERSION")
run %Q[curl -sSL \{go_version}.linux-amd64.tar.gz \
    | tar -xvz -C /usr/local]

Powered by mruby

Box uses the mruby programming language. It does this to get a solid language syntax, functions, variables and more. However, it is not a fully featured Ruby such as MRI and contains almost zero standard library functionality, allowing for only the basic types, and no I/O operations outside of the box DSL are permitted.

You can however:

  • Define classes, functions, variables and constants
  • Access the environment through the getenv box function (which is also omittable if you don’t want people to use it)
  • Retrieve the contents of container files with read
  • import libraries (also written in mruby) to re-use common build plan components.

Tagging and Image Editing

You can tag images mid-plan to create multiple images, each subsets (or supersets, depending on how you look at it) of each other.

Additionally, you can use functions like after, skip, and flatten to manipulate images in ways you may not have considered:

from :ubuntu
skip do
  run "apt-get update"
  run "apt-get install curl -y"
  run "curl -sSL -O"
  tag :downloaded

run "dpkg -i box*.deb"
after do
  tag :installed

And more!

All the standard docker build commands such as user, env, and a few new ones:

  • with_user and inside temporarily scope commands to a specific user or working directory respectively, allowing you to avoid nasty patterns like cd foo && thing.
  • debug drop-in statement: drops you to a container in the middle of a build where you place the call.

REPL (Shell)

REPL is short for “read eval print loop” and is just a fancy way of saying this thing has readline support and a shell history. Check the thing out by invoking box repl or box shell.

Here’s a video of the shell in action (click for more):



Using the Homebrew Tap

brew tap box-builder/box && brew install box-builder/box/box

Advanced Use

The documentation is the best resource for learning the different verbs and functions. However, check out our own build plan for box for an example of how to use different predicates, functions, and verbs to get everything you need out of it.

Development Instructions

  • Requires: compiler, bison, flex, and libgpgme, libdevmapper, btrfs headers.
  • go get -d && cd $GOPATH/src/
  • To build on the host (create a dev environment):
    • make
  • To build a docker image for your dev environment (needed for test and release builds):
    • make build
  • If you have a dev environment:
    • make test
  • To do a release build:
    • VERSION=<version> make release