docker-compose 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb5c46f2fc1351385671bc66a27b8a5ae3a92769c91c2f5d3470b91f31d38e07
+  data.tar.gz: 19800f852de5921b296eda4d9e64a207ce60a6a1fc7959cfaba11965dfb9b823
+SHA512:
+  metadata.gz: 2bf97d99fb8c03cbb2dcbd833d743ef508c7474e6833abf415a0d7534199c67d557585a55ad0dd35d58e92747d8bcada2deb4ce036e7ad86cc79929ad9239a11
+  data.tar.gz: 67f91befe87b16d4f2305bba853eff604abec12d0c3a5f63e1a38f2517838e47a2f1b2db49937630876c6acace00f9abd2f176a17974835eef45465e590217c8

data/.coveralls.yml

@@ -0,0 +1 @@
+repo_token: hMWX6XPNvG4Gfy9gCDEvrxhQVKdyN5e2m

data/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: publish
+
+on:
+  push:
+    branches: [actions]
+
+jobs:
+  publish:
+    name: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0.0
+          bundler-cache: true
+      - name: build
+        run: |
+          release='v0.0.0'
+          version=`echo $release | cut -b2-`
+          if ! echo $release | grep -q '^v[0-9]\+\.[0-9]\+\.[0-9]\+$'; then
+            echo "Release name must be in the format of 'vX.Y.Z', got '$release'"
+            exit 1
+          fi
+          sed -i -r "s/VERSION = '.+'/VERSION = '$version'/" lib/docker/compose/version.rb
+          bundle exec rake build
+      - name: push
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${RUBYGEMS_TOKEN}\n:github: Bearer ${GITHUB_TOKEN}\n" > $HOME/.gem/credentials
+          gem push pkg/*.gem
+          gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} pkg/*.gem
+        env:
+          GITHUB_TOKEN: "Bearer ${{ secrets.GITHUB_TOKEN }}"
+          OWNER: ${{ github.repository_owner }}
+          RUBYGEMS_TOKEN: "${{ secrets.RUBYGEMS_TOKEN }}"

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/.rubocop.yml

@@ -0,0 +1,38 @@
+# CODING CONVENTIONS
+#  - any cop that can be auto-corrected with `rubocop -a` is mandatory
+#  - other cops may be enabled if committer fixes all issues
+AllCops:
+  NewCops: enable
+  Exclude:
+    - features/**/*
+    - spec/**/*
+Style/Encoding:
+  Enabled: true
+Style/FormatString:
+  Enabled: false
+Style/GuardClause:
+  Enabled: false
+Layout/LineLength:
+  Enabled: false
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/RaiseArgs:
+  Enabled: false
+Style/Semicolon:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.0.0

data/.travis.yml

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

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+1.1
+---
+
+#### New features
+
+Add `scale` command to Session methods.
+
+
+1.0
+---
+
+No significant changes; the 1.0 increment is to indicate that Docker::Compose now has test coverage, and that we intend to maintain a stable API until 2.0.
+
+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/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,16 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in docker-compose.gemspec
+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

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,170 @@
+[![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.
+
+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.  
+
+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)
+
+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
+
+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 shell exports for
+host-to-container environment mapping, or you can `docker:compose:host[foo]`.
+
+### Hosting a Command
+
+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.
+
+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.
+
+### 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.
+
+```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 with the host_env option of the Rake task:
+
+```ruby
+Docker::Compose::RakeTasks.new do |tasks|
+    tasks.host_env = {
+        'DATABASE_HOST' => 'db:[3306]',
+        'DATABASE_PORT' => '[db]:3306',
+    }
+end
+```
+
+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'
+# 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
+```
+
+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`.
+
+## 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,7 @@
+# encoding: utf-8
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,18 @@
+#! /usr/bin/env ruby
+# encoding: utf-8
+
+require 'bundler/setup'
+require 'docker/compose'
+
+@session = Docker::Compose::Session.new
+
+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

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,29 @@
+# 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       = '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.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.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'
+end

data/docker-compose.yml

@@ -0,0 +1,11 @@
+# basic smoke test for the gem.
+# TODO: write cucumber features for comprehensive functional tests!
+apple:
+  image: busybox
+  command: /bin/sh -c 'sleep 3600'
+  ports:
+    - 123
+    - 456
+orange:
+  image: busybox
+  command: /bin/sh -c 'sleep 3600'

data/lib/docker/compose/collection.rb

@@ -0,0 +1,13 @@
+module Docker::Compose
+  class Collection < Array
+    # @example find containers that are up
+    #   who_is_up = coll.where { |c| c.up? }
+    # @example count space taken by all containers
+    #   coll.map { |c| c.size }.inject(0) { |a, x| a + x }
+    def where
+      hits = Collection.new
+      self.each { |c| hits << c if yield(c) }
+      hits
+    end
+  end
+end

data/lib/docker/compose/container.rb

@@ -0,0 +1,80 @@
+module Docker::Compose
+  class Container
+    # Format string for `docker ps`
+    PS_FMT     = '({{.ID}}) ({{.Image}}) ({{.Size}}) ({{.Status}}) ({{.Names}}) ({{.Labels}}) ({{.Ports}})'
+    # Number of template substitutions in PS_FMT
+    PS_FMT_LEN = PS_FMT.count('.')
+    # Pattern that parses human-readable values from ps .Status
+    PS_STATUS  = /^([A-Za-z]+) ?\(?([0-9]*)\)? ?(.*)$/i
+    # Pattern that parses FIRST occurrence of container size from a string,
+    # along with its units.
+    PS_SIZE = /^([0-9.]+)\s*([kmgt]?B)/i
+
+    attr_reader :id, :image, :size, :status, :exitstatus
+    attr_reader :names, :labels, :ports
+
+    # @param [String] id
+    # @param [String] image
+    # @param [String,Integer] size e.g. "0B (virtual 100MB)"
+    # @param [String,#map] status e.g. ['Exited', '0', '3 minutes ago']
+    # @param [String,Array] names list of container names (CSV)
+    # @param [String,Array] labels list of container labels (CSV)
+    # @param [String,Array] ports list of exposed ports (CSV)
+    def initialize(id, image, size, status, names, labels, ports)
+      if size.is_a?(String) && (m = PS_SIZE.match(size))
+        scalar, units = m[1], m[2]
+        scalar = scalar.to_f # lazy: invalid --> 0.0
+        mult = case units.downcase
+        when 'b'  then 1
+        when 'kb' then 1_024
+        when 'mb' then 1_024**2
+        when 'gb' then 1_024**3
+        when 'tb' then 1_024**4
+        else
+          raise Error.new('Service#new', units, 'Impossibly large unit')
+        end
+        size = scalar * mult
+      end
+
+      if status.is_a?(String)
+        status = PS_STATUS.match(status)
+        raise Error.new('Service#new', status, 'Unrecognized status') unless status
+      end
+
+      names = names.split(',').map{ |x| x.strip } if names.is_a?(String)
+      labels = labels.split(',').map{ |x| x.strip } if labels.is_a?(String)
+      ports = ports.split(',').map{ |x| x.strip } if ports.is_a?(String)
+
+      @id = id
+      @image = image
+      @size = size
+      @status = status[1].downcase.to_sym
+
+      @exitstatus = case @status
+      when :up
+        nil
+      else
+        status[2].to_i
+      end
+
+      @names = names
+      @labels = labels
+      @ports = ports
+    end
+
+    # static sanity checking ftw!
+    unless ( initarity = instance_method(:initialize).arity ) == PS_FMT_LEN
+      raise LoadError.new("#{__FILE__}:#{__LINE__} - arity(\#initialize) != PS_FMT_LEN; #{initarity} != #{PS_FMT_LEN}")
+    end
+
+    # @return [String]
+    def name
+      names.first
+    end
+
+    # @return [Boolean]
+    def up?
+      self.status == :up
+    end
+  end
+end

data/lib/docker/compose/error.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+module Docker::Compose
+  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(/[\r\n]+/).select { |l| !l.empty? }.first || '(no output)'
+
+      case status
+      when Numeric
+        status = status.to_s
+      else
+        status = "'#{status}'"
+      end
+
+      message = format("'%s' failed with status %s: %s", cmd, status, brief)
+      super(message)
+    end
+  end
+end