README.md in docker-api-1.26.2 vs README.md in docker-api-1.27.0

- old
+ new

@@ -184,10 +184,14 @@ # Return the raw image binary data image.save # => "abiglongbinarystring" +# Stream the contents of the image to a block: +image.save_stream { |chunk| puts chunk } +# => nil + # Given a Container's export, creates a new Image. # docker command for reference: docker import some-export.tar Docker::Image.import('some-export.tar') # => Docker::Image { :id => 66b712aef, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } } @@ -208,10 +212,15 @@ # Create an Image from a Dockerfile. # docker command for reference: docker build . Docker::Image.build_from_dir('.') # => Docker::Image { :id => 1266dc19e, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } } +# Create an Image from a file other than Dockerfile. +# docker command for reference: docker build -f Dockerfile.Centos . +Docker::Image.build_from_dir('.', { 'dockerfile' => 'Dockerfile.Centos' }) +# => Docker::Image { :id => 1266dc19e, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } } + # Create an Image from a Dockerfile and stream the logs Docker::Image.build_from_dir('.') do |v| if (log = JSON.parse(v)) && log.has_key?("stream") $stdout.puts log["stream"] end @@ -245,10 +254,15 @@ # Return the raw image binary data names = %w( my_image1 my_image2:not_latest ) Docker::Image.save(names) # => "abiglongbinarystring" +# Stream the raw binary data +names = %w( my_image1 my_image2:not_latest ) +Docker::Image.save_stream(names) { |chunk| puts chunk } +# => nil + # Search the Docker registry. # docker command for reference: docker search sshd Docker::Image.search('term' => 'sshd') # => [Docker::Image { :id => cespare/sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => johnfuller/sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => dhrp/mongodb-sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => rayang2004/sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => dhrp/sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => toorop/daemontools-sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => toorop/daemontools-sshd-nginx, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => toorop/daemontools-sshd-nginx-php-fpm, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => mbkan/lamp, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => toorop/golang, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => wma55/u1210sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => jdswinbank/sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }, Docker::Image { :id => vgauthier/sshd, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }] ``` @@ -427,16 +441,34 @@ # => Docker::Container { :id => , :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } } # Request all of the Containers. By default, will only return the running Containers. Docker::Container.all(:all => true) # => [Docker::Container { :id => , :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }] +``` +## JSON encoded values + +For JSON encoded values, nothing is done implicitly, meaning you need to explicitly call `to_json` on your parameter before the call. For example, to request all of the Containers using a filter: + +```ruby +require 'docker' + # Request all of the Containers, filtering by status exited. Docker::Container.all(all: true, filters: { status: ["exited"] }.to_json) # => [Docker::Container { :id => , :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }] + +# Request all of the Container, filtering by label_name. +Docker::Container.all(all: true, filters: { label: [ "label_name" ] }.to_json) +# => [Docker::Container { :id => , :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }] + +# Request all of the Container, filtering by label label_name that have the value label_value_. +Docker::Container.all(all: true, filters: { label: [ "label_name=label_value" ] }.to_json) +# => [Docker::Container { :id => , :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }] ``` +This applies for all parameters that are requested to be JSON encoded by the docker api. + ## Events ```ruby require 'docker' @@ -483,9 +515,13 @@ image = Docker::Image.create('fromImage' => 'repo', 'tag' => 'tag') image = image.insert_local('localPath' => 'some-file.tar.gz', 'outputPath' => '/') image.tag('repo' => 'repo', 'tag' => 'new_tag') end ``` + +## Known issues + +* If the docker daemon is always responding to your requests with a 400 Bad Request when using UNIX sockets, verify you're running Excon version 0.46.0 or greater. [Link](https://github.com/swipely/docker-api/issues/381) ## Not supported (yet) * Generating a tarball of images and metadata for a repository specified by a name: https://docs.docker.com/engine/reference/api/docker_remote_api_v1.14/#get-a-tarball-containing-all-images-and-tags-in-a-repository * Load a tarball generated from docker that contains all the images and metadata of a repository: https://docs.docker.com/engine/reference/api/docker_remote_api_v1.14/#load-a-tarball-with-a-set-of-images-and-tags-into-docker