rumrunner 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14bdd585158d5a24f0caa7868eeb5e8ef19bd54055950839f6dce9e6b134435d
-  data.tar.gz: 240eab4bc1a0abaf9ba38e431f2d01af211a37b601c0ae3e2f764f858a2d04e0
+  metadata.gz: ccce65ebe39fca8b6c649ee4584cc97763ff0f0341434b810f92b3de7b498157
+  data.tar.gz: 1f679cd595b16cda478a2b3b416e8040c17ec84fe889f9e969807a25435d6850
 SHA512:
-  metadata.gz: 93761c6971fe01063ae6c91f26a2ee19c2bbbab0a52e8027d5d0c2536f7f5201f6cfa0cd4d41ff9b3efd195d3392b1083c62b7449696f995bef062a69c8112ef
-  data.tar.gz: c867c322254c754b275f90d66b5ed10f5082ca6185b7e59e24d24b7e4a5403e3e299aa9736df26ffeed6efdb859eb6d50916ab3743ec0099817d4e861aad1190
+  metadata.gz: c4252be1a723094c039c2a4c8b15e0bde5947c3e967f1486653b71f36af91c5be08c944f58ce2c3a7eb998f9159abb81e2b2be7642c23284bc437ba4f48d596b
+  data.tar.gz: 1a79e2c3b769db27f089c92ce90fa9ea3aebe7fd2218f5e7db5c34ac91157e5d49cff8d51e998cbad044e948204aedf9ffac115f9ab6618d19114ff7c4a955a3

data/README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://travis-ci.com/amancevice/rumrunner.svg?branch=master)](https://travis-ci.com/amancevice/rumrunner)
 [![codecov](https://codecov.io/gh/amancevice/rumrunner/branch/master/graph/badge.svg)](https://codecov.io/gh/amancevice/rumrunner)
+[![Gem Version](https://badge.fury.io/rb/rumrunner.svg)](https://badge.fury.io/rb/rumrunner)
 
 Rum Runner is a Rake-based utility for building multi-stage Dockerfiles.
 
@@ -10,9 +11,10 @@ Users can pair a multi-stage Dockerfile with a Rumfile that uses a Rake-like DSL
 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:
-* 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.
+* 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
@@ -29,7 +31,7 @@ gem install rumrunner
 
 ## Quickstart
 
-Use the helper `Rum.init` to create a template Rumfile for your project:
+Use the `Rum.init` helper to create a template Rumfile for your project:
 
 ```bash
 # Install the gem
@@ -66,13 +68,17 @@ Create `Rumfile` and describe your build:
 rum :image_name do
   tag "1.2.3"
 
-  stage :build           # => docker build --target build  --tag image_name:1.2.3-build .
-  stage :test => :build  # => docker build --target test   --tag image_name:1.2.3-test .
-  stage :deploy => :test # => docker build --target deploy --tag image_name:1.2.3-deploy .
+  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 `bundle exec rum --tasks` to view the installed tasks:
+Run `rum --tasks` to view the installed tasks:
 
 ```bash
 rum build                # Build `build` stage
@@ -88,22 +94,32 @@ rum test:clean           # Remove any temporary images and products from `test`
 rum test:shell[shell]    # Shell into `test` stage
 ```
 
-Run the `<stage>` task to build the image up to that stage and cache the image digest.
+## Naming Convention
 
-Run the `<stage>:shell` task to build the image and then shell into an instance of the image running as a temporary container.
+The name of the images are taken from the first argument to the main block and appended with the name of the stage.
 
-The default shell is `/bin/sh`, but this can be overridden at runtime with the task arg, eg `bundle exec rum build:shell[/bin/bash]`
-
-The name of the images are taken from the name of the initial block and appended with the name of the stage. The above example would build:
+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
+```
+
+## 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 |c|
+rum :image_name => "tmp" do
   # ...
 end
 ```
@@ -119,16 +135,25 @@ rum :image_name do
   build :fizz do
     tag  "image_name"
     path "."
-  end # => docker build --tag image_name .
+  end
 
   run :buzz do
     rm    true
     image "image_name"
     cmd   %w{echo hello}
-  end # => docker run --rm image_name echo hello
+  end
+
+  # rake fizz => docker build --tag image_name .
+  # rake buzz => docker run --rm 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`.
+
 ## 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.
@@ -137,15 +162,46 @@ The `env` method can be invoked in the `rum` block to declare a value that will
 rum :image_name do
   env :FIZZ => :BUZZ
 
-  stage :build # => docker build --build-arg FIZZ=BUZZ ...
+  stage :build
+
+  artifact "pkg.zip" => :build
+
+  # rum build   => docker build --build-arg FIZZ=BUZZ ...
+  # rum pkg.zip => docker run --env 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]`
+
+## 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
 
-  artifact "pkg.zip" => :build # => docker run --env FIZZ=BUZZ ...
+  # rum dev => docker run --entrypoint /bin/zsh --volume $PWD:/var/task/ ...
 end
 ```
 
 ## Customize Stages
 
-Stages can be customized with blocks. Methods invoked on the stage are (with a few exceptions) passed onto the `docker build` command.
+Stages can be customized with blocks:
 
 ```ruby
 rum :image_name do
@@ -164,6 +220,8 @@ rum :image_name do
 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.
@@ -189,35 +247,42 @@ rum :image_name do
 end
 ```
 
-## Customize Shells
+Methods invoked inside the artifact block are interpreted as options for the eventual `docker run` command.
 
-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.
+## Default Task
 
-Customize the shell for a stage with the `shell` method:
+Use the `default` method to set a default task when running the bare `rum` executable:
 
 ```ruby
 rum :image_name do
-  stage :dev
+  stage :build
 
-  shell :dev do
-    entrypoint "/bin/zsh"
-    rm         false
-    volume     "#{Dir.pwd}:/var/task/"
-  end
+  artifact "package.zip" => :build
+
+  default "package.zip"
 end
 ```
 
-## Default Task
-
-Use the `default` method to set a default task when running `bundle exec rum`:
+## 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
-rum :image_name do
-  stage :build
+# ./Rakefile
 
-  artifact "package.zip" => :build
+require "rumrunner"
 
-  default "package.zip"
+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/init.rb

@@ -14,17 +14,14 @@ module Rum
 
       # Put stages
       if File.exists? "Dockerfile"
-        lines  = File.read("Dockerfile").scan(/^FROM .*?$/)
-        stages = lines.each_with_index.map do |line, i|
-          line.scan(/ AS (.*?)$/).flatten.first || i.to_s
-        end
+        stages = File.read("Dockerfile").scan(/^FROM .*? AS (.*?)$/).flatten
         stages.reverse.zip(stages.reverse[1..-1]).reverse.each do |stage, dep|
           if dep.nil?
             stdout.write "  stage :\"#{stage}\"\n"
           else
             stdout.write "  stage :\"#{stage}\" => :\"#{dep}\"\n"
           end
-        end
+        end unless stages.empty?
       end
 
       # Fin

data/lib/rumrunner/version.rb

@@ -1,3 +1,3 @@
 module Rum
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumrunner
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Alexander Mancevice
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-22 00:00:00.000000000 Z
+date: 2019-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -118,9 +118,10 @@ description: |
   specific stages for debugging, and export artifacts from built containers.
 
   Rum Runner has the following features:
-  * 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.
+  * 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