A Docker HTTP client written in Groovy
This client library aims at supporting all existing api endpoints, which effectively allows to use it in place of the official Docker client binary. It might feel a bit less convenient, though, while it gives you a bit more freedom to access the remote api and some less popular endpoints. See the roadmap.md for details about the current api coverage.
Consider the client as a thin wrapper to perform HTTP requests, minimizing the need to manually configure
TLS or auth encoding in your code. Most commonly known environment variables will work as expected,
e.g. DOCKER_HOST
, DOCKER_TLS_VERIFY
, or DOCKER_CERT_PATH
.
For use in Gradle, add the bintray repository first:
repositories {
maven { url 'http://dl.bintray.com/gesellix/docker-utils' }
}
Then, you need to add the dependency, but please ensure to use the latest version:
dependencies {
compile 'de.gesellix:docker-client:2016-10-07T18-47-59'
}
The tests in DockerClientImplSpec
and DockerClientImplIntegrationSpec
should give you an idea how to use the docker-client.
The default Docker host is expected to be available at unix:///var/run/docker.sock
.
When using Docker Machine the existing environment variables as configured by eval "$(docker-machine env default)"
should be enough.
Even for the native packages Docker for Mac
and Docker for Windows you'll be able to rely on the default configuration.
For Mac the default is the same as for Linux at unix:///var/run/docker.sock
, while
Windows uses the named pipe at //./pipe/docker_engine
.
You can override existing DOCKER_*
environment variables with Java system properties like this:
System.setProperty("docker.host", "192.168.99.100")
System.setProperty("docker.cert.path", "/Users/${System.getProperty('user.name')}/.docker/machine/machines/default")
Please note that the raw responses (including headers) from the Docker daemon are returned, with the actual response body
being available in the content
attribute. Some endpoints return a stream, which is then available in stream
.
For some cases, like following the logs or events stream, you need to provide a callback which is called for every
response line, see example 3 below.
A basic example connecting to a Docker daemon running in a VM (boot2docker/machine) looks like this:
System.setProperty("docker.cert.path", "/Users/${System.getProperty('user.name')}/.docker/machine/machines/default")
def dockerClient = new DockerClientImpl(System.env.DOCKER_HOST)
def info = dockerClient.info().content
Running a container being available on the host via HTTP port 4712 can be achieved like this:
System.setProperty("docker.cert.path", "/Users/${System.getProperty('user.name')}/.docker/machine/machines/default")
def dockerClient = new DockerClientImpl(System.env.DOCKER_HOST)
def image = "busybox"
def tag = "latest"
def cmds = ["sh", "-c", "ping 127.0.0.1"]
def containerConfig = ["Cmd" : cmds,
"ExposedPorts": ["4711/tcp": [:]],
"HostConfig" : ["PortBindings": [
"4711/tcp": [
["HostIp" : "0.0.0.0",
"HostPort": "4712"]]
]]]
def result = dockerClient.run(image, containerConfig, tag).content
def callback = new DockerAsyncCallback() {
def lines = []
@Override
def onEvent(Object line) {
println line
lines << line
}
}
dockerClient.logs("foo", [tail: 1], callback)
// callback.lines will now collect all log lines
// you might implement it as a fifo instead of the List shown above
My personal focus implementing this Docker client was to leverage the Docker remote API in our Gradle scripts. A convenient integration in Gradle is possible by using the Gradle Docker Plugin, which will be developed along with the Docker client library.
If something doesn't work as expected or if you have suggestions, please create an issue. Pull requests are welcome as well!
The developer api is quite rough, but that's where you can certainly help: I'll add a more convenient layer on top of the raw interface so that for 80% of common use cases the Docker client should help you to get it working without digging too deep into the source code. So, all I need is an indication about how you'd like that convenience layer to look like. Feel free to create an issue where we can discuss how your use case could be implemented!
Copyright 2015 Tobias Gesellchen (@gesellix)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.