lux 0.9 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a59ca3dfc3b9dc7b392ba2eccb2e03fdf762a345
-  data.tar.gz: e64035da3da05c6d9ff4aafbe48d909e3bd09164
+  metadata.gz: 840ad1a2f55f5395e18d76976357486af1f860fa
+  data.tar.gz: 4b954b5fababffa6b24ead4841a9245f85308547
 SHA512:
-  metadata.gz: 3da8015452b5ed70a742a1a69951c625d632846d14b6c9ac9156f7fa19e09d0490bd0bbde71e9230fca3ceef806add3283768d0c951792e99cdb00246ee9355f
-  data.tar.gz: 0894977bcfef8ef4e769805cb1167358352b406ce3930b98389cd11dbfa2cd10b9a93d5b0b5a591f7e9e10f9b57d95a0f24a7f4df4ae83d90abd1005c5a07348
+  metadata.gz: 063f969054657465283c3407ecb61042cc9670d0ec8b6e71ae59fe53fb6dc073413cfd4226c867e295accc7a74db99023fa05a168986f59924f7584453ad8ba1
+  data.tar.gz: 1bced056319fa9ec7512b4bbe7d282d68c92bb4714e4f2eb616fc4aaabf3a791d55ee16c9b889c143092c3fba065b6253ea6d27c8a3b934d7fc7ee401470cbe5

data/README.md

@@ -9,6 +9,10 @@ Shining some light on setting up and running various Docker things.
 Lux is both a command line tool (based on Thor) and a library of useful routines
 that can be included in Rake tasks.
 
+It uses the Docker API directly via the
+[docker-api GEM](https://github.com/swipely/docker-api) and so does not require the docker
+client.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,6 +31,10 @@ Or install it yourself as:
 
 ## Usage
 
+If using a Docker server across the network, make sure that you have exported the
+environment variable `DOCKER_URL ` (which is a true URL). Note that this is different to
+the Go docker client which uses `DOCKER_HOST`.
+
 ### Command Line Tool
 
 The `lux` command simplifies a number of Docker command line operations and provides
@@ -38,62 +46,122 @@ Type: `lux help` to get started
 ### Rake Tasks
 
 When trying to write Rakefiles that start Docker containers it is useful to have a Rake
-task that represents a container image. Then you can make other tasks depend on them.
-If the task (when invoked) checks the local Docker server for the image, and
-only executes the task body if the image is not found, then you can build Docker
-dependencies elegantly into the Rakefile.
+task that represents a container image. Then you can make other tasks depend on them.  If
+the task (when invoked) checks the local Docker server for the image, and only executes
+the task body if the image is not found, or if the listed dependencies are out-of-date,
+then you can build Docker dependencies elegantly into the Rakefile.
 
-The boilerplate to do this is included in Lux as a Rake Task Generator. Here are some
-examples:
+Lux extends Rake with two new task types `dockerimage` and `container`. Both of them are
+specializations of the `file` task. They use the Docker server pointed to by the
+`DOCKER_URL` environment variable and do *not* query a remote registry.
 
-```ruby
-require 'lux/dockertasks'
+#### `dockerimage`
 
-# Define a simple task.
-# The tag will default to 'latest' and the name of the task is 'busybox'
+This checks for the existence of an image with the task name in the Docker server. It uses
+the creation date found there as the timestamp and executes the associated action if it is
+out-of-date with respect to it's dependencies. This means you can rebuild the image based
+on other dependencies (such as the Dockerfile or content).
 
-DockerImageTask.new('busybox')
+If you are using an image on a remote repository that you don't build locally then you can
+either define it and make the action a `docker pull` command or omit it altogether. In the
+former case you can then add this as a dependency to a container task to ensure that a
+running container always has the most up-to-date image. The latter case works as the
+Docker runtime will attempt to pull an image from a remote repository if it is not present
+locally.
 
-# Define a task with a tag.
-# The name of the task is 'ubuntu', the tag is 'trusty'
+#### `container`
 
-DockerImageTask.new('ubuntu:trusty')
+This checks for the existence of a running container for a particular docker image. The
+task name is a compound name of the form `containername@imagename`. If the container
+named is not running then the action block is executed, typically it will be a Docker run
+command.  If the container is already running then it's image is checked to see if that it
+is the same as specified. If not the container is destroyed and the action block executed.
+If the container image matches the requested one, then the creation date of the container
+is used as the task timestamp. This allows you to specify a dockerimage dependency and the
+container will then be restarted if the image is newer.
 
-# Define a task with a tag and a name.
-# The name of the task is 'reedy', the image is 'ubuntu' and the tag 'reedy'
+Note that you don't need a corresponding dockerimage task as the Docker runtime will
+attempt to pull an image from a remote repository if it is not present locally.
 
-DockerImageTask.new('ubuntu:reedy', :reedy)
+#### Examples
 
-# Define a task with a fully qualified image and a block.
-# The block will be executed if the image is not found locally.
-# The task object yielded has the image and tag attributes
-# as well as the usual name and description.
+```ruby
+require 'lux/docker_tasks'
 
-DockerImageTask.new('quay.io/rasputin/tools:1.0') do |t|
-  puts "You want me to build the image #{t.image}:#{t.tag}?"
-  fail "Not from here I can't..."
+desc "Build tool image if the image is not found locally"
+dockerimage 'quay.io/rasputin/tools:1.0' do |t|
+  sh "docker build -t #{t.name} ."
 end
 
-desc "Run Busybox"
-task :runb => 'busybox' do
-  sh "docker run -it busybox"
+desc "Build tool image if the image is not found or is older than the Dockerfile"
+dockerimage 'quay.io/rasputin/tools:1.0' => 'Dockerfile' do |t|
+  sh "docker build -t #{t.name} ."
 end
 
-desc "Run Ubuntu Trusty"
-task :runu => :ubuntu do
-  sh "docker run -it ubuntu:trusty /bin/bash"
+desc "Make sure we have a running tools container"
+container 'tools@quay.io/rasputin/tools:1.0' do
+  sh "docker run --name tools -d quay.io/rasputin/tools:1.0"
 end
 
-desc "Run Ubuntu Reedy"
-task :runr => :reedy do
-  sh "docker run -it ubuntu:reedy /bin/bash"
+desc "Make sure we have a running tools container with the most up-to-date image"
+container 'tools@quay.io/rasputin/tools:1.0' => 'quay.io/rasputin/tools:1.0' do
+  sh "docker run --name tools -d quay.io/rasputin/tools:1.0"
 end
 
-# Note how the task name does not include the tag
-desc "Run Tools"
-task :runt => 'quay.io/rasputin/tools' do
-  sh "docker run -it quay.io/rasputin/tools:1.0 /bin/bash"
+# A set of tasks to ensure you always have the latest version of a container
+# stored on a remote registry
+
+require 'lux/docker_tasks'
+
+desc "Always see if there is a new version of busybox"
+task :getbusybox do
+  sh "docker pull busybox"
 end
+
+desc "Create a dockerimage task so we can depend on it"
+dockerimage 'busybox' => :getbusybox
+
+desc "Always run with the latest version"
+container 'busy@busybox' => 'busybox' do
+  sh "docker run -it --name busy busybox"
+end
+
+```
+#### Tracing
+
+When the Rake trace option is enabled the destruction (or attempted destruction if it's a
+dry-run) is recorded.
+
+#### Namespaces
+
+When using the `dockerimage` and `container` tasks with explicit tags (ie. containing a semi-colon), then
+normal Rake namespace rules apply: The _repository_ name will be considered the namespace
+and the _tag_ the taskname within the namespace. If this `dockerimage` task is declared in
+the same execution alongside a matching explicit namespace and task declaration, then the
+actions will accumulate.
+
+
+```ruby
+task :default => 'busybox:greenest'
+
+dockerimage 'busybox:greenest' do
+  puts "Build busybox:greenest Docker image"
+end
+
+namespace :busybox do
+  task :greenest do
+    puts "Do the greenest task in the busybox namespace"
+  end
+end
+
+```
+
+This prints:
+
+```bash
+$ rake -f Rakefile.demo
+Build busybox:greenest Docker image
+Do the greenest task in the busybox namespace
 ```
 
 ## Development

data/lib/lux/docker_tasks.rb

@@ -0,0 +1,106 @@
+# Extend rake with file-like Docker tasks
+#
+require 'rake'
+require 'docker'
+
+module Rake
+  module DSL
+    def dockerimage(*args, &block)
+      Lux::DockerImageTask.define_task(*args, &block)
+    end
+    def container(*args, &block)
+      Lux::DockerContainerTask.define_task(*args, &block)
+    end
+  end
+end
+
+module Lux
+  class DockerImageTask < Rake::FileTask
+    # This task checks to see if the image is present in the local Docker Server
+    # If present it returns the creation date as the timestamp, if not then it
+    # returns Rake::Early. This allows dependencies to execute correctly
+    # The action block should build the container.
+    #
+    def initialize(task_name, app)
+      super(task_name, app)
+      @imagename = @name
+      @imagename += ':latest' unless @imagename.index(':')
+      @image = Docker::Image.all.select{|i| i.info['RepoTags'].include? @imagename}.first
+    end
+
+    def needed?
+      ! @image || out_of_date?(timestamp) || @application.options.build_all
+    end
+
+    def timestamp
+      if @image = Docker::Image.all.select{|i| i.info['RepoTags'].include? @imagename}.first
+        Time.at(@image.info['Created'])
+      else
+        Rake::EARLY
+      end
+    end
+  end
+
+  class DockerContainerTask < Rake::FileTask
+    # This task checks whether a named container is running from a given image.
+    # The name of the task is <container-name>@<image-name>
+    # The container name must match /?[a-zA-Z0-9_-]+
+    #
+    # If a container is already running for this image, the creation time
+    # is checked against the current image modification date.
+    # If the container is not running or out-of-date it is restarted.
+    #
+    def initialize(task_name, app)
+      super(task_name, app)
+      @containername, sep, @imagename = task_name.partition('@')
+      raise "Task #{task_name} must be name@image" if @containername.empty? or @imagename.empty?
+      @container = Docker::Container.get(@containername) rescue nil
+      @imagename += ':latest' unless @imagename.index(':')
+      @image = Docker::Image.all.select{|i| i.info['RepoTags'].include? @imagename}.first
+    end
+
+    def needed?
+      not @container or
+      @container.info["Image"] != @image.id or
+      not @container.info["State"]["Running"] or
+      out_of_date?(timestamp) or
+      @application.options.build_all
+    end
+
+    # Before the task actions are done, remove the container
+    def execute(args)
+      destroy_container("it is out-of-date") { out_of_date?(timestamp) }
+      destroy_container("it uses the wrong image") { @container.info["Image"] != @image.id }
+      destroy_container("it is not running") { not @container.info["State"]["Running"] }
+      destroy_container("it exists!") { @container }
+      super args
+    end
+
+    # Destroy the container if the block yields true
+    def destroy_container msg, &block
+      return if !@container or (block_given? and not yield)
+      application.trace "** Prepare #{name} (destroying container: #{msg})" if application.options.trace
+      return if application.options.dryrun
+      # It may be hard to kill this container, try but if something goes wrong
+      # then print a message and proceed with the action block. The start command
+      # in there will fail in a more user-friendly way.
+      begin
+        @container.stop # @container.kill(signal: 'SIGTERM') better?
+        @container.wait(10)
+        @container.delete
+      rescue Exception => e
+        puts "Exception destroying container: #{e.to_s}"
+      end
+      @container = nil
+    end
+
+    def timestamp
+      if @container = Docker::Container.get(@containername) rescue nil
+        Time.iso8601(@container.info['Created'])
+      else
+        Rake::EARLY
+      end
+    end
+  end
+
+end

data/lib/lux/version.rb

@@ -1,3 +1,3 @@
 module Lux
-  VERSION = "0.9"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: 1.0.2
 platform: ruby
 authors:
 - Nick Townsend
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-05 00:00:00.000000000 Z
+date: 2015-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -98,7 +98,7 @@ files:
 - Rakefile.test
 - bin/lux
 - lib/lux.rb
-- lib/lux/dockertasks.rb
+- lib/lux/docker_tasks.rb
 - lib/lux/version.rb
 - lux.gemspec
 homepage: https://github.com/townsen/lux

data/lib/lux/dockertasks.rb

@@ -1,64 +0,0 @@
-require 'highline/import'
-require 'rake/tasklib'
-
-# A Task Generator for Docker images
-#
-# Example:
-#   require "lux/dockertasks"
-#
-#   DockerImageTask.new('myimage') do
-#      puts "Here you can build the image"
-#   end
-#
-#   task :run => 'myimage' do
-#     sh "docker run myimage"
-#   end
-#
-class DockerImageTask < Rake::TaskLib
-
-  # The name of the task (defaults to the image)
-  attr_accessor :name
-
-  # The name of the image (if different to the task name)
-  attr_accessor :image
-
-  # Name of tag (default is latest)
-  attr_accessor :tag
-
-  # Task Description (default is 'Build Docker Image <imagename>')
-  attr_accessor :description
-
-  # The block to execute if this needs building
-  attr_accessor :build
-
-  # The image may include a tag, but the tag is never part of the name
-  # If the tag is omitted it defaults to 'latest'
-  # If a name is specified it becomes the task name.
-  #
-  def initialize(image, name=nil, &block)
-    @image, sep, @tag = image.partition(':')
-    @tag = 'latest' if @tag.empty?
-    @name = name || @image
-    @description = "Build Docker Image #{@image}:#{@tag}"
-    @build = block
-    define
-  end
-
-  def define
-    desc @description
-    task @name do
-      local_images = `docker images #{@image}`.split("\n")[1..-1].map{|l| l.split(/\s+/)}
-      local_images.select!{|i| i[1] == @tag}
-      if local_images.size == 0
-        if @build.nil?
-          HighLine.say "Build Docker Image <%=BOLD%>#{@image}:#{@tag}<%=CLEAR%> before proceeding"
-          exit 2
-        else
-          @build.call self
-        end
-      end
-    end
-    self
-  end
-
-end