docker 0.0.1 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8a5fe14311f0acab32460ca8923bab196447407f
+  data.tar.gz: 0b41e3f8300a3378bd4523d1b9f1a030229c6555
+SHA512:
+  metadata.gz: c1f63091d8bf8a553084f77e009ce5669660407856cc6ce051549d908d94f26cc95f94c4afdced54670e759042d74971ee00e7dddcb417886976f9ed4efd6800
+  data.tar.gz: c7f76f824a1b2e6e548e94f483edbe6097b478c8960cbb1494f4c1340f9b4849eca9bebad08341bf9864e3e0175764888cb443d6e9b738206cbebb0cc33829dd

data/.gitignore

@@ -1,17 +1,11 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea
+

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.2.2

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.7
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -2,3 +2,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in docker.gemspec
 gemspec
+
+group :development do
+  gem 'pry'
+  gem 'pry-byebug'
+end

data/LICENSE.txt

@@ -1,22 +1,21 @@
-Copyright (c) 2013 Vladimir Pouzanov
+The MIT License (MIT)
 
-MIT License
+Copyright (c) 2015 Tony Spataro
 
-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:
+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 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.
+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

@@ -1,12 +1,23 @@
 # Docker
 
-TODO: Write a gem description
+This is a Ruby OOP wrapper for the [Docker](https://github.com/docker)
+container management tool from Docker Inc. It wraps Docker's command-line
+interface with objects.
+
+Throughout this documentation we will refer to this gem as `docker.gem`
+as opposed to the `docker` tool that this gem wraps.
+
+### Why?
+
+
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'docker'
+```ruby
+gem 'docker'
+```
 
 And then execute:
 
@@ -18,12 +29,32 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Invoking from Ruby code
+
+```ruby
+require 'docker'
+
+# Create a new session talking to `ENV['DOCKER_HOST']`. For fine-grained
+# control over options, see Docker::Session#new
+docker = Docker.new
+
+docker.version
+
+docker.run(t:true, i:true, 'busybox', '/bin/sh')
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Bug reports and pull requests are welcome on GitHub at https://github.com/xeger/docker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -1 +1,6 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'docker'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require 'pry'
+Pry.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docker.gemspec

@@ -6,18 +6,22 @@ require 'docker/version'
 Gem::Specification.new do |spec|
   spec.name          = "docker"
   spec.version       = Docker::VERSION
-  spec.authors       = ["Vladimir Pouzanov"]
-  spec.email         = ["farcaller@gmail.com"]
-  spec.description   = "Docker wrapper to manage docker.io based lxc containers"
-  spec.summary       = "Docker wrapper to manage docker.io based lxc containers"
-  spec.homepage      = ""
+  spec.authors       = ["Tony Spataro"]
+  spec.email         = ["xeger@xeger.net"]
+
+  spec.summary       = %q{Docker CLI wrapper.}
+  spec.description   = %q{Provides an OOP interface to docker without relying on its HTTP API.}
+  spec.homepage      = "https://github.com/xeger/docker"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
+  spec.add_dependency "backticks", "~> 0.3"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
 end

data/lib/docker.rb

@@ -1,5 +1,10 @@
-require "docker/version"
+require_relative 'docker/version'
+require_relative 'docker/error'
+require_relative 'docker/session'
 
 module Docker
-  # Your code goes here...
+  # Create a new session with default options.
+  def self.new
+    Session.new
+  end
 end

data/lib/docker/error.rb

@@ -0,0 +1,16 @@
+module Docker
+  class Error < RuntimeError
+    attr_reader :status, :detail
+
+    # @param [String] cmd
+    # @param [Integer] status
+    # @param [String] detail
+    def initialize(cmd, status, detail)
+      @status = status
+      @detail = detail
+      brief = detail.split("\n").first || '(no output)'
+      message = format("'%s' failed with status %d: %s", cmd, status, brief)
+      super(message)
+    end
+  end
+end

data/lib/docker/session.rb

@@ -0,0 +1,147 @@
+require 'backticks'
+
+module Docker
+  # A Ruby OOP interface to a docker session. A session is bound to
+  # a particular docker host (which is set at initialize time)
+  # time) and invokes whichever docker command is resident in $PATH.
+  #
+  # Run docker commands by calling instance methods of this class and
+  # passing positional and kwargs that are equivalent to the CLI options
+  # you would pass to the command-line tool.
+  #
+  # Note that the Ruby command methods usually expose a _subset_ of the options
+  # allowed by the docker CLI, and that options are sometimes renamed
+  # for clarity. Each command method is extensively documented.
+  class Session
+    # @return [String] URL of the Docker host associated with this session
+    attr_reader :host
+
+    # @return [#command]
+    attr_reader :shell
+
+    def initialize(shell=Backticks::Runner.new(interactive:true), host:ENV['DOCKER_HOST'])
+      @host = host
+      @shell = shell
+    end
+
+    # Kill a running container.
+    #
+    # @param [String] container id or name of container to kill
+    # @param [String] signal Unix signal to send: KILL, TERM, QUIT, HUP, etc
+    def kill(container, signal:nil)
+      run!('kill', {signal:signal}, container)
+    end
+
+    # Run a command in a new container.
+    #
+    # @example open a busybox shell
+    #   session.run('busybox', '/bin/sh', tty:true, interactive:true)
+    #
+    # @param [String] image id or name of base image to use for container
+    # @param [Array] command_and_args optional command to run in container
+    # @param [Integer] cpu_period scheduler period (μs)
+    # @param [Integer] cpu_quota maximum runtime (μs) during one scheduler period
+    # @param [Boolean] detach run container in background and return immediately
+    # @param [Array,Hash] env environment variables; map of {K:V} pairs or list of ["K=V"] assignments
+    # @param [String] env_file name of file to read environment variables from
+    # @param [Array] expose list of Integer/String ports or port-ranges to expose to other containers e.g. 80, "1024-2048"
+    # @param [String] hostname Unix hostname inside container
+    # @param [Boolean] interactive allocate an STDIN for the container
+    # @param [Array] link list of container ids or names to link to the container
+    # @param [String] memory limit on memory consumption e.g. "640k", "32m" or "4g"
+    # @param [String] name name of container; leave blank to let Docker generate one
+    # @param [Array] publish list of Integer/String ports or port-ranges to publish to the host; use "X:Y" to map container's X to host's Y
+    # @param [Boolean] publish_all automatically publish all of container's ports to the host
+    # @param [Boolean] restart automatically restart container when it fails
+    # @param [Boolean] rm clean up container once it exits
+    # @param [Boolean] tty allocate a pseudo-TTY for the container's STDOUT
+    # @param [String] user name or uid of Unix user to run container as
+    # @param [Array] volume list of volumes to mount inside container; use "X:Y" to map host's X to container's Y
+    # @param [String] volumes_from id or name of container to import all volumes from
+    def run(image, *command_and_args,
+            add_host:[],
+            attach:[],
+            cpu_period:nil,
+            cpu_quota:nil,
+            detach:false,
+            env:{},
+            env_file:nil,
+            expose:[],
+            hostname:nil,
+            interactive:false,
+            link:[],
+            memory:nil,
+            name:nil,
+            publish:[],
+            publish_all:false,
+            restart:false,
+            rm:false,
+            tty:false,
+            user:nil,
+            volume:[],
+            volumes_from:nil)
+
+      cmd = []
+
+      # if env was provided as a hash, turn it into an array
+      env = env.map { |k, v| "#{k}=#{v}" } if env.is_a?(Hash)
+
+      # our keyword args are formatted properly for run! to handle them; echo
+      # them into the command line verbatim.
+      # TODO find a way to DRY out this repetitive mess...
+      cmd << {add_host:add_host, attach:attach, cpu_period:cpu_period,
+              cpu_quota:cpu_quota, detach:detach, env_file:env_file, env:env,
+              expose:expose, hostname:hostname, interactive:interactive,
+              link:link, memory:memory, name:name, publish:publish,
+              publish_all:publish_all, restart:restart, rm:rm, tty:tty,
+              user:user, volume:volume, volumes_from:volumes_from}
+
+      # after the options come the image and command
+      cmd << image
+      cmd.concat(command_and_args)
+
+      # return the output of `docker run` minus extra whitespace
+      run!('run', *cmd).strip
+    end
+
+    # Provide version information about the Docker client and server.
+    #
+    # @return [Hash] dictionary of strings describing version/build info
+    # @raise [Error] if command fails
+    def version
+      result = run!('version')
+
+      lines = result.split(/[\r\n]+/)
+
+      info = {}
+      prefix = ''
+
+      lines.each do |line|
+        if line =~ /^Client/
+          prefix = 'Client '
+        elsif line =~ /^Server/
+          prefix = 'Server '
+        else
+          pair = line.split(':',2).map { |e| e.strip }
+          info["#{prefix}#{pair[0]}"] = pair[1]
+        end
+      end
+
+      info
+    end
+
+    # Run a docker command without validating that the CLI parameters
+    # make sense. Prepend implicit options if suitable.
+    #
+    # @param [Array] args command-line arguments in the format accepted by
+    #   Backticks::Runner#command
+    # @return [String] output of the command
+    # @raise [RuntimeError] if command fails
+    def run!(*args)
+      cmd = @shell.run('docker', *args).join
+      status, out, err = cmd.status, cmd.captured_output, cmd.captured_error
+      status.success? || raise(Error.new(args.first, status, err))
+      out
+    end
+  end
+end

data/lib/docker/version.rb

@@ -1,3 +1,3 @@
 module Docker
-  VERSION = "0.0.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,87 +1,116 @@
 --- !ruby/object:Gem::Specification
 name: docker
 version: !ruby/object:Gem::Version
-  version: 0.0.1
-  prerelease: 
+  version: 0.3.0
 platform: ruby
 authors:
-- Vladimir Pouzanov
+- Tony Spataro
 autorequire: 
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2013-05-01 00:00:00.000000000 Z
+date: 2016-01-03 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: backticks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Docker wrapper to manage docker.io based lxc containers
+description: Provides an OOP interface to docker without relying on its HTTP API.
 email:
-- farcaller@gmail.com
+- xeger@xeger.net
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/console
+- bin/setup
 - docker.gemspec
 - lib/docker.rb
+- lib/docker/error.rb
+- lib/docker/session.rb
 - lib/docker/version.rb
-homepage: ''
+homepage: https://github.com/xeger/docker
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.21
+rubygems_version: 2.4.5
 signing_key: 
-specification_version: 3
-summary: Docker wrapper to manage docker.io based lxc containers
+specification_version: 4
+summary: Docker CLI wrapper.
 test_files: []
-has_rdoc: