spotify-docker-client

The client uses Apache HTTP client with a shared connection pool. The default pool size is 100 concurrent requests. If you need to handle more concurrent operations (e.g., waiting on many containers via DockerClient.waitContainer), increase the pool size using .connectionPoolSize().

Note: The connect timeout applies to acquiring a connection from the pool. If the pool is exhausted, a DockerTimeoutException may be thrown.

final DockerClient docker = DefaultDockerClient.fromEnv()
    .connectionPoolSize(SOME_LARGE_NUMBER)
    .build();

Authentication for building, pushing, or pulling images is handled via the RegistryAuthSupplier interface.

Available implementations:

• auth.ConfigFileRegistryAuthSupplier: Reads from ~/.dockercfg or ~/.docker/config.json.
• auth.FixedRegistryAuthSupplier: Uses fixed RegistryAuth and RegistryConfigs POJOs.
• auth.gcr.ContainerRegistryAuthSupplier: Fetches tokens for Google Container Registry.
• auth.MultiRegistryAuthSupplier: Combines multiple implementations.

Since version 8.7.0, ConfigFileRegistryAuthSupplier is enabled by default unless you explicitly provide other authentication via .dockerAuth(), .registryAuth(), or .registryAuthSupplier() in the builder.

The exec API allows you to run processes inside an existing container.

1. Create: Use execCreate(containerId, commandArray) to define the execution. It returns an ExecCreate object containing an id.
2. Start/Run: Use execStart(execId) to run the command. This returns a LogStream which you can read to capture output.
3. Inspect: Use execInspect(execId) to check the ExecState, including exitCode(), running(), and whether openStdout(), openStderr(), or openStdin() are active.
4. Resize: Use execResizeTty(execId, height, width) to resize the TTY of a running exec instance.

You can instantiate a DockerClient using environment variables or a builder. DefaultDockerClient.fromEnv() uses DOCKER_HOST and DOCKER_CERT_PATH to configure the client. DefaultDockerClient.builder() allows for manual configuration of timeouts, connection pools, and other parameters.

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

// or use the builder
final DockerClient docker = DefaultDockerClient.builder()
  // Set various options
  .build();

To build docker-client from source, you need the following installed on your system:

• Docker 1.6+
• JDK 8+
• Maven 3 (recent version)

Use the volume API to manage persistent storage.

• List volumes: listVolumes() returns a VolumeList containing a list of Volume objects and any warnings.
• Create a volume:
  • Named volume: Use Volume.builder() to specify name, driver, and labels, then call createVolume(volume).
  • Anonymous volume: Call createVolume() with no arguments.
• Inspect: inspectVolume(volumeName) returns metadata for the volume.
• Remove: removeVolume(volumeName) or removeVolume(volumeObject) deletes the volume.

// Create a named volume with labels
final Volume toCreate = Volume.builder()
  .name("volumeName")
  .driver("local")
  .labels(ImmutableMap.of("foo", "bar"))
  .build();
final Volume created = docker.createVolume(toCreate);

// Remove a volume
docker.removeVolume("volumeName");

You can export images as tar streams using save or saveMultiple and import them using load.

• Save a single image: save(imageName) returns an InputStream of the tarball.
• Save multiple images: saveMultiple(name1, name2, ...) returns an InputStream containing multiple images.
• Load images: load(InputStream) accepts an InputStream containing one or more images/tags in tar format.

When using Docker for Mac with DefaultDockerClient.fromEnv(), you may need to explicitly set the DOCKER_HOST environment variable if you are on an older version of the client.

For Docker for Mac, use: DOCKER_HOST=unix:///var/run/docker.sock

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

To use docker-client in your Java project, add the following dependency to your pom.xml.

Note: If your project uses Jersey 1.x, you should use the shaded classifier to avoid dependency conflicts with Jersey 2.x.

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

<!-- Shaded version (use this if you have Jersey 1.x conflicts) -->
<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>docker-client</artifactId>
  <classifier>shaded</classifier>
  <version>LATEST-VERSION</version>
</dependency>

If the Docker daemon encounters an unexpected error, the client will throw an exception such as: com.spotify.docker.client.shaded.javax.ws.rs.InternalServerErrorException: HTTP 500 Internal Server Error.

Resolution: This is a server-side error from the Docker daemon. Check the Docker daemon logs on the host machine (typically at /var/log/docker.log or /var/log/upstart/docker.log) to find the root cause.