Home

Awesome

Box: A Next-Generation Builder for Docker Images

Build Status Join the chat at https://gitter.im/box-builder/Lobby 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.

<p align="center"><img src="https://raw.githubusercontent.com/box-builder/box/master/docs-theme/img/box-logo.png"></img></p>

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"
end

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 \
    https://storage.googleapis.com/golang/go#{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:

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 https://github.com/box-builder/box/releases/download/v0.4.2/box_0.4.2_amd64.deb"
  tag :downloaded
end

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

And more!

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

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):

Box REPL

Install

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