dry-dock 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5de350e13158e99318eabbb68b7d507804cb0c9c
-  data.tar.gz: df476fedf7609cf0734aa92aaae0ab71235aa2df
+  metadata.gz: 5f2e43155c83ad0b25eb7ee30a1da32697c0b270
+  data.tar.gz: fe24886ba40a3d093989f2c03f0068026698dcdf
 SHA512:
-  metadata.gz: 562e59af24727a8d9a23a2e8a677386b70a5bcadd48969af33a0c595c3c5592d68bd90cf72cc913a111bf4c27127ac03e051ce01aa114aa4d7db1e5189522183
-  data.tar.gz: f5807ebf5764c81c1fdef2e9c7650fc0e57f97608e305c586a18dcfe04fb46ef9a450d4c00085c1be94f181c1353df0da1719a4bf7f141d1f1e2bd23a4e64ba6
+  metadata.gz: daf3a6b9aea72c10fb072740f97c2682df12f6378d88f768d0de43ffd16fd4f2f4bb92cb43190598e9d3e04d6c48bdd964c6edcd7ea8e8c1594e5c883a9968ba
+  data.tar.gz: b300b19d4869daf770dd612f7524ce5a8cbf909d3812be2feb9661ee42a01f55ec639071e2f2515c4d6c6b7e4d23823321be501bc234457cb26597e8ad74dafe

data/.codeclimate.yml

@@ -0,0 +1,9 @@
+engines:
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - lib/**/*
+exclude_paths:
+- spec/**/*
+- vendor/**/*

data/.travis.yml

@@ -0,0 +1,16 @@
+sudo: required
+services:
+- docker
+language: ruby
+rvm:
+- 2.1.5
+before_install:
+- sudo service docker stop
+- sudo apt-get purge lxc-docker-1.7.0
+- curl -sSL https://get.docker.com/ | sudo sh
+- docker version
+- docker info
+script: bundle exec rspec
+addons:
+  code_climate:
+    repo_token: e1dfe86e3cc086b44532f7f1122f585fe828e141767ac41e833b365b21fd275a

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+--readme README.md

data/Gemfile

@@ -11,6 +11,7 @@ group :development do
 end
 
 group :test do
+  gem 'codeclimate-test-reporter', require: false
   gem 'rspec', '~> 3.0'
   gem 'rspec-collection_matchers'
   gem 'fakefs', require: false

data/Gemfile.lock

@@ -3,6 +3,8 @@ GEM
   specs:
     addressable (2.3.8)
     builder (3.2.2)
+    codeclimate-test-reporter (0.4.8)
+      simplecov (>= 0.7.1, < 1.0.0)
     coderay (1.1.0)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
@@ -87,6 +89,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  codeclimate-test-reporter
   docker-api (~> 1.22)
   excon (~> 0.45)
   fakefs

data/README.md

@@ -1,6 +1,9 @@
 # drydock
 
-(WORK IN PROGRESS)
+WORK IN PROGRESS — ALPHA-RELEASE SOFTWARE
+SOME FEATURES REQUIRE DOCKER 1.8.0 OR NEWER
+
+![Automated Build Status](https://travis-ci.org/ripta/drydock.svg)
 
 A ruby DSL to build your own docker images. Images are built based on instructions
 contained in your project's `Drydockfile`.
@@ -38,8 +41,10 @@ Drydockfiles are written in ruby.
 
 ## Production Installation
 
-Either (a) `gem install drydock`, or (b) add "drydock" to your project's Gemfile,
-and run `bundle`.
+Either (a) `gem install dry-dock`, or (b) add "dry-dock" to your project's Gemfile,
+and run `bundle`. Sorry, but the gem name `drydock` was already taken by a defunct
+gem, and I'm too lazy to contact them; the binary and name of the project, however,
+are both `drydock`.
 
 In your project's root directory, you'll want to create a `Drydockfile` containing
 drydock functions. When you're ready, build an image using:
@@ -67,9 +72,28 @@ $ git clone git@github.com:ripta/drydock.git
 $ bundle
 ```
 
+## Drydockfile Syntax
+
+As previously mentioned, Drydockfiles are ruby. The contents of Drydockfile are
+evaluated in the context of an instance of `Drydock::Project`; you can refer to
+the documentation for it for more in-depth information.
+
+Because Drydockfiles are ruby, most constructs should work as-is: you can declare
+constants and refer to them later; call `Kernel#abort` to exit the program and
+stop the build; and write plugins to be called from within the Drydockfile.
+
+It would help if you understand ruby and
+[Dockerfiles](https://docs.docker.com/reference/builder/) before jumping in.
+
+All instructions are evaluated in the order that they are seen; syntax errors or
+any logical errors might not be caught until execution arrives at that point.
+
+For a complete and updated list of Drydockfile instructions, see the public API
+methods of the {Drydock::Project} class or head to the
+[automatically-generated ruby docs](http://www.rubydoc.info/gems/dry-dock).
+
+
 ## Roadmap
 
 1. Customizable caching subsystem.
-2. Derived docker images from a previous build step.
-3. Composable docker images.
 4. Customizable caching rules.

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

data/dry-dock.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: dry-dock 0.1.4 ruby lib
+# stub: dry-dock 0.1.5 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "dry-dock"
-  s.version = "0.1.4"
+  s.version = "0.1.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Ripta Pasay"]
-  s.date = "2015-10-02"
+  s.date = "2015-10-07"
   s.description = "A Dockerfile-replacement DSL for building complex images"
   s.email = "github@r8y.org"
   s.executables = ["drydock", "json-test-consumer.rb", "json-test-producer.rb", "test-tar-writer-digest.rb"]
@@ -20,9 +20,12 @@ Gem::Specification.new do |s|
     "README.md"
   ]
   s.files = [
+    ".codeclimate.yml",
     ".dockerignore",
     ".pryrc",
     ".rspec",
+    ".travis.yml",
+    ".yardopts",
     "Dockerfile",
     "Gemfile",
     "Gemfile.lock",

data/lib/drydock/drydock.rb

@@ -29,12 +29,6 @@ module Drydock
     end
   end
 
-  def self.build_on_chain(chain, opts = {}, &blk)
-    Project.new(opts.merge(chain: chain)).tap do |project|
-      project.instance_eval(&blk) if blk
-    end
-  end
-
   def self.from(repo, opts = {}, &blk)
     opts = opts.clone
     tag  = opts.delete(:tag, 'latest')

data/lib/drydock/errors.rb

@@ -6,4 +6,6 @@ module Drydock
 
   class ExecutionError < OperationError; end
   class InvalidCommandExecutionError < ExecutionError; end
+
+  class InsufficientVersionError < OperationError; end
 end

data/lib/drydock/phase_chain.rb

@@ -9,9 +9,13 @@ module Drydock
     def self.build_commit_opts(opts = {})
       {}.tap do |commit|
         if opts.key?(:command)
-          commit['run'] = {
-            Cmd: opts[:command]
-          }
+          commit['run'] ||= {}
+          commit['run'][:Cmd] = opts[:command]
+        end
+
+        if opts.key?(:entrypoint)
+          commit['run'] ||= {}
+          commit['run'][:Entrypoint] = opts[:entrypoint]
         end
 
         commit[:author]  = opts.fetch(:author, '')  if opts.key?(:author)
@@ -127,6 +131,22 @@ module Drydock
       new(Docker::Image.create(build_pull_opts(repo, tag)))
     end
 
+    def self.propagate_config!(src_image, config_name, opts, opt_key)
+      if opts.key?(opt_key)
+        Drydock.logger.info("Command override: #{opts[opt_key].inspect}")
+      else
+        src_image.refresh!
+        if src_image.info && src_image.info.key?('Config')
+          src_image_config = src_image.info['Config']
+          opts[opt_key]    = src_image_config[config_name] if src_image_config.key?(config_name)
+        end
+
+        Drydock.logger.debug(message: "Command retrieval: #{opts[opt_key].inspect}")
+        Drydock.logger.debug(message: "Source image info: #{src_image.info.class} #{src_image.info.inspect}")
+        Drydock.logger.debug(message: "Source image config: #{src_image.info['Config'].inspect}")
+      end
+    end
+
     def initialize(from, parent = nil)
       @chain  = []
       @from   = from
@@ -231,20 +251,8 @@ module Drydock
           Drydock.logger.info(message: "Skipping commit phase")
           ephemeral_containers << container
         else
-          if opts.key?(:command)
-            Drydock.logger.info("Command override: #{opts[:command].inspect}")
-          else
-            src_image.refresh!
-            if src_image.info && src_image.info.key?('Config')
-              src_image_config = src_image.info['Config']
-              opts[:command]   = src_image_config['Cmd'] if src_image_config.key?('Cmd')
-            end
-
-            Drydock.logger.debug(message: "Command retrieval: #{opts[:command].inspect}")
-            Drydock.logger.debug(message: "Source image info: #{src_image.info.class} #{src_image.info.inspect}")
-            Drydock.logger.debug(message: "Source image config: #{src_image.info['Config'].inspect}")
-          end
-
+          self.class.propagate_config!(src_image, 'Cmd',        opts, :command)
+          self.class.propagate_config!(src_image, 'Entrypoint', opts, :entrypoint)
           commit_config = self.class.build_commit_opts(opts)
 
           result = container.commit(commit_config)

data/lib/drydock/project.rb

@@ -7,11 +7,23 @@ module Drydock
       author: nil,
       cache: nil,
       event_handler: false,
-      ignorefile: '.dockerignore',
-      label: nil,
-      logs: false
+      ignorefile: '.dockerignore'
     }
 
+    # Create a new project. **Do not use directly.**
+    #
+    # @api private
+    # @param [Hash] build_opts Build-time options
+    # @option build_opts [Boolean] :auto_remove Whether intermediate images
+    #   created during the build of this project should be automatically removed.
+    # @option build_opts [String] :author The default author field when an
+    #   author is not provided explicitly with {#author}.
+    # @option build_opts [ObjectCaches::Base] :cache An object cache manager.
+    # @option build_opts [#call] :event_handler A handler that responds to a
+    #   `#call` message with four arguments: `[event, is_new, serial_no, event_type]`
+    #   most useful to override logging or 
+    # @option build_opts [PhaseChain] :chain A phase chain manager.
+    # @option build_opts [String] :ignorefile The name of the ignore-file to load.
     def initialize(build_opts = {})
       @chain   = build_opts.key?(:chain) && build_opts.delete(:chain).derive
       @plugins = {}
@@ -27,25 +39,66 @@ module Drydock
 
     # Set the author for commits. This is not an instruction, per se, and only
     # takes into effect after instructions that cause a commit.
+    #
+    # This instruction affects **all instructions after it**, but nothing before it.
+    #
+    # At least one of `name` or `email` must be given. If one is provided, the
+    # other is optional.
+    #
+    # If no author instruction is provided, the author field is left blank by default.
+    #
+    # @param [String] name The name of the author or maintainer of the image.
+    # @param [String] email The email of the author or maintainer.
+    # @raise [InvalidInstructionArgumentError] when neither name nor email is provided
     def author(name: nil, email: nil)
+      if (name.nil? || name.empty?) && (email.nil? || name.empty?)
+        raise InvalidInstructionArgumentError, 'at least one of `name:` or `email:` must be provided'
+      end
+
       value = email ? "#{name} <#{email}>" : name.to_s
       set :author, value
     end
 
-    # Retrieve the current build ID for this project.
+    # Retrieve the current build ID for this project. If no image has been built,
+    # returns the string '0'.
     def build_id
       chain ? chain.serial : '0'
     end
 
     # Change directories for operations that require a directory.
-    def cd(path, &blk)
+    #
+    # @param [String] path The path to change directories to.
+    # @yield block containing instructions to run inside the new directory
+    def cd(path = '/', &blk)
       @run_path << path
-      blk.call
+      blk.call if blk
     ensure
       @run_path.pop
     end
 
-    # Set the command to automatically execute when the image is run.
+    # Set the command that is automatically executed by default when the image
+    # is run through the `docker run` command.
+    #
+    # {#cmd} corresponds to the `CMD` Dockerfile instruction. This instruction
+    # does **not** run the command, but rather provides the default command to
+    # be run when the image is run without specifying a command.
+    #
+    # As with the `CMD` Dockerfile instruction, the {#cmd} instruction has three
+    # forms:
+    #
+    # * `['executable', 'param1', 'param2', '...']`, which would run the
+    #   executable directly when the image is run;
+    # * `['param1', 'param2', '...']`, which would pass the parameters to the
+    #   executable provided in the {#entrypoint} instruction; or
+    # * `'executable param1 param2'`, which would run the executable inside
+    #   a subshell.
+    #
+    # The first two forms are preferred over the last one. See also {#entrypoint}
+    # to see how the instruction interacts with this one.
+    #
+    # @param [String, Array<String>] command The command set to run. When a
+    #   `String` is provided, the command is run inside a shell (`/bin/sh`).
+    #   When an `Array` is given, the command is run as-is given.
     def cmd(command)
       requires_from!(:cmd)
       log_step('cmd', command)
@@ -61,14 +114,33 @@ module Drydock
     # Copies files from `source_path` on the the build machine, into `target_path`
     # in the container. This instruction automatically commits the result.
     #
-    # When `chmod` is `false` (the default), the original file mode from its
-    # source file is kept when copying into the container. Otherwise, the mode
-    # provided will be used to override *all* file and directory modes.
+    # The `copy` instruction always respects the `ignorefile`.
     #
-    # When `no_cache` is `false` (the default), the hash digest of the source path
-    # is used as the cache key. When `true`, the image is rebuilt every time.
+    # When `no_cache` is `true` (also see parameter explanation below), then any
+    # instruction after {#copy} will also be rebuilt *every time*.
     #
-    # The `copy` instruction always respects the `ignorefile`.
+    # @param [String] source_path The source path on the build machine (where
+    #   `drydock` is running) from which to copy files.
+    # @param [String] target_path The target path inside the image to which to
+    #   copy the files. This path **must already exist** before copying begins.
+    # @param [Integer, Boolean] chmod When `false` (the default), the original file
+    #   mode from its source file is kept when copying into the container. Otherwise,
+    #   the mode provided (in integer octal form) will be used to override *all*
+    #   file and directory modes.
+    # @param [Boolean] no_cache When `false` (the default), the hash digest of the
+    #   source path—taking into account all its files, directories, and contents—is
+    #   used as the cache key. When `true`, the image is rebuilt *every* time.
+    # @param [Boolean] recursive When `true`, then `source_path` is expected to be
+    #   a directory, at which point all its contents would be recursively searched.
+    #   When `false`, then `source_path` is expected to be a file.
+    #
+    # @raise [InvalidInstructionError] when the `source_path` does not exist
+    # @raise [InvalidInstructionError] when the `source_path` is an empty directory
+    #   with nothing to copy
+    # @raise [InvalidInstructionError] when the `target_path` does not exist in the
+    #   container
+    # @raise [InvalidInstructionError] when the `target_path` exists in the container,
+    #   but is not actually a directory
     def copy(source_path, target_path, chmod: false, no_cache: false, recursive: true)
       requires_from!(:copy)
       log_step('copy', source_path, target_path, chmod: (chmod ? sprintf('%o', chmod) : false))
@@ -128,12 +200,18 @@ module Drydock
       self
     end
 
+    # Destroy the images and containers created, and attempt to return the docker
+    # state as it was before the project.
+    #
+    # @api private
     def destroy!(force: false)
       chain.destroy!(force: force) if chain
       finalize!(force: force)
     end
 
     # Meta instruction to signal to the builder that the build is done.
+    #
+    # @api private
     def done!
       throw :done
     end
@@ -173,7 +251,101 @@ module Drydock
       self
     end
 
-    # Set an environment variable.
+    # **This instruction is *optional*, but if specified, must appear at the
+    # beginning of the file.** 
+    #
+    # This instruction is used to restrict the version of `drydock` required to
+    # run the `Drydockfile`. When not specified, any version of `drydock` is
+    # allowed to run the file.
+    #
+    # The version specifier understands any bundler-compatible (and therefore
+    # [gem-compatible](http://guides.rubygems.org/patterns/#semantic-versioning))
+    # version specification; it even understands the twiddle-waka (`~>`) operator.
+    #
+    # @example
+    #   drydock '~> 0.5'
+    # @param [String] version The version specification to use.
+    def drydock(version = '>= 0')
+      raise InvalidInstructionError, '`drydock` must be called before `from`' if chain
+      log_step('drydock', version)
+      
+      requirement = Gem::Requirement.create(version)
+      current     = Gem::Version.create(Drydock.version)
+
+      unless requirement.satisfied_by?(current)
+        raise InsufficientVersionError, "build requires #{version.inspect}, but you're on #{Drydock.version.inspect}"
+      end
+
+      self
+    end
+
+    # Sets the entrypoint command for an image. 
+    #
+    # {#entrypoint} corresponds to the `ENTRYPOINT` Dockerfile instruction. This
+    # instruction does **not** run the command, but rather provides the default
+    # command to be run when the image is run without specifying a command.
+    #
+    # As with the {#cmd} instruction, {#entrypoint} has three forms, of which the
+    # first two forms are preferred over the last one.
+    #
+    # @param (see #cmd)
+    def entrypoint(command)
+      requires_from!(:entrypoint)
+      log_step('entrypoint', command)
+
+      unless command.is_a?(Array)
+        command = ['/bin/sh', '-c', command.to_s]
+      end
+
+      chain.run("# ENTRYPOINT #{command.inspect}", entrypoint: command)
+      self
+    end
+
+    # Set an environment variable, which will be persisted in future images
+    # (unless it is specifically overwritten) and derived projects.
+    # 
+    # Subsequent commands can refer to the environment variable by preceeding
+    # the variable with a `$` sign, e.g.:
+    #
+    # ```
+    #   env 'APP_ROOT', '/app'
+    #   mkdir '$APP_ROOT'
+    #   run ['some-command', '--install-into=$APP_ROOT']
+    # ```
+    #
+    # Multiple calls to this instruction will build on top of one another.
+    # That is, after the following two instructions:
+    # 
+    # ```
+    #   env 'APP_ROOT',   '/app'
+    #   env 'BUILD_ROOT', '/build'
+    # ```
+    #
+    # the resulting image will have both `APP_ROOT` and `BUILD_ROOT` set. Later
+    # instructions overwrites previous instructions of the same name:
+    #
+    # ```
+    #   # 1
+    #   env 'APP_ROOT', '/app'
+    #   # 2
+    #   env 'APP_ROOT', '/home/jdoe/app'
+    #   # 3
+    # ```
+    #
+    # At `#1`, `APP_ROOT` is not set (assuming no other instruction comes before
+    # it). At `#2`, `APP_ROOT` is set to '/app'. At `#3`, `APP_ROOT` is set to
+    # `/home/jdoe/app`, and its previous value is no longer available.
+    #
+    # Note that the environment variable is not evaluated in ruby; in fact, the
+    # `$` sign should be passed as-is to the instruction. As with shell
+    # programming, the variable name should **not** be preceeded by the `$`
+    # sign when declared, but **must be** when referenced.
+    #
+    # @param [String] name The name of the environment variable. By convention,
+    #   the name should be uppercased and underscored. The name should **not**
+    #   be preceeded by a `$` sign in this context.
+    # @param [String] value The value of the variable. No extra quoting should be
+    #   necessary here.
     def env(name, value)
       requires_from!(:env)
       log_step('env', name, value)
@@ -181,9 +353,31 @@ module Drydock
       self
     end
 
-    # Set multiple environment variables at once. `pairs` should be a
-    # hash-like enumerable.
-    def envs(pairs = {})
+    # Set multiple environment variables at once. The values will be persisted in
+    # future images and derived projects, unless specifically overwritten.
+    #
+    # The following instruction:
+    #
+    # ```
+    #   envs APP_ROOT: '/app', BUILD_ROOT: '/tmp/build'
+    # ```
+    #
+    # is equivalent to the more verbose:
+    #
+    # ```
+    #   env 'APP_ROOT', '/app'
+    #   env 'BUILD_ROOT', '/tmp/build'
+    # ```
+    #
+    # When the same key appears more than once in the same {#envs} instruction,
+    # the same rules for ruby hashes are used, which most likely (but not guaranteed
+    # between ruby version) means the last value set is used.
+    #
+    # See also notes for {#env}.
+    #
+    # @param [Hash, #map] pairs A hash-like enumerable, where `#map` yields exactly
+    #   two elements. See {#env} for any restrictions of the name (key) and value.
+    def envs(pairs)
       requires_from!(:envs)
       log_step('envs', pairs)
 
@@ -192,13 +386,24 @@ module Drydock
       self
     end
 
-    # Expose one or more ports.
+    # Expose one or more ports. The values will be persisted in future images
     #
     # When `ports` is specified, the format must be: ##/type where ## is the port
     # number and type is either tcp or udp. For example, "80/tcp", "53/udp".
     #
     # Otherwise, when the `tcp` or `udp` options are specified, only the port
     # numbers are required.
+    #
+    # @example Different ways of exposing port 53 UDP and ports 80 and 443 TCP:
+    #   expose '53/udp', '80/tcp', '443/tcp'
+    #   expose udp: 53, tcp: [80, 443]
+    # @param [Array<String>] ports An array of strings of port specifications.
+    #   Each port specification must look like `#/type`, where `#` is the port
+    #   number, and `type` is either `udp` or `tcp`.
+    # @param [Integer, Array<Integer>] tcp A TCP port number to open, or an array
+    #   of TCP port numbers to open.
+    # @param [Integer, Array<Integer>] udp A UDP port number to open, or an array
+    #   of UDP port numbers to open.
     def expose(*ports, tcp: [], udp: [])
       requires_from!(:expose)
 
@@ -210,10 +415,21 @@ module Drydock
       chain.run("# SET PORTS #{ports.inspect}", expose: ports)
     end
 
-    # Build on top of the `from` image. This must be the first instruction of
-    # the project, although non-instructions may appear before this.
+    # Build on top of the `from` image. **This must be the first instruction of
+    # the project,** although non-instructions may appear before this.
+    #
+    # If the `drydock` instruction is provided, `from` should come after it.
+    # 
+    # @param [#to_s] repo The name of the repository, which may be any valid docker
+    #   repository name, and may optionally include the registry address, e.g.,
+    #   `johndoe/thing` or `quay.io/jane/app`. The name *must not* contain the tag name.
+    # @param [#to_s] tag The tag to use.
     def from(repo, tag = 'latest')
       raise InvalidInstructionError, '`from` must only be called once per project' if chain
+
+      repo = repo.to_s
+      tag  = tag.to_s
+
       log_step('from', repo, tag)
       @chain = PhaseChain.from_repo(repo, tag)
       self
@@ -221,6 +437,8 @@ module Drydock
 
     # Finalize everything. This will be automatically invoked at the end of
     # the build, and should not be called manually.
+    #
+    # @api private
     def finalize!(force: false)
       if chain
         chain.finalize!(force: force)
@@ -234,13 +452,73 @@ module Drydock
       self
     end
 
-    # Derive a new project based on the current state of the build. This
-    # instruction returns a project that can be referred to elsewhere.
+    # Derive a new project based on the current state of the current project.
+    # This instruction returns the new project that can be referred to elsewhere,
+    # and most useful when combined with other inter-project instructions,
+    # such as {#import}.
+    #
+    # For example:
+    #
+    # ```
+    #   from 'some-base-image'
+    #
+    #   APP_ROOT = '/app'
+    #   mkdir APP_ROOT
+    #
+    #   # 1:
+    #   ruby_build = derive {
+    #     copy 'Gemfile', APP_ROOT
+    #     run 'bundle install --path vendor'
+    #   }
+    #
+    #   # 2:
+    #   js_build = derive {
+    #     copy 'package.json', APP_ROOT
+    #     run 'npm install'
+    #   }
+    #
+    #   # 3:
+    #   derive {
+    #     import APP_ROOT, from: ruby_build
+    #     import APP_ROOT, from: js_build
+    #     tag 'jdoe/app', 'latest', force: true
+    #   }
+    # ```
+    #
+    # In the example above, an image is created with a new directory `/app`.
+    # From there, the build branches out into three directions:
+    #
+    # 1. Create a new project referred to as `ruby_build`. The result of this
+    #    project is an image with `/app`, a `Gemfile` in it, and a `vendor`
+    #    directory containing vendored gems.
+    # 2. Create a new project referred to as `js_build`. The result of this
+    #    project is an image with `/app`, a `package.json` in it, and a
+    #    `node_modules` directory containing vendored node.js modules.
+    #    This project does **not** contain any of the contents of `ruby_build`.
+    # 3. Create an anonymous project containing only the empty `/app` directory.
+    #    Onto that, we'll import the contents of `/app` from `ruby_build` into
+    #    this anonymous project. We'll do the same with the contents of `/app`
+    #    from `js_build`. Finally, the resulting image is given the tag
+    #    `jdoe/app:latest`.
+    #
+    # Because each derived project lives on its own and only depends on the
+    # root project (whose end state is essentially the {#mkdir} instruction),
+    # when `Gemfile` changes but `package.json` does not, only the first
+    # derived project will be rebuilt (and following that, the third as well).
+    #
     def derive(opts = {}, &blk)
-      Drydock.build_on_chain(chain, opts, &blk)
+      clean_opts  = build_opts.delete_if { |k, v| v.nil? }
+      derive_opts = clean_opts.merge(opts).merge(chain: chain)
+
+      Project.new(derive_opts).tap do |project|
+        project.instance_eval(&blk) if blk
+      end
     end
 
     # Access to the logger object.
+    #
+    # @return [Logger] A logger object on which one could call `#info`, `#error`,
+    #   and the likes.
     def logger
       Drydock.logger
     end
@@ -248,11 +526,14 @@ module Drydock
     # Import a `path` from a different project. The `from` option should be
     # project, usually the result of a `derive` instruction.
     #
-    # TODO(rpasay): add a #load method as an alternative to #import, which allows
-    # importing a full container, including things from /etc.
-    # TODO(rpasay): do not always append /. to the #archive_get calls; must check
-    # the type of `path` inside the container first.
-    # TODO(rpasay): break this large method into smaller ones.
+    # @todo Add a #load method as an alternative to #import
+    #   Doing so would allow importing a full container, including things from
+    #   /etc, some of which may be mounted from the host.
+    #
+    # @todo Do not always append /. to the #archive_get calls
+    #   We must check the type of `path` inside the container first.
+    #
+    # @todo Break this large method into smaller ones.
     def import(path, from: nil, force: false, spool: false)
       mkdir(path)
 
@@ -296,14 +577,18 @@ module Drydock
       log_info("Imported #{Formatters.number(total_size)} bytes")
     end
 
-    # The last image object built in this project.
+    # Retrieve the last image object built in this project.
+    #
+    # If no image has been built, returns `nil`.
     def last_image
       chain ? chain.last_image : nil
     end
 
-    # Create a new directory specified by `path`. When `chmod` is given, the new
-    # directory will be chmodded. Otherwise, the default umask is used to determine
-    # the path's mode.
+    # Create a new directory specified by `path` in the image.
+    #
+    # @param [String] path The path to create inside the image.
+    # @param [String] chmod The mode to which the new directory will be chmodded.
+    #   If not specified, the default umask is used to determine the mode.
     def mkdir(path, chmod: nil)
       if chmod
         run "mkdir -p #{path} && chmod #{chmod} #{path}"
@@ -312,7 +597,7 @@ module Drydock
       end
     end
 
-    # TODO(rpasay): on_build instructions should be deferred to the end
+    # @todo on_build instructions should be deferred to the end.
     def on_build(instruction = nil, &blk)
       requires_from!(:on_build)
       log_step('on_build', instruction)
@@ -334,6 +619,15 @@ module Drydock
     #   normal usage, you should use the `expose` instruction instead.
     # * `on_build`, which can be used to specify low-level on-build options. For
     #   normal usage, you should use the `on_build` instruction instead.
+    #
+    # Additional `opts` are also recognized:
+    #
+    # * `author`, a string, preferably in the format of "Name <email@domain.com>".
+    #   If provided, this overrides 
+    # * `comment`, an arbitrary string used as a comment for the resulting image
+    #
+    # If `run` results in a container being created and `&blk` is provided, the
+    # container will be yielded to the block.
     def run(cmd, opts = {}, &blk)
       requires_from!(:run)
 
@@ -374,13 +668,17 @@ module Drydock
     # Use a `plugin` to issue other commands. The block form can be used to issue
     # multiple commands:
     #
+    # ```
     #   with Plugins::APK do |apk|
     #     apk.update
     #   end
+    # ```
     # 
     # In cases of single commands, the above is the same as:
     #
+    # ```
     #   with(Plugins::APK).update
+    # ```
     def with(plugin, &blk)
       (@plugins[plugin] ||= plugin.new(self)).tap do |instance|
         yield instance if block_given?

data/spec/drydock/project_spec.rb

@@ -61,6 +61,27 @@ RSpec.describe Drydock::Project do
     expect(hash_output).to include('60fde9c2310b0d4cad4dab8d126b04387efba289')
   end
 
+  it 'fails to change working directory if it does not exist' do
+    project.from('alpine')
+    expect { project.cd('/app') }.not_to raise_error
+    expect { project.cd('/app') { project.run('pwd') } }.to raise_error(Drydock::InvalidCommandExecutionError)
+  end
+
+  it 'correctly changes working directories' do
+    project.from('alpine')
+    project.mkdir('/app')
+    expect { project.cd('/app') { project.run('pwd') } }.not_to raise_error
+  end
+
+  it 'complains when version check does not pass' do
+    expect { project.drydock('~> 901.301') }.to raise_error(Drydock::InsufficientVersionError)
+  end
+
+  it 'requires version check to go before #from instruction' do
+    project.from('alpine')
+    expect { project.drydock('~> 0.1') }.to raise_error(Drydock::InvalidInstructionError)
+  end
+
   it 'autocreates the target path on copy' do
     project.from('alpine')
     expect {
@@ -116,6 +137,18 @@ RSpec.describe Drydock::Project do
     expect(image.info['ContainerConfig']['Cmd']).to eq(['/bin/sh', '-c', '/bin/date'])
   end
 
+  it 'sets the raw Entrypoint' do
+    project.from('alpine')
+    project.entrypoint(['/bin/bash'])
+
+    expect(project.last_image).not_to be_nil
+
+    image = Docker::Image.get(project.last_image.id)
+    expect(image).not_to be_nil
+    expect(image.info['Config']['Entrypoint']).to eq(['/bin/bash'])
+  end
+
+
   it 'sets the Env' do
     project.from('alpine')
     project.env('APP_ROOT_TEST', '/app/current')
@@ -127,10 +160,11 @@ RSpec.describe Drydock::Project do
     expect(image.info['Config']['Env']).to include('APP_ROOT_TEST=/app/current')
   end
 
-  it 'sets the Env with multiple values' do
+  it 'sets the Env with multiple values, and retained after other commands' do
     project.from('alpine')
     project.env('APP_ROOT_TEST', '/app/current')
     project.env('BUILD_ROOT',    '/tmp/build')
+    project.run('touch /hello-world')
 
     expect(project.last_image).not_to be_nil
 
@@ -140,6 +174,19 @@ RSpec.describe Drydock::Project do
     expect(image.info['Config']['Env']).to include('BUILD_ROOT=/tmp/build')
   end
 
+  it 'sets multiple Envs in one go, and retained after other commands' do
+    project.from('alpine')
+    project.envs(APP_ROOT: '/app', BUILD_ROOT: '/build')
+    project.run('touch /hello-world')
+
+    expect(project.last_image).not_to be_nil
+
+    image = Docker::Image.get(project.last_image.id)
+    expect(image).not_to be_nil
+    expect(image.info['Config']['Env']).to include('APP_ROOT=/app')
+    expect(image.info['Config']['Env']).to include('BUILD_ROOT=/build')
+  end
+
   it 'sets the ExposedPorts' do
     project.from('alpine')
     project.expose(tcp: [80, 443], udp: 53)

data/spec/drydock/stream_monitor_spec.rb

@@ -30,7 +30,13 @@ RSpec.describe Drydock::StreamMonitor do
       expect(monitor).not_to be_nil
       expect(run_image).not_to be_nil
 
-      expect(events).to have(5).items
+      sleep 1
+      expect(events).to have_at_least(1).item
+
+      event_statuses = events.map(&:status).sort
+      expect(event_statuses).to include('create')
+      expect(event_statuses).to include('pull')
+      expect(event_statuses).to include('start')
 
       commit_event = events.find { |evt| evt.status == 'commit' }
       expect(commit_event).not_to be_nil

data/spec/spec_helper.rb

@@ -7,6 +7,9 @@ require 'fakefs/spec_helpers'
 require 'simplecov'
 require 'simplecov-rcov'
 
+require 'codeclimate-test-reporter'
+CodeClimate::TestReporter.start
+
 unless ENV.key?('RCOV')
   SimpleCov.start {
     add_filter '/vendor/'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-dock
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Ripta Pasay
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-02 00:00:00.000000000 Z
+date: 2015-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docker-api
@@ -120,9 +120,12 @@ extra_rdoc_files:
 - LICENSE
 - README.md
 files:
+- ".codeclimate.yml"
 - ".dockerignore"
 - ".pryrc"
 - ".rspec"
+- ".travis.yml"
+- ".yardopts"
 - Dockerfile
 - Gemfile
 - Gemfile.lock