docker-compose 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a06d21989982bb658ca42414f0a20e6e511263f6
+  data.tar.gz: 94d12b911c12197da022fe880548d68f80225182
+SHA512:
+  metadata.gz: 400d618d335ebb064edccbb21f074c66d1b5e82ba4b6f5a93b69ac1227cab19438df7e23ea94529f40f5598405fcd4834234881ffdc011a7c00f0d00d0467919
+  data.tar.gz: 180aac4998d6a1ed559f006a617a987e0ea61aa0904c9030de8ba9698f23f254b08ee907aa613b12ca79f1863a61e761668388f1e4f6d8efa816bf6b13d7b6d9

data/.gitignore

@@ -0,0 +1,11 @@
+/.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

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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:
+
+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,154 @@
+# Docker::Compose
+
+This is a Ruby OOP wrapper for the [docker-compose](https://github.com/docker/compose)
+container orchestration tool from Docker Inc. It also contains some features that
+layer nicely on top of docker-compose to enhance your productivity.
+
+Distinctive features of this gem:
+
+1) Simulates environment-variable substitution in the style of docker-compose
+   1.5; sequences such as ${FOO} in your YML will be replaced with the
+   corresponding environment variable. (This feature will go away once 1.5
+   is released.)
+
+2) Environment-variable mapping that allows you to export environment variables
+   into your _host_ that point to network services published by containers.
+
+Throughout this documentation we will refer to this gem as `Docker::Compose`
+as opposed to the `docker-compose` tool that this gem wraps.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'docker-compose'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install docker-compose
+
+## Usage
+
+### Invoking from Ruby code
+
+```ruby
+require 'docker/compose'
+
+# Create a new session in Dir.pwd using the file "docker-compose.yml"
+# for fine-grained control over options, see Docker::Compose::Session#new
+compose = Docker::Compose.new
+
+compose.version
+
+compose.up(detached:true)
+```
+
+### Invoking from Rake
+
+Open your Rakefile and add the Docker::Compose tasks.
+
+```ruby
+require 'docker/compose/rake_tasks'
+
+Docker::Compose::RakeTasks.new do |tasks|
+    # customize by calling setter methods of tasks;
+    # see the class documentation for details
+end
+
+```
+
+Notice that `rake -T` now has a few additional tasks for invoking gem
+functionality. You can `docker:compose:env` to print bash export statements
+for host-to-container environment mapping; you can `docker:compose:up` or
+`docker:compose:stop` to start and stop containers.
+
+The `docker-compose` command is a perfectly valid way to start
+and stop containers, but the gem provides some env-substitution functionality
+for your YML files that will be built into docker-compose 1.5 but is not
+released yet. If your YML contains `${ENV}` references, i.e. in order to
+point your containers at network services running on the host, then you must
+invoke docker-compose through Rake in order to peform the substitution.
+
+### Mapping container IPs and ports
+
+Assuming that your app accepts its configuration in the form of environment
+variables, you can use the `docker:compose:env` to export environment values
+into your bash shell that point to services running inside containers. This
+allows you to run the app on your host (for easier debugging and code editing)
+but let it communicate with services running inside containers.
+
+Docker::Compose uses a heuristic to figure out which IP your services
+are actually reachable at; the heuristic works regardless whether you are
+running "bare" docker daemon on localhost, communicating with a docker-machine
+instance, or even using a cloud-hosted docker machine!
+
+As a trivial example, let's say that your `docker-compose.yml` contains one
+service, the database that your app needs in order to run.
+
+```yaml
+db:
+  image: mysql:latest
+  environment:
+    MYSQL_DATABASE: myapp_development
+    MYSQL_ROOT_PASSWORD: opensesame
+  ports:
+    - "3306"
+
+```
+
+Your app needs two inputs, `DATABASE_HOST` and `DATABASE_PORT`. You can specify
+this in the env section of the Rake task:
+
+```ruby
+Docker::Compose::RakeTasks.new do |tasks|
+    tasks.env = {
+        'DATABASE_HOST' => 'db:[3306]'
+        'DATABASE_PORT' => '[db]:3306'
+    }
+end
+```
+
+(If I had a `DATABASE_URL` input, I could provide a URL such as
+`mysql://db/myapp_development`; Docker::Compose would parse the URL and replace
+the hostname and port appropriately.)
+
+Now, I can run my services, ask Docker::Compose to map the environment values
+to the actual IP and port that `db` has been published to, and run my app:
+
+```bash
+user@machine$ docker-compose up -d
+
+# This prints bash code resembling the following:
+#   export DATABASE_HOST=127.0.0.1
+#   export DATABASE_PORT=34387
+# We eval it, which makes the variables available to our shell and to all
+# subprocesses.
+user@machine$ eval "$(bundle exec rake docker:compose:env)"
+
+user@machine$ bundle exec rackup
+```
+
+To learn more about mapping, read the class documentation for
+`Docker::Compose::Mapper`.
+
+## 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
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/xeger/docker-compose. 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

@@ -0,0 +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,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "docker/compose"
+
+# 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
+
+require "irb"
+IRB.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-compose.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'docker/compose/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "docker-compose"
+  spec.version       = Docker::Compose::VERSION
+  spec.authors       = ["Tony Spataro"]
+  spec.email         = ["xeger@xeger.net"]
+
+  spec.summary       = %q{Wrapper docker-compose with added Rake smarts.}
+  spec.description   = %q{Provides an OOP interface to docker-compose and facilitates container-to-host and host-to-container networking.}
+  spec.homepage      = "https://github.com/xeger/docker-compose"
+  spec.license       = "MIT"
+
+  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.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

data/lib/docker/compose.rb

@@ -0,0 +1,14 @@
+require_relative 'compose/version'
+require_relative 'compose/shell'
+require_relative 'compose/session'
+require_relative 'compose/net_info'
+require_relative 'compose/mapper'
+
+module Docker
+  module Compose
+    # Create a new session.
+    def self.new
+      Session.new
+    end
+  end
+end

data/lib/docker/compose/future/session.rb

@@ -0,0 +1,90 @@
+require 'yaml'
+
+module Docker::Compose::Future
+  module Session
+    # Pattern that matches an environment substitution in a docker-compose YML
+    # file.
+    # @see #substitute
+    SUBSTITUTION = /\$\{([A-Z0-9:_-]+)\}/
+
+    # Hook in env-var substitution by aliasing a method chain for run!
+    def self.included(host)
+      done = host.instance_methods.include?(:run_without_substitution!)
+      host.instance_eval do
+        alias_method :run_without_substitution!, :run!
+        alias_method :run!, :run_with_substitution!
+      end unless done
+    end
+
+    # Read docker-compose YML; perform environment variable substitution;
+    # write a temp file; invoke run! with the new file; delete the temp
+    # file afterward.
+    #
+    # This is a complete reimplementation of run! and we only alias the original
+    # to be good citizens.
+    def run_with_substitution!(*cmd)
+      temp = nil
+      project = File.basename(@dir)
+
+      # Find and purge the 'file' flag if it exists; otherwise assume we will
+      # substitute our default (session) file.
+      fn = nil
+      cmd.each do |item|
+        fn ||= item.delete(:file) if item.is_a?(Hash)
+      end
+      fn ||= @file
+
+      # Rewrite YML if the file exists and the file:false "flag" wasn't
+      # explicitly passed to us.
+      Dir.chdir(@dir) do
+        yml = YAML.load(File.read(fn))
+        yml = substitute(yml)
+        temp = Tempfile.new(fn, @dir)
+        temp.write(YAML.dump(yml))
+        temp.close
+
+        project_opts = {
+          file: temp.path,
+          project: File.basename(@dir)
+        }
+
+        result, output =
+          @shell.command('docker-compose', project_opts, *cmd)
+        (result == 0) || raise(RuntimeError,
+                               "#{cmd.first} failed with status #{result}")
+        output
+      end
+    ensure
+      temp.unlink if temp
+    end
+
+    # Simulate the behavior of docker-compose 1.5: replace "${VAR}" sequences
+    # with the values of environment variables. Perform this recursively if
+    # data is a Hash or Array.
+    #
+    #
+    # @param [Hash,Array,String,Object] data
+    # @return [Hash,Array,String,Object] data with all ${ENV} references substituted
+    private def substitute(data)
+      case data
+      when Hash
+        result = {}
+        data.each_pair { |k, v| result[k] = substitute(v) }
+      when Array
+        result = []
+        data.each { |v| result << substitute(v) }
+      when String
+        result = data
+        while (match = SUBSTITUTION.match(result))
+          var = match[1]
+          repl = format("${%s}", var)
+          result.gsub!(repl, ENV[var])
+        end
+      else
+        result = data
+      end
+
+      result
+    end
+  end
+end

data/lib/docker/compose/mapper.rb

@@ -0,0 +1,95 @@
+module Docker::Compose
+  # Uses a Session to discover information about services' IP addresses and
+  # ports as reachable from the host, then
+  class Mapper
+    # Pattern that matches an "elided" host or port that should be omitted from
+    # output, but is needed to identify a specific container and port.
+    ELIDED          = /^\[.+\]$/.freeze
+
+    # Regexp that can be used with gsub to strip elision marks
+    REMOVE_ELIDED   = /[\[\]]/.freeze
+
+    BadSubstitution = Class.new(StandardError)
+    NoService       = Class.new(RuntimeError)
+
+    # Create an instance of Mapper
+    # @param [Docker::Compose::Session] session
+    # @param [String] host_ip IPv4 address of the host that is publishing
+    #   Docker services (i.e. the `DOCKER_HOST` hostname or IP if you are using
+    #   a non-clustered Docker environment)
+    # @param [Boolean] strict if true, raise BadSubstitution when unrecognized
+    #        syntax is passed to #map; if false, simply return the value without
+    #        substituting anything
+    def initialize(session, host_ip, strict:true)
+      @session = session
+      @host_ip = host_ip
+      @strict  = strict
+    end
+
+    # Substitute service hostnames and ports that appear in a URL or a
+    # host:port string. If either component of a host:port string is
+    # surrounded by square brackets, "elide" that component, removing it
+    # from the result but using it to find the correct service and port.
+    #
+    # @example map MySQL on local docker host with 3306 published to 13847
+    #   map("tcp://db:3306") # => "tcp://127.0.0.1:13847"
+    #
+    # @example map just the hostname of MySQL on local docker host
+    #   map("db:[3306]") # => "127.0.0.1"
+    #
+    # @example map just the port of MySQL on local docker host
+    #   map("[db]:3306") # => "13847"
+    #
+    # @param [String] value a URI or a host:port pair
+    #
+    # @raise [BadSubstitution] if a substitution string can't be parsed
+    # @raise [NoService] if service is not up or does not publish port
+    def map(value)
+      uri = URI.parse(value) rescue nil
+      pair = value.split(':')
+
+      if uri && uri.scheme && uri.host
+        # absolute URI with scheme, authority, etc
+        uri.port = published_port(uri.host, uri.port)
+        uri.host = @host_ip
+        return uri.to_s
+      elsif pair.size == 2
+        # "host:port" pair; three sub-cases...
+        if pair.first =~ ELIDED
+          # output only the port
+          service = pair.first.gsub(REMOVE_ELIDED, '')
+          port = published_port(service, pair.last)
+          return port.to_s
+        elsif pair.last =~ ELIDED
+          # output only the hostname; resolve the port anyway to ensure that
+          # the service is running.
+          service = pair.first
+          port = pair.last.gsub(REMOVE_ELIDED, '')
+          published_port(service, port)
+          return @host_ip
+        else
+          # output port:hostname pair
+          port = published_port(pair.first, pair.last)
+          return "#{@host_ip}:#{port}"
+        end
+      elsif @strict
+        raise BadSubstitution, "Can't understand '#{value}'"
+      else
+        return value
+      end
+    end
+
+    # Figure out which host port a given service's port has been published to,
+    # and/or whether that service is running. Cannot distinguish between the
+    # "service not running" case and the "container port not published" case!
+    #
+    # @raise [NoService] if service is not up or does not publish port
+    # @return [Integer] host port number, or nil if port not published
+    def published_port(service, port)
+      result = @session.port(service, port)
+      Integer(result.split(':').last.gsub("\n", ""))
+    rescue RuntimeError
+      raise NoService, "Service '#{service}' not running, or does not publish port '#{port}'"
+    end
+  end
+end

data/lib/docker/compose/net_info.rb

@@ -0,0 +1,88 @@
+module Docker::Compose
+  # Utility that gathers information about the relationship between the host
+  # on which the Ruby VM is running and the docker host, then makes an
+  # guess about the mutually routable IP addresses of each.
+  #
+  # This information can be used to tell containers how to connect to ports on
+  # the local host, or conversely to tell the local host how to connect to ports
+  # published by containers running on the docker host.
+  #
+  # The heuristic works for most cases encountered in the wild, including:
+  #   - DOCKER_HOST is unset (assume daemon listening on 127.0.0.1)
+  #   - DOCKER_HOST points to a socket (assume 127.0.0.1)
+  #   - DOCKER_HOST points to a tcp, http or https address
+  class NetInfo
+    # Determine IP addresses of the local host's network interfaces.
+    #
+    # @return [Array] list of String dotted-quad IPv4 addresses
+    def self.ipv4_interfaces
+      Socket.getifaddrs
+        .map { |i| i.addr.ip_address if i.addr && i.addr.ipv4? }.compact
+    end
+
+    # Create a new instance of this class.
+    # @param [String] docker_host a URI pointing to the docker host
+    # @param [Array] list of String dotted-quad IPv4 addresses of local host
+    def initialize(docker_host=ENV['DOCKER_HOST'],
+                   my_ips=self.class.ipv4_interfaces)
+      docker_host ||= 'unix:/var/run/docker.sock'
+      @docker_url = URI.parse(docker_host)
+      @my_ips = my_ips
+    end
+
+    # Examine local host's network interfaces; figure out which one is most
+    # likely to share a route with the given IP address. If no IP address
+    # is specified, figure out which IP the Docker daemon is reachable on
+    # and use that as the target IP.
+    #
+    # @param [String] target_ip IPv4 address of target
+    #
+    # @return [String] IPv4 address of host machine that _may_ be reachable from
+    #   Docker machine
+    def host_routable_ip(target_ip=docker_routable_ip)
+      best_match  = ''
+      best_prefix = 0
+
+      target_cps = target_ip.codepoints
+
+      @my_ips.each do |my_ip|
+        ip_cps = my_ip.codepoints
+        prefix = 0
+        ip_cps.each_with_index do |cp, i|
+          break unless target_cps[i] == cp
+          prefix = i
+        end
+
+        if prefix > best_prefix
+          best_match = my_ip
+          best_prefix = prefix
+        end
+      end
+
+      best_match
+    end
+
+    # Figure out the likely IP address of the host pointed to by
+    # self.docker_url.
+    #
+    # @return [String] host-reachable IPv4 address of docker host
+    def docker_routable_ip
+      case @docker_url.scheme
+      when 'tcp', 'http', 'https'
+        docker_dns = @docker_url.host
+        docker_port = @docker_url.port || 2376
+      else
+        # Cheap trick: for unix or other protocols, assume docker daemon
+        # is listening on 127.0.0.1:2376
+        docker_dns = 'localhost'
+        docker_port = 2376
+      end
+
+      addr = Addrinfo.getaddrinfo(
+        docker_dns, docker_port,
+        Socket::AF_INET, Socket::SOCK_STREAM).first
+
+      addr && addr.ip_address
+    end
+  end
+end

data/lib/docker/compose/rake_tasks.rb

@@ -0,0 +1,158 @@
+require 'rake/tasklib'
+
+# In case this file is required directly
+require 'docker/compose'
+
+module Docker::Compose
+  class RakeTasks < Rake::TaskLib
+    # Set the directory in which docker-compose commands will be run. Default
+    # is the directory in which Rakefile is located.
+    #
+    # @return [String]
+    attr_accessor :dir
+
+    # Set the name of the docker-compose file. Default is`docker-compose.yml`.
+    # @return [String]
+    attr_accessor :file
+
+    # Provide a mapping of environment variables that should be set in the
+    # _host_ shell for docker:compose:env or docker:compose:server.
+    # The values of the environment variables can refer to names of services
+    # and ports defined in the docker-compose file, and this gem will query
+    # docker-compose to find out which host IP and port the services are
+    # reachable on. This allows components running on the host to connect to
+    # services running inside containers.
+    #
+    # @see Docker::Compose::Mapper for information about the substitution syntax
+    attr_accessor :env
+
+    # Extra environment variables that should be set before invoking the command
+    # specified for docker:compose:server. These are set _in addition_ to env
+    # (and should be disjoint from env), and do not necessarily need to map the
+    # location of a container; they can be simple extra env values that are
+    # useful to change the server's behavior when it runs in cooperation
+    # with containers.
+    #
+    # If there is overlap between env and server_env, then keys of server_env
+    # will "win"; they are set last.
+    attr_accessor :server_env
+
+    # Command to exec on the _host_ when someone invokes docker:compose:server.
+    # This is used to start up all containers and then run a server that
+    # depends on them and is properly linked to them.
+    attr_accessor :server
+
+    # Construct Rake wrapper tasks for docker-compose. If a block is given,
+    # yield self to the block before defining any tasks so their behavior
+    # can be configured by calling #env=, #file= and so forth.
+    def initialize
+      self.dir = Rake.application.original_dir
+      self.file = 'docker-compose.yml'
+      self.env = {}
+      self.server_env = {}
+      yield self if block_given?
+
+      @shell = Docker::Compose::Shell.new
+      @session = Docker::Compose::Session.new(@shell, dir:dir, file:file)
+      @net_info = Docker::Compose::NetInfo.new
+
+      define
+    end
+
+    private def define
+      namespace :docker do
+        namespace :compose do
+          desc 'Print bash exports with IP/ports of running services'
+          task :env do
+            @shell.interactive = false # suppress useless 'port' output
+
+            if Rake.application.top_level_tasks.include? 'docker:compose:env'
+              # This task is being run as top-level; print some bash export
+              # statements or usage information depending on whether STDOUT
+              # is a tty.
+              if STDOUT.tty?
+                print_usage
+              else
+                export_env(print:true)
+              end
+            else
+              # This task is a dependency of something else; just export the
+              # environment variables for use in-process by other Rake tasks.
+              export_env(print:false)
+            end
+          end
+
+          desc 'Launch services needed to run this application'
+          task :up do
+            @shell.interactive = true # let user see what's happening
+            @session.up(detached:true)
+          end
+
+          desc 'Tail logs of all running services'
+          task :logs do
+            @session.logs
+          end
+
+          desc 'Stop services needed to run this application'
+          task :stop do
+            @session.stop
+          end
+
+          desc 'Run application on the host, linked to services in containers'
+          task :server => ['docker:compose:up', 'docker:compose:env'] do
+            exec(self.server)
+          end
+        end
+      end
+    end
+
+    # Substitute and set environment variables that point to network ports
+    # published by docker-compose services. Optionally also print bash export
+    # statements so this information can be made available to a user's shell.
+    private def export_env(print:)
+      # First, do env substitutions in strict mode; don't catch BadSubstitution
+      # so the caller knows when he has a bogus value
+      mapper = Docker::Compose::Mapper.new(@session,
+                                           @net_info.docker_routable_ip)
+      self.env.each_pair do |k, v|
+        begin
+          v = mapper.map(v)
+          ENV[k] = v
+          print_env(k, v) if print
+        rescue Docker::Compose::Mapper::NoService
+          ENV[k] = nil
+          print_env(k, nil) if print
+        end
+      end
+
+      # Next, do server substitutions in non-strict mode since server_env
+      # can contain arbitrary values.
+      mapper = Docker::Compose::Mapper.new(@session,
+                                           @net_info.docker_routable_ip,
+                                           strict:false)
+      self.server_env.each_pair do |k, v|
+        v = mapper.map(v)
+        ENV[k] = v
+        print_env(k, v) if print
+      end
+    end
+
+    # Print a bash export or unset statement
+    private def print_env(k, v)
+      if v
+        puts format('export %s=%s', k, v)
+      else
+        puts format('unset %s # service not running', k)
+      end
+    end
+
+    private def print_usage
+      be = 'bundle exec ' if defined?(Bundler)
+      puts "# To export container network locations to your environment:"
+      puts %Q{eval "$(#{be}rake docker:compose:env)"}
+      puts
+      puts '# To learn which environment variables we will export:'
+      puts %Q{echo "$(#{be}rake docker:compose:env)"}
+    end
+  end
+end

data/lib/docker/compose/session.rb

@@ -0,0 +1,113 @@
+require 'docker/compose/future/session'
+
+module Docker::Compose
+  # A Ruby OOP interface to a docker-compose session. A session is bound to
+  # a particular directory and docker-compose file (which are set at initialize
+  # time) and invokes whichever docker-compose command is resident in $PATH.
+  #
+  # Run docker-compose commands by calling instance methods of this class and
+  # passing 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-compose CLI, and that options are sometimes renamed
+  # for clarity, e.g. the "-d" flag always becomes the "detached:" kwarg.
+  class Session
+    def initialize(shell=Docker::Compose::Shell.new,
+                   dir:Dir.pwd, file:'docker-compose.yml')
+      @shell = shell
+      @dir = dir
+      @file = file
+    end
+
+    # Monitor the logs of one or more containers.
+    # @param [Array] services list of String service names to show logs for
+    # @return [true] always returns true
+    # @raise [RuntimeError] if command fails
+    def logs(*services)
+      run!('logs', services)
+      true
+    end
+
+    # Idempotently run services in the project,
+    # @param [Array] services list of String service names to run
+    # @param [Boolean] detached if true, to start services in the background;
+    #   otherwise, monitor logs in the foreground and shutdown on Ctrl+C
+    # @param [Integer] timeout how long to wait for each service to stostart
+    # @param [Boolean] no_build if true, to skip building images for services
+    #   that have a `build:` instruction in the docker-compose file
+    # @param [Boolean] no_deps if true, just run specified services without
+    #   running the services that they depend on
+    # @return [true] always returns true
+    # @raise [RuntimeError] if command fails
+    def up(*services,
+           detached:false, timeout:10, no_build:false, no_deps:false)
+      run!('up',
+           {d:detached, timeout:timeout, no_build:no_build, no_deps:no_deps},
+           services)
+      true
+    end
+
+    # Stop running services.
+    # @param [Array] services list of String service names to stop
+    # @param [Integer] timeout how long to wait for each service to stop
+    def stop(*services, timeout:10)
+      run!('stop', {timeout:timeout}, services)
+    end
+
+    # Figure out which host a port a given service port has been published to.
+    # @param [String] service name of service from docker-compose.yml
+    # @param [Integer] port number of port
+    # @param [String] protocol 'tcp' or 'udp'
+    # @param [Integer] index of container (if multiple instances running)
+    def port(service, port, protocol:'tcp', index:1)
+      run!('port', {protocol:protocol, index:index}, service, port)
+    end
+
+    # Determine the installed version of docker-compose.
+    # @param [Boolean] short whether to return terse version information
+    # @return [String, Hash] if short==true, returns a version string;
+    #   otherwise, returns a Hash of component names to version strings
+    # @raise [RuntimeError] if command fails
+    def version(short:false)
+      result = run!('version', short:short, file:false, dir:false)
+
+      if short
+        result.strip
+      else
+        lines = result.split("\n")
+        lines.inject({}) do |h, line|
+          kv = line.split(/: +/, 2)
+          h[kv.first] = kv.last
+          h
+        end
+      end
+    end
+
+    # Run a docker-compose command without validating that the CLI parameters
+    # make sense. Prepend project and file options if suitable.
+    #
+    # @see Docker::Compose::Shell#command
+    #
+    # @param [Array] cmd subcommand words and options in the format accepted by
+    #   Shell#command
+    # @return [String] output of the command
+    # @raise [RuntimeError] if command fails
+    def run!(*cmd)
+      project_opts = {
+        file: @file
+      }
+
+      Dir.chdir(@dir) do
+        result, output =
+          @shell.command('docker-compose', project_opts, *cmd)
+        (result == 0) || raise(RuntimeError,
+                               "#{cmd.first} failed with status #{result}")
+        output
+      end
+    end
+
+    # Simulate behaviors from Docker 1.5
+    include Docker::Compose::Future::Session
+  end
+end

data/lib/docker/compose/shell.rb

@@ -0,0 +1,165 @@
+require 'open3'
+
+module Docker::Compose
+  # An easy-to-use interface for invoking commands and capturing their output.
+  # Instances of Shell can be interactive, which prints the command's output
+  # to the terminal and also allows the user to interact with the command.
+  class Shell
+    # If true, commands run in the shell will have their stdio streams tied
+    # to the parent process so the user can view their output and send input
+    # to them. Commands' stdout is still captured normally when they are
+    # interactive.
+    #
+    # Note that interactivity doesn't work very well because we use popen,
+    # which uses pipes to communicate with the child process and pipes have
+    # a fixed buffer size; the displayed output tends to "lag" behind the
+    # actual program, and bytes sent to stdin may not arrive until you send
+    # a lot of them!
+    #
+    # TODO: solve pipe buffering issues, perhaps with a pty...
+    #
+    # @return [Boolean]
+    attr_accessor :interactive
+
+    # Convert Ruby keyword arguments into CLI parameters that are compatible
+    # with the syntax of golang's flags package.
+    #
+    # Options are translated to CLI parameters using the following convention:
+    # 1) Snake-case symbols are hyphenated, e.g. :no_foo => "--no-foo"
+    # 2) boolean values indicate a CLI flag; true includes the flag, false or nil omits it
+    # 3) other values indicate a CLI option that has a value.
+    # 4) single character values are passed as short options e.g. "-X V"
+    # 5) multi-character values are passed as long options e.g. "--XXX=V"
+    #
+    def self.options(**opts)
+      flags = []
+
+      # Transform opts into golang flags-style command line parameters;
+      # append them to the command.
+      opts.each do |kw, arg|
+        if kw.length == 1
+          if arg == true
+            # true: boolean flag
+            flags << "-#{kw}"
+          elsif arg
+            # truthey: option that has a value
+            flags << "-#{kw}" << arg.to_s
+          else
+            # falsey: omit boolean flag
+          end
+        else
+          kw = kw.to_s.gsub('_','-')
+          if arg == true
+            # true: boolean flag
+            flags << "--#{kw}"
+          elsif arg
+            # truthey: option that has a value
+            flags << "--#{kw}=#{arg}"
+          else
+            # falsey: omit boolean flag
+          end
+        end
+      end
+
+      flags
+    end
+
+    # Create an instance of Shell.
+    def initialize
+      @interactive = false
+    end
+
+    # Run a shell command whose arguments and flags are expressed using some
+    # Rubyish sugar. This method accepts an arbitrary number of positional
+    # parameters; each parameter can be a Hash, an array, or a simple Object.
+    # Arrays and simple objects are appended to argv as "bare" words; Hashes
+    # are translated to golang flags and then appended to argv.
+    #
+    # @example Run docker-compose with complex parameters
+    #   command('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')
+    #
+    # @see #options for information on Hash-to-flag translation
+    def command(*cmd)
+      argv = []
+
+      cmd.each do |item|
+        case item
+        when Array
+          # list of words to append to argv
+          argv.concat(item.map { |e| e.to_s })
+        when Hash
+          # list of options to convert to CLI parameters
+          argv.concat(self.class.options(item))
+        else
+          # single word to append to argv
+          argv << item.to_s
+        end
+      end
+
+      run(argv)
+    end
+
+    # Run a shell command. Perform no translation or substitution. Return
+    # the program's exit status and stdout.
+    #
+    # @param [Array] argv command to run; argv[0] is program name and the
+    #   remaining elements are parameters and flags
+    # @return [Array] a pair of Integer exitstatus and String output
+    private def run(argv)
+      stdin, stdout, stderr, thr = Open3.popen3(*argv)
+
+      streams = [stdout, stderr]
+
+      if @interactive
+        streams << STDIN
+      else
+        stdin.close
+      end
+
+      output = String.new.force_encoding(Encoding::BINARY)
+
+      until streams.empty? || (streams.length == 1 && streams.first == STDIN)
+        ready, _, _ = IO.select(streams, [], [], 1)
+
+        if ready && ready.include?(STDIN)
+          input = STDIN.readpartial(1_024) rescue nil
+          if input
+            stdin.write(input)
+          else
+            # our own STDIN got closed; proxy to child's stdin
+            stdin.close
+          end
+        end
+
+        if ready && ready.include?(stderr)
+          data = stderr.readpartial(1_024) rescue nil
+          if data
+            STDERR.write(data) if @interactive
+          else
+            streams.delete(stderr)
+          end
+        end
+
+        if ready && ready.include?(stdout)
+          data = stdout.readpartial(1_024) rescue nil
+          if data
+            output << data
+            STDOUT.write(data) if @interactive
+          else
+            streams.delete(stdout)
+          end
+        end
+      end
+
+      # This blocks until the process exits (which probably already happened,
+      # given that we have received EOF on its output streams).
+      status = thr.value.exitstatus
+
+      [status, output]
+    rescue Interrupt
+      # Proxy Ctrl+C to our child process
+      Process.kill('INT', thr.pid) rescue nil
+      raise
+    end
+  end
+end

data/lib/docker/compose/version.rb

@@ -0,0 +1,5 @@
+module Docker
+  module Compose
+    VERSION = "0.1.0"
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: docker-compose
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tony Spataro
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-10-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    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
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides an OOP interface to docker-compose and facilitates container-to-host
+  and host-to-container networking.
+email:
+- xeger@xeger.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- docker-compose.gemspec
+- lib/docker/compose.rb
+- lib/docker/compose/future/session.rb
+- lib/docker/compose/mapper.rb
+- lib/docker/compose/net_info.rb
+- lib/docker/compose/rake_tasks.rb
+- lib/docker/compose/session.rb
+- lib/docker/compose/shell.rb
+- lib/docker/compose/version.rb
+homepage: https://github.com/xeger/docker-compose
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Wrapper docker-compose with added Rake smarts.
+test_files: []