docker-client

A docker client

License

License

Categories

Categories

Docker Container Virtualization Tools CLI User Interface
GroupId

GroupId

com.spotify
ArtifactId

ArtifactId

docker-client
Last Version

Last Version

8.16.0
Release Date

Release Date

Type

Type

jar
Description

Description

docker-client
A docker client
Project URL

Project URL

https://github.com/spotify/docker-client
Source Code Management

Source Code Management

https://github.com/spotify/docker-client

Download docker-client

How to add to project

<!-- https://jarcasting.com/artifacts/com.spotify/docker-client/ -->
<dependency>
    <groupId>com.spotify</groupId>
    <artifactId>docker-client</artifactId>
    <version>8.16.0</version>
</dependency>
// https://jarcasting.com/artifacts/com.spotify/docker-client/
implementation 'com.spotify:docker-client:8.16.0'
// https://jarcasting.com/artifacts/com.spotify/docker-client/
implementation ("com.spotify:docker-client:8.16.0")
'com.spotify:docker-client:jar:8.16.0'
<dependency org="com.spotify" name="docker-client" rev="8.16.0">
  <artifact name="docker-client" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.spotify', module='docker-client', version='8.16.0')
)
libraryDependencies += "com.spotify" % "docker-client" % "8.16.0"
[com.spotify/docker-client "8.16.0"]

Dependencies

compile (17)

Group / Artifact Type Version
org.slf4j : slf4j-api jar 1.7.22
com.google.guava : guava jar 20.0
com.fasterxml.jackson.jaxrs : jackson-jaxrs-json-provider jar 2.9.8
com.fasterxml.jackson.datatype : jackson-datatype-guava jar 2.9.8
com.fasterxml.jackson.core : jackson-databind jar 2.9.8
org.glassfish.jersey.core : jersey-client jar 2.22.2
org.glassfish.jersey.connectors : jersey-apache-connector jar 2.22.2
org.glassfish.jersey.media : jersey-media-json-jackson jar 2.22.2
javax.activation : activation jar 1.1
org.apache.commons : commons-compress jar 1.18
commons-io : commons-io jar 2.5
org.apache.httpcomponents : httpclient jar 4.5
org.apache.httpcomponents : httpcore jar 4.4.5
com.github.jnr : jnr-unixsocket jar 0.18
commons-lang : commons-lang jar 2.6
org.bouncycastle : bcpkix-jdk15on jar 1.60
com.google.auth : google-auth-library-oauth2-http Optional jar 0.6.0

provided (3)

Group / Artifact Type Version
com.google.auto.value : auto-value jar 1.3
com.google.code.findbugs : jsr305 jar 3.0.1
com.google.code.findbugs : annotations jar 3.0.1

test (10)

Group / Artifact Type Version
junit : junit jar 4.12
org.mockito : mockito-core jar 1.10.19
org.hamcrest : hamcrest-library jar 1.3
ch.qos.logback : logback-classic jar 1.2.1
com.google.jimfs : jimfs jar 1.0
joda-time : joda-time jar 2.8.2
org.awaitility : awaitility jar 2.0.0
com.squareup.okhttp3 : mockwebserver jar 3.8.0
com.spotify : hamcrest-jackson jar 1.1.3
com.spotify : hamcrest-pojo jar 1.1.3

Project Modules

There are no modules declared in this project.

Docker Client

Build Status codecov Maven Central License

Status: mature

Spotify no longer uses recent versions of this project internally. The version of docker-client we're using is whatever helios has in its pom.xml. At this point, we're not developing or accepting new features or even fixing non-critical bugs. Feel free to fork this repo though.

This is a Docker client written in Java. It is used in many critical production systems at Spotify.

Version compatibility

docker-client is built and tested against the six most recent minor releases of Docker. Right now these are 17.03.1ce - 17.12.1ce (specifically the ones here). We upload the artifact tested on Docker 17.12.1~ce. See Docker docs on the mapping between Docker version and API version.

Download

Download the latest JAR or grab via Maven.

<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>docker-client</artifactId>
  <version>LATEST-VERSION</version>
</dependency>

Usage Example

// Create a client based on DOCKER_HOST and DOCKER_CERT_PATH env vars
final DockerClient docker = DefaultDockerClient.fromEnv().build();

// Pull an image
docker.pull("busybox");

// Bind container ports to host ports
final String[] ports = {"80", "22"};
final Map<String, List<PortBinding>> portBindings = new HashMap<>();
for (String port : ports) {
    List<PortBinding> hostPorts = new ArrayList<>();
    hostPorts.add(PortBinding.of("0.0.0.0", port));
    portBindings.put(port, hostPorts);
}

// Bind container port 443 to an automatically allocated available host port.
List<PortBinding> randomPort = new ArrayList<>();
randomPort.add(PortBinding.randomPort("0.0.0.0"));
portBindings.put("443", randomPort);

final HostConfig hostConfig = HostConfig.builder().portBindings(portBindings).build();

// Create container with exposed ports
final ContainerConfig containerConfig = ContainerConfig.builder()
    .hostConfig(hostConfig)
    .image("busybox").exposedPorts(ports)
    .cmd("sh", "-c", "while :; do sleep 1; done")
    .build();

final ContainerCreation creation = docker.createContainer(containerConfig);
final String id = creation.id();

// Inspect container
final ContainerInfo info = docker.inspectContainer(id);

// Start container
docker.startContainer(id);

// Exec command inside running container with attached STDOUT and STDERR
final String[] command = {"sh", "-c", "ls"};
final ExecCreation execCreation = docker.execCreate(
    id, command, DockerClient.ExecCreateParam.attachStdout(),
    DockerClient.ExecCreateParam.attachStderr());
final LogStream output = docker.execStart(execCreation.id());
final String execOutput = output.readFully();

// Kill container
docker.killContainer(id);

// Remove container
docker.removeContainer(id);

// Close the docker client
docker.close();

Getting Started

If you're looking for how to use docker-client, see the User Manual. If you're looking for how to build and develop it, keep reading.

Prerequisites

docker-client should be buildable on any platform with Docker 1.6+, JDK8+, and a recent version of Maven 3.

A note on using Docker for Mac

If you are using Docker for Mac and DefaultDockerClient.fromEnv(), it might not be clear what value to use for the DOCKER_HOST environment variable. The value you should use is DOCKER_HOST=unix:///var/run/docker.sock, at least as of version 1.11.1-beta11.

As of version 4.0.8 of docker-client, DefaultDockerClient.fromEnv() uses unix:///var/run/docker.sock on OS X by default.

Testing

If you're running a recent version of docker (>= 1.12), which contains native swarm support, please ensure that you run docker swarm init to initialize the docker swarm.

Make sure Docker daemon is running and that you can do docker ps.

You can run tests on their own with mvn test. Note that the tests start and stop a large number of containers, so the list of containers you see with docker ps -a will start to get pretty long after many test runs. You may find it helpful to occasionally issue docker rm $(docker ps -aq).

Releasing

Commits to the master branch will trigger our continuous integration agent to build the jar and release by uploading to Sonatype. If you are a project maintainer with the necessary credentials, you can also build and release locally by running the below.

mvn clean [-DskipTests -Darguments=-DskipTests] -Dgpg.keyname=<key ID used for signing artifacts> release:prepare release:perform

A note on shading

Please note that in releases 2.7.6 and earlier, the default artifact was the shaded version. When upgrading to version 2.7.7, you will need to include the shaded classifier if you relied on the shaded dependencies in the docker-client jar.

Standard:

<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>docker-client</artifactId>
  <version>3.5.12</version>
</dependency>

Shaded:

<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>docker-client</artifactId>
  <classifier>shaded</classifier>
  <version>3.5.12</version>
</dependency>

This is particularly important if you use Jersey 1.x in your project. To avoid conflicts with docker-client and Jersey 2.x, you will need to explicitly specify the shaded version above.

Code of conduct

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.

com.spotify

Spotify

Versions

Version
8.16.0
8.15.3
8.15.2
8.15.1
8.15.0
8.14.5
8.14.4
8.14.3
8.14.2
8.14.1
8.14.0
8.13.1
8.13.0
8.12.0
8.11.7
8.11.6
8.11.5
8.11.4
8.11.3
8.11.2
8.11.1
8.11.0
8.10.1
8.10.0
8.9.2
8.9.1
8.9.0
8.8.4
8.8.3
8.8.2
8.8.1
8.8.0
8.7.3
8.7.2
8.7.1
8.7.0
8.6.2
8.6.1
8.6.0
8.5.0
8.4.0
8.3.2
8.3.1
8.3.0
8.2.1
8.2.0
8.1.2
8.1.1
8.1.0
8.0.0
7.0.2
7.0.1
7.0.0
7.0.0-rc3
7.0.0-rc2
7.0.0-rc1
6.2.5
6.2.4
6.2.3
6.2.2
6.2.1
6.2.0
6.1.1
6.1.0
6.0.0
5.0.2
5.0.1
5.0.0
4.0.8
4.0.6
4.0.2
4.0.1
3.6.8
3.6.7
3.6.6
3.6.5
3.6.4
3.6.3
3.6.2
3.6.1
3.6.0
3.5.13
3.5.12
3.5.11
3.5.10
3.5.9
3.5.8
3.5.7
3.5.6
3.5.5
3.5.4
3.5.3
3.5.2
3.5.1
3.5.0
3.4.0
3.3.5
3.3.4
3.3.3
3.3.2
3.3.1
3.3.0
3.2.1
3.2.0
3.1.10
3.1.9
3.1.8
3.1.6
3.1.5
3.1.4
3.1.3
3.1.2
3.1.1
3.1.0
3.0.0
2.7.27
2.7.26
2.7.25
2.7.22
2.7.21
2.7.20
2.7.19
2.7.18
2.7.17
2.7.16
2.7.14
2.7.13
2.7.11
2.7.10
2.7.9
2.7.8
2.7.7
2.7.6
2.7.5
2.7.4
2.7.3
2.7.1
2.7.0
2.6.5
2.6.4
2.6.3
2.6.2
2.6.1
2.6.0
2.5.0
2.4.3
2.4.2
2.4.1
2.4.0
2.3.1
2.3.0
2.2.1