docker-compose 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: bb5c46f2fc1351385671bc66a27b8a5ae3a92769c91c2f5d3470b91f31d38e07
-  data.tar.gz: 19800f852de5921b296eda4d9e64a207ce60a6a1fc7959cfaba11965dfb9b823
+SHA1:
+  metadata.gz: a06d21989982bb658ca42414f0a20e6e511263f6
+  data.tar.gz: 94d12b911c12197da022fe880548d68f80225182
 SHA512:
-  metadata.gz: 2bf97d99fb8c03cbb2dcbd833d743ef508c7474e6833abf415a0d7534199c67d557585a55ad0dd35d58e92747d8bcada2deb4ce036e7ad86cc79929ad9239a11
-  data.tar.gz: 67f91befe87b16d4f2305bba853eff604abec12d0c3a5f63e1a38f2517838e47a2f1b2db49937630876c6acace00f9abd2f176a17974835eef45465e590217c8
+  metadata.gz: 400d618d335ebb064edccbb21f074c66d1b5e82ba4b6f5a93b69ac1227cab19438df7e23ea94529f40f5598405fcd4834234881ffdc011a7c00f0d00d0467919
+  data.tar.gz: 180aac4998d6a1ed559f006a617a987e0ea61aa0904c9030de8ba9698f23f254b08ee907aa613b12ca79f1863a61e761668388f1e4f6d8efa816bf6b13d7b6d9

data/.ruby-version

@@ -1 +1 @@
-3.0.0
+2.2.2

data/.travis.yml

@@ -1,8 +1,4 @@
 language: ruby
 rvm:
-  - 2.0
-  - 2.1
-  - 2.3.1
-  - 2.7.1
-  - 3.0.0
+  - 2.1.7
 before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -5,12 +5,4 @@ gemspec
 
 group :development do
   gem 'pry'
-  gem 'pry-byebug'
-  gem 'rubocop'
-  gem 'rubocop-rake'
-  gem 'rubocop-rspec'
-end
-
-group :test do
-  gem 'coveralls', require: false
-end
+end

data/README.md

@@ -1,17 +1,18 @@
-[![Build Status](https://travis-ci.org/xeger/docker-compose.svg)](https://travis-ci.org/xeger/docker-compose) [![Coverage Status](https://coveralls.io/repos/github/xeger/docker-compose/badge.svg?branch=coveralls)](https://coveralls.io/github/xeger/docker-compose?branch=coveralls) [![Docs](https://img.shields.io/badge/docs-rubydoc-blue.svg)](http://www.rubydoc.info/gems/docker-compose)
-
 # Docker::Compose
 
 This is a Ruby OOP wrapper for the [docker-compose](https://github.com/docker/compose)
-container orchestration tool from Docker Inc.
+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.)
 
-In addition to wrapping the CLI, this gem provides an environment-variable mapping
-feature that allows you to export environment variables into your _host_ that point
-to network services exposed by containers. This allows you to run an application on
-your host for quicker and easier development, but run all of its dependencies --
-database, cache, adjacent services -- in containers. The dependencies can even run
-on another machine, e.g. a cloud instance or a container cluster, provided your
-development machine has TCP connectivity to every port exposed by a container.  
+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.
@@ -39,19 +40,13 @@ Or install it yourself as:
 ```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
+# 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)
-
-exited = compose.ps.where { |c| !c.up? }
-puts "We have some exited containers: " + exited.join(', ')
-
-sum = compose.ps.inject(0) { |a,c| a + c.size }
-puts format("Composition is using %.1f MiB disk space", sum/1024.0**2)
 ```
 
 ### Invoking from Rake
@@ -69,26 +64,29 @@ end
 ```
 
 Notice that `rake -T` now has a few additional tasks for invoking gem
-functionality. You can `docker:compose:env` to print shell exports for
-host-to-container environment mapping, or you can `docker:compose:host[foo]`.
+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.
 
-### Hosting a Command
+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.
 
-To run a process on your host and allow it to talk to containers, use
-the `docker:compose:host` task. For example, I could enter a shell
-with `rake docker:compose:host[bash]`.
-
-Before "hosting" your command, the Rake task exports some environment
-variables that your command can use to discover services running in
-containers. Your Rakefile specifies which variables your app needs
-(the `host_env` option) and which container information each variable should
-map to.
+### Mapping container IPs and ports
 
-By hosting commands, you benefit from easier debugging and code editing of
-the app you're working on, but still get to rely on containers to provide
-the companion services your app requires to run.
+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.
 
-### Mapping container IPs and ports
+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.
@@ -105,27 +103,30 @@ db:
 ```
 
 Your app needs two inputs, `DATABASE_HOST` and `DATABASE_PORT`. You can specify
-this with the host_env option of the Rake task:
+this in the env section of the Rake task:
 
 ```ruby
 Docker::Compose::RakeTasks.new do |tasks|
-    tasks.host_env = {
-        'DATABASE_HOST' => 'db:[3306]',
-        'DATABASE_PORT' => '[db]:3306',
+    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
-# First, bring up the containers we will be interested in
 user@machine$ docker-compose up -d
 
-# The rake task prints bash code resembling the following:
-#   export DATABASE_HOST='127.0.0.1'
-#   export DATABASE_PORT='34387'
+# 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)"
@@ -133,24 +134,6 @@ user@machine$ eval "$(bundle exec rake docker:compose:env)"
 user@machine$ bundle exec rackup
 ```
 
-The `host_env` option also handles substitution of URLs, and arrays of values
-(which are serialized back to the environment as JSON)
-For example:
-
-```ruby
-tasks.host_env = {
-  'DATABASE_URL' => 'mysql://db:3306/myapp_development',
-  'MIXED_FRUIT' => ['db:[3306]', '[db]:3306']
-}
-```
-
-This would result in the following exports:
-
-```bash
-export DATABASE_URL='mysql://127.0.0.1:34387/myapp_development'
-export MIXED_FRUIT='["127.0.0.1", "34387"]'
-```
-
 To learn more about mapping, read the class documentation for
 `Docker::Compose::Mapper`.
 
@@ -168,3 +151,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/xeger/
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

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

data/bin/console

@@ -1,18 +1,14 @@
-#! /usr/bin/env ruby
-# encoding: utf-8
+#!/usr/bin/env ruby
 
-require 'bundler/setup'
-require 'docker/compose'
+require "bundler/setup"
+require "docker/compose"
 
-@session = Docker::Compose::Session.new
+# 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.
 
-begin
-  require 'pry'
-  Pry.start(@session)
-rescue LoadError
-  require 'irb'
-  IRB.setup nil
-  IRB.conf[:MAIN_CONTEXT] = IRB::Irb.new.context
-  require 'irb/ext/multi-irb'
-  IRB.irb nil, @session
-end
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/docker-compose.gemspec

@@ -4,26 +4,22 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'docker/compose/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = 'docker-compose'
+  spec.name          = "docker-compose"
   spec.version       = Docker::Compose::VERSION
-  spec.authors       = ['Tony Spataro']
-  spec.email         = ['xeger@xeger.net']
+  spec.authors       = ["Tony Spataro"]
+  spec.email         = ["xeger@xeger.net"]
 
-  spec.summary       = 'Wrapper docker-compose with added Rake smarts.'
-  spec.description   = '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.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.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
+  spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.0', '< 4.0')
-
-  spec.add_dependency 'backticks', '~> 1.0'
-
-  spec.add_development_dependency 'bundler', '~> 2.3'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
 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

@@ -1,16 +1,6 @@
-# encoding: utf-8
 module Docker::Compose
   # Uses a Session to discover information about services' IP addresses and
-  # ports as reachable from localhost, then maps URLs and other common network
-  # address formats so they point to the right host and port.
-  #
-  # **NOTE**: this class uses some heuristics to deal with cases where the
-  # Docker client is talking to a remote server because the `DOCKER_HOST`
-  # environment variable is set. In those cases, Mapper tries to determine
-  # the IP address of the exposed services as reachable from localhost;
-  # it generally makes a correct guess, but in certain super-complex networking
-  # scenarios it may guess wrong. Please open a GitHub issue if you find
-  # a situation where Mapper provides a wrong answer.
+  # 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.
@@ -22,44 +12,18 @@ module Docker::Compose
     BadSubstitution = Class.new(StandardError)
     NoService       = Class.new(RuntimeError)
 
-    # Instantiate a mapper; map some environment variables; yield to caller for
-    # additional processing.
-    #
-    # @param [Hash] env a set of keys/values whose values will be mapped
-    # @param [Session] session
-    # @param [NetInfo] net_info
-    # @yield yields with each substituted (key, value) pair
-    def self.map(env, session:Session.new, net_info:NetInfo.new)
-      mapper = new(session, net_info)
-      env.each_pair do |k, v|
-        begin
-          v = mapper.map(v)
-          yield(k, v)
-        rescue NoService
-          yield(k, nil)
-        end
-      end
-    end
-
     # Create an instance of Mapper
-    #
     # @param [Docker::Compose::Session] session
-    # @param [NetInfo] net_info
-    def initialize(session=Session.new, net_info=NetInfo.new)
-      docker_host = ENV['DOCKER_HOST']
-      if docker_host.nil? || docker_host =~ /^(\/|unix|file)/
-        # If DOCKER_HOST is blank, or pointing to a local socket, then we
-        # can trust the address information returned by `docker-compose port`.
-        override_host = nil
-      else
-        # If DOCKER_HOST is present, assume that containers have bound to
-        # whatever IP we reach it at; don't fall victim to docker-compose's
-        # dirty lies!
-        override_host = net_info.docker_routable_ip
-      end
-
+    # @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
-      @override_host = override_host
+      @host_ip = host_ip
+      @strict  = strict
     end
 
     # Substitute service hostnames and ports that appear in a URL or a
@@ -76,84 +40,56 @@ module Docker::Compose
     # @example map just the port of MySQL on local docker host
     #   map("[db]:3306") # => "13847"
     #
-    # @example map an array of database hosts
-    #   map(["[db1]:3306", "[db2]:3306"])
-    #
-    # @param [String,#map] value a URI, host:port pair, or an array of either
-    #
-    # @return [String,Array] the mapped value with container-names and ports substituted
+    # @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)
-      if value.respond_to?(:map)
-        value.map { |e| map_scalar(e) }
-      else
-        map_scalar(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 [Array] (String, Integer) pair of host address and port number
-    def host_and_port(service, port)
-      result = @session.port(service, port.to_s)
-      if result
-        result.chomp!
-      else
-        raise NoService,
-              "Service '#{service}' not running, or does not " \
-              "publish port '#{port}'"
-      end
-
-      host, port = result.split(':')
-      host = @override_host if @override_host
-
-      [host, Integer(port)]
-    end
-
-    # Map a single string, replacing service names with IPs and container ports
-    # with the host ports that they have been mapped to.
-    # @param [String] value
-    # @return [String]
-    def map_scalar(value)
-      uri = begin
-              URI.parse(value)
-            rescue
-              nil
-            end
+      uri = URI.parse(value) rescue nil
       pair = value.split(':')
 
       if uri && uri.scheme && uri.host
         # absolute URI with scheme, authority, etc
-        uri.host, uri.port = host_and_port(uri.host, uri.port)
+        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 = host_and_port(service, pair.last)
+          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, '')
-          host, = host_and_port(service, port)
-          return host
+          published_port(service, port)
+          return @host_ip
         else
           # output port:hostname pair
-          host, port = host_and_port(pair.first, pair.last)
-          return "#{host}:#{port}"
+          port = published_port(pair.first, pair.last)
+          return "#{@host_ip}:#{port}"
         end
+      elsif @strict
+        raise BadSubstitution, "Can't understand '#{value}'"
       else
-        fail BadSubstitution, "Can't understand '#{value}'"
+        return value
       end
     end
-    private :map_scalar
+
+    # 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

@@ -1,4 +1,3 @@
-# encoding: utf-8
 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
@@ -24,8 +23,8 @@ module Docker::Compose
     # 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)
+    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
@@ -40,7 +39,7 @@ module Docker::Compose
     #
     # @return [String] IPv4 address of host machine that _may_ be reachable from
     #   Docker machine
-    def host_routable_ip(target_ip = docker_routable_ip)
+    def host_routable_ip(target_ip=docker_routable_ip)
       best_match  = ''
       best_prefix = 0
 
@@ -73,8 +72,8 @@ module Docker::Compose
         docker_dns = @docker_url.host
         docker_port = @docker_url.port || 2376
       else
-        # Cheap trick: for unix, file or other protocols, assume docker ports
-        # are proxied to localhost in addition to other interfaces
+        # 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