rumrunner 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2d506d9a66b272edf5663be0c4dac9bd641f379dd5c165fc2cba54fd3d14d2b
-  data.tar.gz: 51f946b939d14cdc41586bc4325040fac38bd9084185594ea6aac0820edf1aeb
+  metadata.gz: baac9f7a8524654ef3c90b7ffe5ee1d726ce01252d4cb2af7e0dae09d8fec667
+  data.tar.gz: 66e87c6cba9dbe2c7ea7ce09c0fdfd16ca83861bf19e83b6c9139fced65d4435
 SHA512:
-  metadata.gz: 17d8992d08dad789e01d5b8a43d479ae4b8f3689123c18e6cf34208338940d7509595459b3bc5b31212ca6fe1089ed7e5ea022c0a672aa3967649c850b12dab6
-  data.tar.gz: 92d1f795b46d4059d87f1b12928015990382268125964304eec1771386ccc8249695f0791964a40fa3bd3e7b46c54161732e4f667e05d90aea840d0909e83cc5
+  metadata.gz: 5b70c6649583bc4f282d3c630c7fd35e307ac66c09ae8b5a70c08349a615418b0b96b9cc84816d9ad371bb0948e25a3dcd3ff575102cde6684db379558cb9b48
+  data.tar.gz: 12f2b6fcc92a637bacc670cc424a1b1d75b57b05c10ce7bc66410c2755777dff2c0f2ff9a555195b90726bd38ed88a9b728545768c3a43aba0055e2fa8c2c9ff

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Alexander Mancevice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,350 @@
+[![Rum Runner](https://github.com/amancevice/rumrunner/blob/master/rum-runner.png?raw=true)](https://github.com/amancevice/rumrunner)
+[![Build Status](https://travis-ci.com/amancevice/rumrunner.svg?branch=master)](https://travis-ci.com/amancevice/rumrunner)
+[![Gem Version](https://badge.fury.io/rb/rumrunner.svg)](https://badge.fury.io/rb/rumrunner)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/4b56853acc5cbb254125/test_coverage)](https://codeclimate.com/github/amancevice/rumrunner/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/4b56853acc5cbb254125/maintainability)](https://codeclimate.com/github/amancevice/rumrunner/maintainability)
+
+<sub>logo by [seenamavaddat.com](http://seenamavaddat.com/)</sub>
+
+Rum Runner is a Rake-based utility for building multi-stage Dockerfiles.
+
+Users can pair a multi-stage Dockerfile with a Rumfile that uses a Rake-like DSL to customize each stage's build options and dependencies.
+
+The `rum` executable allows users to easily invoke builds, shell-into specific stages for debugging, and export artifacts from built containers.
+
+Rum Runner has the following features:
+* Fully compatible with Rake
+* Rake-like DSL/CLI that enable simple annotation and execution of builds
+* Rumfiles are completely defined in standard Ruby syntax, like Rakefiles
+* Users can chain Docker build stages with prerequisites
+* Artifacts can be exported from stages
+* Shell tasks are automatically provided for every stage
+* Stage, artifact, and shell, steps can be customized
+
+**Origins**
+
+This project was born from using Makefiles to drive multi-stage builds. For the most part this worked really well, but it became a bit of an ordeal to write for more complex projects. This tool is an attempt to recreate that general technique with minimal annotation and limited assumptions.
+
+View the docs on [rubydoc.info](https://www.rubydoc.info/github/amancevice/rumrunner)
+
+## Installation
+
+```bash
+gem install rumrunner
+```
+
+## Quickstart
+
+If you have a multi-stage Dockerfile in your project and are unsure where to begin, use the `rum init` helper to create a template Rumfile for your project:
+
+```bash
+gem install rumrunner
+rum init > Rumfile
+rum --tasks
+```
+
+The `init` command will parse a Dockerfile in the current directory and output a simple Rumfile with each stage and its dependencies declared.
+
+## Example
+
+Imagine a simple multi-stage Dockerfile:
+
+```Dockerfile
+FROM ruby AS build
+# Run build steps here...
+
+FROM ruby AS test
+# Run test steps here...
+
+FROM ruby AS deploy
+# Run deploy steps here...
+```
+
+Create `Rumfile` and describe your build:
+
+```ruby
+rum :image_name do
+  tag "1.2.3"
+
+  stage :build
+  stage :test => :build
+  stage :deploy => :test
+
+  # rum build  => docker build --target build  --tag image_name:1.2.3-build .
+  # rum test   => docker build --target test   --tag image_name:1.2.3-test .
+  # rum deploy => docker build --target deploy --tag image_name:1.2.3-deploy .
+end
+```
+
+Run `rum --tasks` to view the installed tasks:
+
+```bash
+rum build                # Build `build` stage
+rum clean                # Remove any temporary images and products
+rum clean:build          # Remove any temporary images and products through `build` stage
+rum clean:deploy         # Remove any temporary images and products through `deploy` stage
+rum clean:test           # Remove any temporary images and products through `test` stage
+rum clobber              # Remove any generated files
+rum deploy               # Build `deploy` stage
+rum shell:build[shell]   # Shell into `build` stage
+rum shell:deploy[shell]  # Shell into `deploy` stage
+rum shell:test[shell]    # Shell into `test` stage
+rum test                 # Build `test` stage
+```
+
+## Customize Shells
+
+By default, all stages have a `:shell` task that can be invoked to build and shell into a container for a stage. By default the container is run as an ephemeral container (`--rm`) in interactive with TTY allocated and a bash shell open.
+
+Customize the shell for a stage with the `shell` method:
+
+```ruby
+rum :image_name do
+  stage :dev
+
+  shell :dev do
+    entrypoint "/bin/zsh"
+    rm         false
+    volume     "#{Dir.pwd}:/var/task/"
+  end
+
+  # rum dev => docker run --entrypoint /bin/zsh --volume $PWD:/var/task/ ...
+end
+```
+
+## Customize Stages
+
+Stages can be customized with blocks:
+
+```ruby
+rum :image_name do
+  tag "1.2.3"
+
+  stage :build
+
+  stage :test => :build
+
+  stage :deploy => :test do
+    build_arg :AWS_ACCESS_KEY_ID
+    build_arg :AWS_SECRET_ACCESS_KEY
+    build_arg :AWS_DEFAULT_REGION => "us-east-1"
+    label     :Fizz
+  end
+end
+```
+
+Methods invoked inside the stage block are interpreted as options for the eventual `docker build` command.
+
+## Export Artifacts
+
+Use the `artifact` method to specify an artifact to be exported from the image.
+
+```ruby
+rum :image_name do
+  stage :build
+
+  artifact "package.zip" => :build
+end
+```
+
+By default the container simply `cat`s the file from the container to the local file system, but more complex exports can be defined:
+
+```ruby
+rum :image_name do
+  stage :build
+
+  artifact "package.zip" => :build do
+    workdir "/var/task/"
+    cmd     %w[zip -r - .]
+  end
+end
+```
+
+Methods invoked inside the artifact block are interpreted as options for the eventual `docker run` command.
+
+## Default Task
+
+Every `rum` declaration has a default task associated with it so that simply executing `rum` on the command line does something.
+
+In the most simple case, the default task simply builds the image:
+
+```ruby
+rum :image_name
+# rum => docker build --tag image_name .
+```
+
+Use the `default` method inside the main block to set a default task or tasks:
+
+```ruby
+rum :image_name do
+  stage :build
+  stage :plan => :build
+
+  artifact "package.zip" => :build
+
+  default ["package.zip", :plan]
+end
+# rum => docker build --target build ...
+#        docker run ... > package.zip
+#        docker build --target plan ...
+```
+## Shared ENV variables
+
+The `env` method can be invoked in the `rum` block to declare a value that will be passed to all stages/artifacts/shells. For stages, the value will be passed using the `--build-arg` option; for artifacts and shells, the `--env` option.
+
+```ruby
+rum :image_name do
+  env :FIZZ => :BUZZ
+
+  stage :build
+
+  # rum build => docker build --build-arg FIZZ=BUZZ ...
+end
+```
+
+## Shells
+
+Run a stage task to build the image up to that stage and cache the image digest.
+
+Run with the `:shell` suffix to build the image and then shell into an instance of the image running as a temporary container.
+
+The default shell is `/bin/sh`, but this can be overridden at runtime with the task arg, eg. `rum build:shell[/bin/bash]`
+
+## Build vs. Run
+
+At the core, every directive within the `rum` block will eventually be interpreted as either a `docker build` or a `docker run` command. The type of directive is simply a way of specifying defaults for the command.
+
+If you simply wish to define a named task that executes a build or a run, you can use the `build` or `run` directives:
+
+```ruby
+rum :image_name do
+  env :JAZZ => "fuzz"
+
+  build :fizz do
+    tag  "image_name"
+    path "."
+  end
+
+  run :buzz do
+    rm    true
+    image "image_name"
+    cmd   %w[echo hello]
+  end
+
+  # rum fizz => docker build --build-arg JAZZ=fuzz --tag image_name .
+  # rum buzz => docker run --rm --env JAZZ=fuzz image_name echo hello
+end
+```
+
+Note that the build/run commands will still import any shared ENV values defined above.
+
+If this is undesirable, use the `clear_options` method inside your block to clear ALL the default options:
+
+```ruby
+rum :image_name do
+
+  env :JAZZ => "fuzz"
+
+  run :buzz do
+    clear_options
+    image "image_name"
+    cmd   %w[echo hello]
+  end
+
+  # rum buzz => docker run image_name echo hello
+end
+```
+
+## Blocks
+
+The methods inside blocks for `build`, `run`, `stage`, `artifact`, and `shell` tasks are dynamically handled. Any option you might pass to the `docker run` or `docker build` command can be used.
+
+Simply drop any leading `-`s from the option and convert to snake-case.
+
+Eg,
+
+`--build-arg` becomes `build_arg`
+
+`--env-file` becomes `env_file`.
+
+## Task Naming Convention
+
+As of v0.3, rum runner uses a "verb-first" naming convention (eg. `clean:stage`) for tasks.
+
+To revert to the previous convention of "stage-first" (eg. `stage:clean`) use the environmental variable `RUM_TASK_NAMES`:
+
+```bash
+export RUM_TASK_NAMES=STAGE_FIRST  # => rum stage:clean
+export RUM_TASK_NAMES=VERB_FIRST   # => rum clean:stage (default)
+```
+
+## Image Naming Convention
+
+The name of the images are taken from the first argument to the main block and appended with the name of the stage.
+
+In the above example, built images would build be named:
+
+- `image_name:1.2.3-build`
+- `image_name:1.2.3-test`
+- `image_name:1.2.3-deploy`
+
+The first argument to the main block can be any Docker image reference:
+
+```ruby
+rum :"registry:5000/username/image" do
+  #...
+end
+```
+
+## Dockerfile Location
+
+Images built use the current working directory as the default path to the Dockerfile, but this can be modified:
+
+```ruby
+rum :image_name => "some/dockerfile/dir" do
+  # ...
+end
+```
+
+The default Dockerfile path can also be set using the `RUM_PATH` environmental variable.
+
+
+## Docker Image Digest Location
+
+Images build with the `stage` task have their digests cached for easy lookup.
+
+The default location for the digests is in `.docker`, but that can be modified:
+
+```ruby
+rum :image_name => [".", "tmp"] do
+  # ...
+end
+```
+
+Note that in this case you must also explicitly define the Dockerfile path.
+
+The default digest path can also be set using the `RUM_HOME` environmental variable.
+
+## Integrate with Rake
+
+It isn't strictly necessary to include a `Rumfile` in your project. Rum Runner can be included in any `Rakefile` and run with the `rake` command:
+
+```ruby
+# ./Rakefile
+
+require "rumrunner"
+
+namespace :rum do
+  rum :image_name do
+    stage :build
+    stage :test => :build
+  end
+end
+```
+
+```bash
+$ rake --tasks
+
+rake rum:build # ...
+rake rum:test  # ...
+```

data/lib/rumrunner/docker.rb

@@ -266,6 +266,13 @@ module Rum
         File.join(*[@registry, @username, @name].compact.map(&:to_s))
       end
 
+      ##
+      # Show handle
+      def inspect
+        handle = @tag.nil? || @tag.to_sym == :latest ? family : to_s
+        "#<#{self.class.name}[#{handle}]>"
+      end
+
       ##
       # Convert the image reference to string.
       def to_s

data/lib/rumrunner/dsl_definition.rb

@@ -22,8 +22,8 @@ module Rum
     #
     def rum(*args, &block)
       name, _, deps = Rake.application.resolve_args(args)
-      root = deps.first || :".docker"
-      Manifest.new(name: name, root: root, &block).install
+      path, home = deps
+      Manifest.new(name: name, path: path, home: home, &block).install
     end
   end
 end

data/lib/rumrunner/manifest.rb

@@ -14,21 +14,22 @@ module Rum
     attr_reader :image
 
     def_delegator :@env, :<<, :env
-    def_delegator :@root, :to_s, :root
+    def_delegator :@path, :to_s, :path
+    def_delegator :@home, :to_s, :home
     def_delegators :@image, :registry, :username, :name, :tag, :to_s
 
     ##
-    # Initialize new manifest with name and root path for caching
+    # Initialize new manifest with name, build path, and home path for caching
     # build digests. Evaluates <tt>&block</tt> if given.
     #
     # Example:
-    #   Manifest.new(name: "my_image", root: ".docker")
+    #   Manifest.new(name: "my_image", path: ".", home: ".docker")
     #
-    def initialize(name:, root:nil, &block)
-      @name  = name
-      @root  = root || :".docker"
+    def initialize(name:, path:nil, home:nil, env:nil, &block)
+      @path  = path || ENV["RUM_PATH"] || "."
+      @home  = home || ENV["RUM_HOME"] || ".docker"
+      @env   = env  || []
       @image = Docker::Image.parse(name)
-      @env   = []
       instance_eval(&block) if block_given?
     end
 
@@ -58,9 +59,8 @@ module Rum
     #   build :name => [:deps]
     #
     def build(*args, &block)
-      name, _, deps = Rake.application.resolve_args(args)
-      task name => deps do
-        sh Docker::Build.new(options: build_options, &block).to_s
+      task(*args) do
+        sh Docker::Build.new(options: build_options, path: path, &block).to_s
       end
     end
 
@@ -75,10 +75,10 @@ module Rum
       name, _, deps = Rake.application.resolve_args(args)
 
       images   = deps.map{|dep| Docker::Image.parse("#{@image}-#{dep}") }
-      iidfiles = images.map{|image| File.join(root, *image) }
+      iidfiles = images.map{|image| File.join(home, *image) }
 
-      task name => iidfiles do
-        image = iidfiles.empty? ? to_s : File.read(iidfiles.first)
+      task name => iidfiles do |t|
+        image = t.prereqs.empty? ? to_s : File.read(t.prereqs.first)
         sh Docker::Run.new(options: run_options, image: image, &block).to_s
       end
     end
@@ -95,7 +95,7 @@ module Rum
 
       # Assemble image/iidfile from manifest/stage name
       image   = Docker::Image.parse("#{@image}-#{name}")
-      iidfile = File.join(root, *image)
+      iidfile = File.join(home, *image)
       iidpath = File.split(iidfile).first
 
       # Ensure path to iidfile exists
@@ -104,20 +104,20 @@ module Rum
         iidpath
       else
         images = deps.map{|x| Docker::Image.parse("#{@image}-#{x}") }
-        images.map{|x| File.join(root, *x) }
+        images.map{|x| File.join(home, *x) }
       end
 
       # Build stage and save digest in iidfile
-      stage_file iidfile, iiddeps, tag: image, target: name, &block
+      stage_file(iidfile, iiddeps, tag: image, target: name, &block)
 
       # Shortcut to build stage by name
-      stage_task name, iidfile
+      stage_task(name, iidfile)
 
       # Shell into stage
-      stage_shell name, iidfile
+      stage_shell(name, iidfile)
 
       # Clean stage
-      stage_clean name, iidfile, deps
+      stage_clean(name, iidfile, deps)
     end
 
     ##
@@ -133,7 +133,7 @@ module Rum
 
       target  = deps.first
       image   = Docker::Image.parse("#{@image}-#{target}")
-      iidfile = File.join(root, *image)
+      iidfile = File.join(home, *image)
       path    = File.split(name).first
       deps    = [iidfile]
 
@@ -142,9 +142,9 @@ module Rum
         deps << path
       end
 
-      artifact_file name, deps, iidfile, &block
+      artifact_file(name, deps, iidfile, &block)
 
-      artifact_clobber name, path
+      artifact_clobber(name, path)
     end
 
     ##
@@ -158,7 +158,7 @@ module Rum
       target  = Rake.application.resolve_args(args).first
       name    = task_name shell: target
       image   = Docker::Image.parse("#{@image}-#{target}")
-      iidfile = File.join(root, *image)
+      iidfile = File.join(home, *image)
 
       Rake::Task[name].clear if Rake::Task.task_defined?(name)
 
@@ -175,6 +175,7 @@ module Rum
     ##
     # Install any remaining tasks for the manifest.
     def install
+      install_default unless Rake::Task.task_defined?(:default)
       install_clean
 
       self
@@ -200,20 +201,34 @@ module Rum
     def install_clean
       desc "Remove any temporary images and products"
       task :clean do
-        Dir[File.join root, "**/*"].reverse.each do |name|
+        Dir[File.join(home, "**/*")].reverse.each do |name|
           sh "docker", "image", "rm", "--force", File.read(name) if File.file?(name)
           rm_rf name
         end
-        rm_rf root
+        rm_rf home if Dir.exist?(home)
+      end
+    end
+
+    ##
+    # Install :default task that builds the image
+    def install_default
+      iidfile = File.join(home, *image)
+      file iidfile do |t|
+        tsfile = "#{t.name}@#{Time.now.utc.to_i}"
+        build  = Docker::Build.new(options: build_options, path: path)
+        build.with_defaults(iidfile: tsfile, tag: tag || :latest)
+        sh build.to_s
+        cp tsfile, iidfile
       end
+      task :default => iidfile
     end
 
     ##
     # Install file task for stage and save digest in iidfile
     def stage_file(iidfile, iiddeps, tag:, target:, &block)
-      file iidfile => iiddeps do
-        tsfile = "#{iidfile}@#{Time.now.utc.to_i}"
-        build = Docker::Build.new(options: build_options, &block)
+      file iidfile => iiddeps do |t|
+        tsfile = "#{t.name}@#{Time.now.utc.to_i}"
+        build  = Docker::Build.new(options: build_options, path: path, &block)
         build.with_defaults(iidfile: tsfile, tag: tag, target: target)
         sh build.to_s
         cp tsfile, iidfile
@@ -232,7 +247,7 @@ module Rum
     def stage_shell(name, iidfile)
       desc "Shell into `#{name}` stage"
       task task_name(shell: name), [:shell] => iidfile do |t,args|
-        digest = File.read(iidfile)
+        digest = File.read(t.prereqs.first)
         shell  = args.any? ? args.to_a.join(" ") : "/bin/sh"
         run    = Docker::Run.new(options: run_options)
           .entrypoint(shell)
@@ -250,7 +265,7 @@ module Rum
       # Clean stage image
       desc "Remove any temporary images and products through `#{name}` stage"
       task task_name(clean: name) do
-        if File.exist? iidfile
+        if File.exist?(iidfile)
           sh "docker", "image", "rm", "--force", File.read(iidfile)
           rm_rf iidfile
         end

data/lib/rumrunner/version.rb

@@ -1,5 +1,5 @@
 module Rum
   ##
   # Rum Runner gem version.
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumrunner
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Alexander Mancevice
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-03 00:00:00.000000000 Z
+date: 2019-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -104,6 +104,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - bin/rum
 - lib/rumrunner.rb
 - lib/rumrunner/application.rb
@@ -131,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Rum Runner is a Rake-based utility for building projects with multi-stage