provisioners/docker: build images using new DSL

plugins/provisioners/docker/client.rb

@@ -7,6 +7,15 @@ module VagrantPlugins
         @machine = machine
       end
 
+      def build_images(images)
+        @machine.communicate.tap do |comm|
+          images.each do |path, opts|
+            @machine.ui.info(I18n.t("vagrant.docker_building_single", path: path))
+            comm.sudo("docker build #{image[:args]} #{path}")
+          end
+        end
+      end
+
       def pull_images(*images)
         @machine.communicate.tap do |comm|
           images.each do |image|
@@ -16,16 +25,6 @@ module VagrantPlugins
         end
       end
 
-      def build_images(images)
-        @machine.communicate.tap do |comm|
-          images.each do |image|
-            path = image[:path]
-            @machine.ui.info(I18n.t("vagrant.docker_building_single", path: path))
-            comm.sudo("docker build #{image[:args]} #{path}")
-          end
-        end
-      end
-
       def start_service
         if !daemon_running? && @machine.guest.capability?(:docker_start_service)
           @machine.guest.capability(:docker_start_service)

plugins/provisioners/docker/config.rb

@@ -3,7 +3,7 @@ require 'set'
 module VagrantPlugins
   module Docker
     class Config < Vagrant.plugin("2", :config)
-      attr_reader :images, :containers, :build_options
+      attr_reader :build_images, :images, :containers, :build_options
       attr_accessor :version
 
       def initialize
@@ -13,6 +13,14 @@ module VagrantPlugins
         @build_images   = []
       end
 
+      # Defines an image to build using `docker build` within the machine.
+      #
+      # @param [String] path Path to the Dockerfile to pass to
+      #   `docker build`.
+      def build_image(path, **opts)
+        @build_images << [path, opts]
+      end
+
       def images=(images)
         @images = Set.new(images)
       end
@@ -21,12 +29,6 @@ module VagrantPlugins
         @images += images.map(&:to_s)
       end
 
-      def build_images(*images)
-        @build_images = images.map do |image|
-          image.values_at(:path, :args)
-        end
-      end
-
       def run(name, **options)
         params = options.dup
         params[:image] ||= name

plugins/provisioners/docker/provisioner.rb

@@ -7,8 +7,6 @@ module VagrantPlugins
       error_namespace("vagrant.provisioners.docker")
     end
 
-    # TODO: Improve handling of vagrant-lxc specifics (like checking for apparmor
-    #       profile stuff + autocorrection)
     class Provisioner < Vagrant.plugin("2", :provisioner)
       def initialize(machine, config, installer = nil, client = nil)
         super(machine, config)

test/unit/plugins/provisioners/docker/config_test.rb

@@ -5,6 +5,17 @@ require Vagrant.source_root.join("plugins/provisioners/docker/config")
 describe VagrantPlugins::Docker::Config do
   subject { described_class.new }
 
+  describe "#build_image" do
+    it "stores them" do
+      subject.build_image("foo")
+      subject.build_image("bar", foo: :bar)
+      subject.finalize!
+      expect(subject.build_images.length).to eql(2)
+      expect(subject.build_images[0]).to eql(["foo", {}])
+      expect(subject.build_images[1]).to eql(["bar", { foo: :bar }])
+    end
+  end
+
   describe "#images" do
     it "stores them in a set" do
       subject.images = ["1", "1", "2"]

website/docs/source/v2/provisioning/docker.html.md

@@ -36,6 +36,40 @@ for you (if it isn't already installed).
 * `version` (string) - The version of Docker to install. This defaults to
   "latest" and will install the latest version of Docker.
 
+In addition to the options that can be set, various functions are available
+and can be called to configure other aspects of the Docker provisioner. Most
+of these functions have examples in more detailed sections below.
+
+* `build_image` - Build an image from a Dockerfile.
+
+* `pull_images` - Pull the given images. This does not start these images.
+
+* `run` - Run a container and configure it to start on boot.
+
+## Building Images
+
+The provisioner can automatically build images. Images are built prior to
+any configured containers to run, so you can build an image before running it.
+Building an image is easy:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "docker" do |d|
+    d.build_image "/vagrant/app"
+  end
+end
+```
+
+The argument to build an image is the path to give to `docker build`. This
+must be a path that exists within the guest machine. If you need to get data
+to the guest machine, use a synced folder.
+
+The `build_image` function accepts options as a second parameter. Here
+are the available options:
+
+* `args` (string) - Additional arguments to pass to `docker build`. Use this
+  to pass in things like `-t "foo"` to tag the image.
+
 ## Pulling Images
 
 The docker provisioner can automatically pull images from the