Class: Docker::Compose::Session

Inherits:
Object
  • Object
show all
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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(shell = Backticks::Runner.new(interactive: true), dir: Dir.pwd, file: 'docker-compose.yml') ⇒ Session

Returns a new instance of Session.



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

def initialize(shell = Backticks::Runner.new(interactive: true),
               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.



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

def dir
  @dir
end

#file ⇒ Object (readonly)

Returns the value of attribute file.



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

def file
  @file
end

Instance Method Details

#config(*args) ⇒ Hash

Validate docker-compose file and return it as Hash

Returns:

  • (Hash) —

    the docker-compose config file

Raises:

  • (Error) —

    if command fails



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

def config(*args)
  config = run!('config', *args)
  YAML.load(config)
end

#kill(*services, signal: 'KILL') ⇒ Object

Forcibly stop running services.

Parameters:

  • services (Array) —

    list of String service names to stop

  • name (String) —

    of murderous signal to use, default is ‘KILL’

See Also:

  • for a list of acceptable signal names


129
130
131
 
# File 'lib/docker/compose/session.rb', line 129

def kill(*services, signal:'KILL')
  run!('kill', { s: signal }, services)
end

#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:

  • (Error) —

    if command fails



39
40
41
42
 
# File 'lib/docker/compose/session.rb', line 39

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

#pause(*services) ⇒ Object

Pause running services.

Parameters:

  • services (Array) —

    list of String service names to run



107
108
109
 
# File 'lib/docker/compose/session.rb', line 107

def pause(*services)
  run!('pause', *services)
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)

Raises:

  • (Error) —

    if command fails



139
140
141
 
# File 'lib/docker/compose/session.rb', line 139

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

#ps ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/docker/compose/session.rb', line 44

def ps()
  inter = @shell.interactive
  @shell.interactive = false

  lines = run!('ps', q:true).split(/[\r\n]+/)
  containers = Collection.new

  lines.each do |id|
    containers << docker_ps(id)
  end

  containers
ensure
  @shell.interactive = inter
end

#rm(*services, force: false, volumes: false) ⇒ Object 



79
80
81
 
# File 'lib/docker/compose/session.rb', line 79

def rm(*services, force:false, volumes:false)
  run!('rm', { f: force, v: volumes }, services)
end

#run(service, *cmd, detached: false, no_deps: false, env: [], env_vars: nil, rm: false) ⇒ Object

Idempotently run an arbitrary command with a service container.

Parameters:

  • service (String) —

    name to run

  • cmd (String) —

    command statement 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

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

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

  • env (Array) (defaults to: []) —

    a list of environment variables (see: -e flag)

  • env_vars (Array) (defaults to: nil) —

    DEPRECATED alias for env kwarg

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

    remove the container when done

Raises:

  • (Error) —

    if command fails



94
95
96
97
98
99
100
101
102
103
 
# File 'lib/docker/compose/session.rb', line 94

def run(service, *cmd, detached:false, no_deps:false, env:[], env_vars:nil, rm:false)
  # handle deprecated kwarg
  if (env.nil? || env.empty?) && !env_vars.nil?
    env = env_vars
  end

  env_params = env.map { |v| { e: v } }
  run!('run',
       { d: detached, no_deps: no_deps, rm: rm }, *env_params, service, cmd)
end

#run!(*args) ⇒ String

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

Parameters:

  • args (Array) —

    command-line arguments in the format accepted by Backticks::Runner#command

Returns:

  • (String) —

    output of the command

Raises:

  • (Error) —

    if command fails

See Also:

  • Docker::Compose::Shell#command


172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/docker/compose/session.rb', line 172

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

  Dir.chdir(@dir) do
    cmd = @shell.run('docker-compose', project_opts, *args).join
    status = cmd.status
    out = cmd.captured_output
    err = cmd.captured_error
    status.success? || fail(Error.new(args.first, status, err))
    out
  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

Raises:

  • (Error) —

    if command fails



121
122
123
 
# File 'lib/docker/compose/session.rb', line 121

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

#unpause(*services) ⇒ Object

Unpause running services.

Parameters:

  • services (Array) —

    list of String service names to run



113
114
115
 
# File 'lib/docker/compose/session.rb', line 113

def unpause(*services)
  run!('unpause', *services)
end

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

Idempotently up the given 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:

  • (Error) —

    if command fails



71
72
73
74
75
76
77
 
# File 'lib/docker/compose/session.rb', line 71

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-name strings to version strings

Raises:

  • (Error) —

    if command fails



148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/docker/compose/session.rb', line 148

def version(short:false)
  result = run!('version', short: short, file: false, dir: false)

  if short
    result.strip
  else
    lines = result.split(/[\r\n]+/)
    lines.inject({}) do |h, line|
      kv = line.split(/: +/, 2)
      h[kv.first] = kv.last
      h
    end
  end
end