Class: Docker::Compose::Session

Inherits:
Object
  • Object
show all
Includes:
Future::Session
Defined in:
lib/docker/compose/session.rb

Overview

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.

Constant Summary

Constants included from Future::Session

Future::Session::SUBSTITUTION

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Future::Session

included, #run_with_substitution!

Constructor Details

#initialize(shell = Docker::Compose::Shell.new, dir: Dir.pwd, file: 'docker-compose.yml') ⇒ Session

Returns a new instance of Session.



18
19
20
21
22
23
 
# File 'lib/docker/compose/session.rb', line 18

def initialize(shell=Docker::Compose::Shell.new,
               dir:Dir.pwd, file:'docker-compose.yml')
  @shell = shell
  @dir = dir
  @file = file
end

Instance Attribute Details

#dir ⇒ Object (readonly)

Returns the value of attribute dir.



16
17
18
 
# File 'lib/docker/compose/session.rb', line 16

def dir
  @dir
end

#file ⇒ Object (readonly)

Returns the value of attribute file.



16
17
18
 
# File 'lib/docker/compose/session.rb', line 16

def file
  @file
end

Instance Method Details

#logs(*services) ⇒ true

Monitor the logs of one or more containers.

Parameters:

  • services (Array) —

    list of String service names to show logs for

Returns:

  • (true) —

    always returns true

Raises:

  • (RuntimeError) —

    if command fails



29
30
31
32
 
# File 'lib/docker/compose/session.rb', line 29

def logs(*services)
  run!('logs', services)
  true
end

#port(service, port, protocol: 'tcp', index: 1) ⇒ Object

Figure out which host a port a given service port has been published to.

Parameters:

  • service (String) —

    name of service from docker-compose.yml

  • port (Integer) —

    number of port

  • protocol (String) (defaults to: 'tcp') —

    ‘tcp’ or ‘udp’

  • index (Integer) (defaults to: 1) —

    of container (if multiple instances running)



65
66
67
 
# File 'lib/docker/compose/session.rb', line 65

def port(service, port, protocol:'tcp', index:1)
  run!('port', {protocol:protocol, index:index}, service, port)
end

#run!(*cmd) ⇒ String

Run a docker-compose command without validating that the CLI parameters make sense. Prepend project and file options if suitable.

Parameters:

  • cmd (Array) —

    subcommand words and options in the format accepted by Shell#command

Returns:

  • (String) —

    output of the command

Raises:

  • (RuntimeError) —

    if command fails

See Also:



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/docker/compose/session.rb', line 98

def run!(*cmd)
  project_opts = {
    file: @file
  }

  Dir.chdir(@dir) do
    result, output, error =
      @shell.command('docker-compose', project_opts, *cmd)
    (result == 0) || raise(Error.new(cmd.first, result, error))
    output
  end
end

#stop(*services, timeout: 10) ⇒ Object

Stop running services.

Parameters:

  • services (Array) —

    list of String service names to stop

  • timeout (Integer) (defaults to: 10) —

    how long to wait for each service to stop



56
57
58
 
# File 'lib/docker/compose/session.rb', line 56

def stop(*services, timeout:10)
  run!('stop', {timeout:timeout}, services)
end

#up(*services, detached: false, timeout: 10, no_build: false, no_deps: false) ⇒ true

Idempotently run services in the project,

Parameters:

  • services (Array) —

    list of String service names to run

  • detached (Boolean) (defaults to: false) —

    if true, to start services in the background; otherwise, monitor logs in the foreground and shutdown on Ctrl+C

  • timeout (Integer) (defaults to: 10) —

    how long to wait for each service to stostart

  • no_build (Boolean) (defaults to: false) —

    if true, to skip building images for services that have a ‘build:` instruction in the docker-compose file

  • no_deps (Boolean) (defaults to: false) —

    if true, just run specified services without running the services that they depend on

Returns:

  • (true) —

    always returns true

Raises:

  • (RuntimeError) —

    if command fails



45
46
47
48
49
50
51
 
# File 'lib/docker/compose/session.rb', line 45

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

#version(short: false) ⇒ String, Hash

Determine the installed version of docker-compose.

Parameters:

  • short (Boolean) (defaults to: false) —

    whether to return terse version information

Returns:

  • (String, Hash) —

    if short==true, returns a version string; otherwise, returns a Hash of component names to version strings

Raises:

  • (RuntimeError) —

    if command fails



74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/docker/compose/session.rb', line 74

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