docker-compose 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a85e6cd467f9c5c4a6704724d9429a4f681d065a
-  data.tar.gz: a5f85af19b15c215b68a01e7004bf0c0cb05587e
+  metadata.gz: 04a52fb98e79311b5e3c771d24d41d434ab08e53
+  data.tar.gz: d1a04e25f5164edff5e2651ceed331fd58a20eb4
 SHA512:
-  metadata.gz: 1a9143db8626ea989d500c29a802c79b84c50ebd66674daf9bfff474f413353a9d3203bd1860d5dce3dbefa2301fc44521db597fd56b4cdf95d9ff295d11be57
-  data.tar.gz: f2f68bd762d659926ec4880423db394e75ef03ea72f7ee0cf7af65e06639be902f0f0d9819128f64d6dc8e4d56d06b5ceb05795ed3e800ac1383f23b3939947d
+  metadata.gz: 52a9df711b6120701e3359fb30c3b22bc3c87abaa7823724c39e0efb462bc288b091efbce6eb77561b42f0ab112b9ea5568ac856de18ac7511d5a08292d60c30
+  data.tar.gz: ecd93e2c5c33b10acde0b8bd7c15c025676a53ff43f5b5df020e07f103961ccd5833e2096e965bd0766be2f768d0abdcb55b0b0ccab27572411f8f6fa07ec7e4

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+0.6
+---
+
+#### Interface-breaking changes
+
+  - Replaced `docker:compose:server` Rake task with more general `docker:compose:host`
+    - Replaced `server_env` option with `host_env`
+    - Replaced `extra_server_env` option with `extra_host_env`
+  - Stopped mapping values in `extra_host_env`; they are now exported verbatim
+
+#### New features
+
+Produce `docker:compose:env` output that is compatible with user's login shell.
+
+0.5
+---
+
+Initial public release of prototype. Features work well, but there is no test
+coverage.

data/README.md

@@ -7,7 +7,7 @@ In addition to wrapping the CLI, this gem provides an environment-variable mappi
 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 architectural
-dependencies -- database, cache, adjacent microservices -- in containers. The
+dependencies -- database, cache, adjacent services -- in containers. The
 dependencies can even be running on another machine, e.g. a cloud instance or a
 container cluster, provided your development machine has TCP connectivity on every
 port exposed by a container.  
@@ -62,29 +62,26 @@ 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.
+functionality. You can `docker:compose:env` print shell exports for
+host-to-container environment mapping, or you can `docker:compose:host[foo]`.
 
-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.
+### Hosting a Command
 
-### Mapping container IPs and ports
+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 export ssome 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.
 
-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.
+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.
 
-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!
+### Mapping container IPs and ports
 
 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.
@@ -101,30 +98,27 @@ db:
 ```
 
 Your app needs two inputs, `DATABASE_HOST` and `DATABASE_PORT`. You can specify
-this in the env section of the Rake task:
+this with the host_env option of the Rake task:
 
 ```ruby
 Docker::Compose::RakeTasks.new do |tasks|
-    tasks.env = {
-        'DATABASE_HOST' => 'db:[3306]'
-        'DATABASE_PORT' => '[db]:3306'
+    tasks.host_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
 
-# This prints bash code resembling the following:
-#   export DATABASE_HOST=127.0.0.1
-#   export DATABASE_PORT=34387
+# The rake task 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)"
@@ -132,6 +126,24 @@ 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`.
 

data/lib/docker/compose/mapper.rb

@@ -15,11 +15,10 @@ module Docker::Compose
     # Instantiate a mapper; map some environment variables; yield to caller for
     # additional processing.
     #
-    # @param [Boolean] strict
     # @param [Session] session
     # @param [NetInfo] net_info
     # @yield yields with each substituted (key, value) pair
-    def self.map(env, strict:true, session:Session.new, net_info:NetInfo.new)
+    def self.map(env, session:Session.new, net_info:NetInfo.new)
       # TODO: encapsulate this trickiness better ... inside NetInfo perhaps?
       docker_host = ENV['DOCKER_HOST']
       if docker_host.nil? || docker_host =~ /^(\/|unix|file)/
@@ -32,7 +31,7 @@ module Docker::Compose
         override_host = net_info.docker_routable_ip
       end
 
-      mapper = self.new(session, override_host, strict:strict)
+      mapper = self.new(session, override_host)
       env.each_pair do |k, v|
         begin
           v = mapper.map(v)
@@ -47,13 +46,9 @@ module Docker::Compose
     # @param [Docker::Compose::Session] session
     # @param [String] override_host forcible address or DNS hostname to use;
     #   leave nil to trust docker-compose output.
-    # @param [Boolean] strict if true, raise BadSubstitution when unrecognized
-    #        syntax is passed to #map; if false, simply return unrecognized
-    #        values without substituting anything
-    def initialize(session, override_host=nil, strict:true)
+    def initialize(session, override_host=nil)
       @session = session
       @override_host = override_host
-      @strict  = strict
     end
 
     # Substitute service hostnames and ports that appear in a URL or a
@@ -133,10 +128,8 @@ module Docker::Compose
           host, port = host_and_port(pair.first, pair.last)
           return "#{host}:#{port}"
         end
-      elsif @strict
-        raise BadSubstitution, "Can't understand '#{value}'"
       else
-        return value
+        raise BadSubstitution, "Can't understand '#{value}'"
       end
     end
   end

data/lib/docker/compose/rake_tasks.rb

@@ -5,6 +5,9 @@ require 'shellwords'
 # In case this file is required directly
 require 'docker/compose'
 
+# Only used here, so only required here
+require 'docker/compose/shell_printer'
+
 module Docker::Compose
   class RakeTasks < Rake::TaskLib
     # Set the directory in which docker-compose commands will be run. Default
@@ -17,32 +20,33 @@ module Docker::Compose
     # @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.
+    # Provide a mapping of environment variables that should be set in
+    # _host_ processes, e.g. when running docker:compose:env or
+    # docker:compose:host.
+    #
     # 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.
+    # and ports defined in the docker-compose file, and this gem will substitute
+    # the actual IP and port that the containers are reachable on. This allows
+    # commands invoked via "docker:compose:host" to reach services running
+    # inside containers.
     #
     # @see Docker::Compose::Mapper for information about the substitution syntax
-    attr_accessor :server_env
-
-    # Extra environment variables that should be set before invoking the command
-    # specified for docker:compose:server. These are set _in addition_ to server_env
-    # (and should be disjoint from server_env), and do not necessarily need to map the
-    # location of a container; they are simply extra environment values that are
-    # useful to change the server's behavior when it runs in cooperation
-    # with containers.
+    attr_accessor :host_env
+
+    # Extra environment variables to set before invoking host processes. These
+    # are set _in addition_ to server_env, but are not substituted in any way
+    # and must not contain any service information.
     #
-    # If there is overlap between server_env and extra_server_env, then keys
-    # of extra_server_env will "win"; they are set last.
-    attr_accessor :extra_server_env
+    # Extra host env should be disjoint from host_env; if there is overlap
+    # between the two, then extra_host_env will "win."
+    attr_accessor :extra_host_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
+    # Services to bring up with `docker-compose up` before running any hosted
+    # command. This is useful if your `docker-compose.yml` contains a service
+    # definition for the app you will be hosting; if you host the app, you
+    # want to specify all of the _other_ services, but not the app itself, since
+    # that will run on the host.
+    attr_accessor :host_services
 
     # Namespace to define the rake tasks under. Defaults to "docker:compose'.
     attr_accessor :rake_namespace
@@ -53,14 +57,15 @@ module Docker::Compose
     def initialize
       self.dir = Rake.application.original_dir
       self.file = 'docker-compose.yml'
-      self.server_env = {}
-      self.extra_server_env = {}
+      self.host_env = {}
+      self.extra_host_env = {}
       self.rake_namespace = 'docker:compose'
       yield self if block_given?
 
       @shell = Backticks::Runner.new
       @session = Docker::Compose::Session.new(@shell, dir:dir, file:file)
       @net_info = Docker::Compose::NetInfo.new
+      @shell_printer = Docker::Compose::ShellPrinter.new
 
       @shell.interactive = true
 
@@ -73,41 +78,22 @@ module Docker::Compose
         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 task; set process
-            # environment _and_ print bash export commands to stdout.
-            # Also print usage hints if user invoked rake directly vs.
-            # eval'ing it's output
-            print_usage
-            export_env(print:true)
-          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
+          print_usage if STDOUT.tty?
+          export_env(print:true)
 
           @shell.interactive = true
         end
 
-        desc 'Launch services (ONLY=a,b,...)'
-        task :up do
-          only = (ENV['ONLY'] || '').split(',').compact.uniq
-          @session.up(*only, detached:true)
-        end
-
-        desc 'Tail logs of all running services'
-        task :logs do
-          @session.logs
-        end
+        desc 'Run command on host, linked to services in containers'
+        task :host, [:command] => ['docker:compose:env'] do |task, args|
 
-        desc 'Stop services'
-        task :stop do
-          @session.stop
-        end
+          if self.host_services
+            @session.up(*self.host_services, detached:true)
+          else
+            @session.up(detached:true)
+          end
 
-        desc 'Run application on the host, linked to services in containers'
-        task :server => ['docker:compose:up', 'docker:compose:env'] do
-          exec(self.server)
+          exec(args[:command])
         end
       end
     end
@@ -116,17 +102,14 @@ module Docker::Compose
     # 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:)
-      Docker::Compose::Mapper.map(self.server_env,
+      Docker::Compose::Mapper.map(self.host_env,
                                   session:@session,
                                   net_info:@net_info) do |k, v|
         ENV[k] = serialize_for_env(v)
         print_env(k, ENV[k]) if print
       end
 
-      Docker::Compose::Mapper.map(self.extra_server_env,
-                                  strict:false,
-                                  session:@session,
-                                  net_info:@net_info) do |k, v|
+      self.extra_host_env.each do |k, v|
         ENV[k] = serialize_for_env(v)
         print_env(k, ENV[k]) if print
       end
@@ -148,19 +131,21 @@ module Docker::Compose
       end
     end
 
-    # Print a bash export or unset statement
+    # Print an export or unset statement suitable for user's shell
     private def print_env(k, v)
       if v
-        puts format('export %s=%s', k, Shellwords.escape(v))
+        puts @shell_printer.export(k, v)
       else
-        puts format('unset %s # service not running', k)
+        puts @shell_printer.unset(k)
       end
     end
 
+
     private def print_usage
-      be = 'bundle exec ' if defined?(Bundler)
-      puts %Q{# To export these variables to your shell, run:}
-      puts %Q{#   eval "$(#{be}rake docker:compose:env)"}
+      command = "rake #{rake_namespace}:env"
+      command = "bundle exec " + command if defined?(Bundler)
+      puts @shell_printer.comment('To export these variables to your shell, run:')
+      puts @shell_printer.comment(@shell_printer.eval_output(command))
     end
   end
 end

data/lib/docker/compose/shell_printer.rb

@@ -0,0 +1,21 @@
+require 'etc'
+
+module Docker::Compose
+  module ShellPrinter
+    def self.new
+      shell = Etc.getpwuid(Process.uid).shell
+      basename = File.basename(shell)
+
+      # Crappy titleize (bash -> Bash)
+      basename[0] = basename[0].upcase
+
+      # Find adapter class named after shell; default to posix if nothing found
+      klass = const_get(basename.to_sym) rescue Posix
+
+      klass.new
+    end
+  end
+end
+
+require_relative 'shell_printer/posix'
+require_relative 'shell_printer/fish'

data/lib/docker/compose/shell_printer/fish.rb

@@ -0,0 +1,16 @@
+module Docker::Compose::ShellPrinter
+  # Printer that works with the Friendly Interactive Shell (fish).
+  class Fish < Posix
+    def eval_output(command)
+      format('eval (%s)', command)
+    end
+
+    def export(name, value)
+      format('set -gx %s %s; ', name, single_quoted_escaped(value))
+    end
+
+    def unset(name)
+      format('set -ex %s; ', name)
+    end
+  end
+end

data/lib/docker/compose/shell_printer/posix.rb

@@ -0,0 +1,32 @@
+module Docker::Compose::ShellPrinter
+  # Printer that works with any POSIX-compliant shell e.g. sh, bash, zsh
+  class Posix
+    def comment(value)
+      format('# %s', value)
+    end
+
+    def eval_output(command)
+      format('eval "$(%s)"', command)
+    end
+
+    def export(name, value)
+      format('export %s=%s', name, single_quoted_escaped(value))
+    end
+
+    def unset(name)
+      format('unset %s', name)
+    end
+
+    protected def single_quoted_escaped(value)
+      # "escape" any occurrences of ' in value by closing the single-quoted
+      # string, concatenating a single backslash-escaped ' character, and reopening
+      # the single-quoted string.
+      #
+      # This relies on the shell's willingness to concatenate adjacent string
+      # literals. Tested under sh, bash and zsh; should work elsewhere.
+      escaped = value.gsub("'") { "'\\''" }
+
+      "'#{escaped}'"
+    end
+  end
+end

data/lib/docker/compose/version.rb

@@ -1,5 +1,5 @@
 module Docker
   module Compose
-    VERSION = "0.5.1"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: docker-compose
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-13 00:00:00.000000000 Z
+date: 2016-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backticks
@@ -78,6 +78,7 @@ files:
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -92,6 +93,9 @@ files:
 - lib/docker/compose/net_info.rb
 - lib/docker/compose/rake_tasks.rb
 - lib/docker/compose/session.rb
+- lib/docker/compose/shell_printer.rb
+- lib/docker/compose/shell_printer/fish.rb
+- lib/docker/compose/shell_printer/posix.rb
 - lib/docker/compose/version.rb
 homepage: https://github.com/xeger/docker-compose
 licenses: