tessl/maven-com-spotify--docker-client

A comprehensive Docker client library for Java applications providing programmatic Docker API access with container lifecycle management, image operations, and Docker Swarm support.

—

Pending

Overview

Eval results

Files

Client Configuration

Name: tessl/maven-com-spotify--docker-client
Author: tessl

The Docker client provides flexible configuration options for connecting to Docker daemons using various transport mechanisms, authentication methods, and connection parameters.

Creating Docker Clients

Environment-Based Configuration

The simplest way to create a client using DOCKER_HOST and DOCKER_CERT_PATH environment variables:

import com.spotify.docker.client.*;
import com.spotify.docker.client.exceptions.DockerCertificateException;

// Create from environment
DockerClient docker = DefaultDockerClient.fromEnv().build();

Builder Configuration

For custom configuration, use the builder pattern:

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker.example.com:2376")
    .connectionPoolSize(50)
    .connectTimeoutMillis(30000)
    .readTimeoutMillis(60000)
    .build();

Connection Types

Unix Socket Connection

For local Docker daemon access on Linux/macOS:

DockerClient docker = DefaultDockerClient.builder()
    .uri("unix:///var/run/docker.sock")
    .build();

// Or using the constructor
DockerClient docker = new DefaultDockerClient("unix:///var/run/docker.sock");

Named Pipe Connection (Windows)

For Windows Docker Desktop:

DockerClient docker = DefaultDockerClient.builder()
    .uri("npipe:////./pipe/docker_engine")
    .build();

TCP Connection

For remote Docker daemon access:

DockerClient docker = DefaultDockerClient.builder()
    .uri("tcp://docker.example.com:2376")
    .build();

HTTPS Connection with TLS

For secure remote connections:

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker.example.com:2376")
    .dockerCertificates(new DockerCertificates(Paths.get("/path/to/certs")))
    .build();

SSL Certificates and Security

Using DockerCertificates

import com.spotify.docker.client.DockerCertificates;
import java.nio.file.Paths;

// From certificate directory
DockerCertificates certs = new DockerCertificates(Paths.get("/Users/user/.docker"));

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker.example.com:2376")
    .dockerCertificates(certs)
    .build();

Certificate Files

The certificate directory should contain:

ca.pem - Certificate authority
cert.pem - Client certificate
key.pem - Client private key

Path certPath = Paths.get(System.getProperty("user.home"), ".docker", "machine-name");
DockerCertificates certs = new DockerCertificates(certPath);

DockerCertificatesStore

For advanced certificate management:

import com.spotify.docker.client.DockerCertificatesStore;

DockerCertificatesStore certStore = DockerCertificates.builder()
    .dockerCertPath(Paths.get("/path/to/certs"))
    .caCertPath(Paths.get("/path/to/ca.pem"))
    .clientKeyPath(Paths.get("/path/to/key.pem"))
    .clientCertPath(Paths.get("/path/to/cert.pem"))
    .build()
    .orElse(null);

DockerClient docker = DefaultDockerClient.builder()
    .dockerCertificates(certStore)
    .build();

Connection Pool Configuration

Basic Pool Settings

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker.example.com:2376")
    .connectionPoolSize(100)  // Maximum concurrent connections
    .build();

Timeout Configuration

DockerClient docker = DefaultDockerClient.builder()
    .connectTimeoutMillis(30000)    // 30 second connect timeout
    .readTimeoutMillis(300000)      // 5 minute read timeout
    .connectionPoolSize(50)
    .build();

Registry Authentication

Authentication Suppliers

The library provides several authentication mechanisms:

import com.spotify.docker.client.auth.*;

// From Docker config files (~/.docker/config.json)
RegistryAuthSupplier authSupplier = new ConfigFileRegistryAuthSupplier();

DockerClient docker = DefaultDockerClient.builder()
    .registryAuthSupplier(authSupplier)
    .build();

Fixed Registry Authentication

RegistryAuth auth = RegistryAuth.builder()
    .username("myuser")
    .password("mypass")
    .email("user@example.com")
    .serverAddress("https://index.docker.io/v1/")
    .build();

RegistryAuthSupplier authSupplier = new FixedRegistryAuthSupplier(
    auth, RegistryConfigs.create(Map.of("https://index.docker.io/v1/", auth))
);

DockerClient docker = DefaultDockerClient.builder()
    .registryAuthSupplier(authSupplier)
    .build();

Multiple Registry Authentication

RegistryAuthSupplier dockerHub = new ConfigFileRegistryAuthSupplier();
RegistryAuthSupplier gcr = new ContainerRegistryAuthSupplier(
    "path/to/service-account.json", "my-project"
);

RegistryAuthSupplier multiAuth = new MultiRegistryAuthSupplier(
    dockerHub, gcr
);

DockerClient docker = DefaultDockerClient.builder()
    .registryAuthSupplier(multiAuth)
    .build();

Google Container Registry

import com.spotify.docker.client.auth.gcr.ContainerRegistryAuthSupplier;

RegistryAuthSupplier gcrAuth = new ContainerRegistryAuthSupplier(
    Paths.get("/path/to/service-account.json"),
    "my-gcp-project"
);

DockerClient docker = DefaultDockerClient.builder()
    .registryAuthSupplier(gcrAuth)
    .build();

Configuration from Docker Environment

Reading Docker Configuration

import com.spotify.docker.client.DockerConfigReader;

// Read from default locations
DockerConfig config = DockerConfigReader.fromDefaultConfigPath();

// Read from specific path  
DockerConfig config = DockerConfigReader.fromConfigPath(
    Paths.get("/custom/config.json")
);

// Use configuration
RegistryAuth auth = config.auths().get("https://index.docker.io/v1/");

Environment Variables

The client automatically recognizes these environment variables:

DOCKER_HOST - Docker daemon endpoint
DOCKER_CERT_PATH - Path to certificate directory
DOCKER_TLS_VERIFY - Enable TLS verification

// Automatically uses environment variables
DockerClient docker = DefaultDockerClient.fromEnv().build();

// Override specific settings
DockerClient docker = DefaultDockerClient.fromEnv()
    .connectionPoolSize(200)
    .readTimeoutMillis(120000)
    .build();

Advanced Configuration

Custom Headers

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker.example.com:2376")
    .header("X-Custom-Header", "value")
    .header("Authorization", "Bearer " + token)
    .build();

Proxy Configuration

// System properties based proxy
System.setProperty("http.proxyHost", "proxy.example.com");
System.setProperty("http.proxyPort", "8080");

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker.example.com:2376")
    .useProxy(true)
    .build();

Request Entity Processing

import org.glassfish.jersey.client.ClientProperties;

DockerClient docker = DefaultDockerClient.builder()
    .requestEntityProcessing(ClientProperties.RequestEntityProcessing.CHUNKED)
    .build();

Configuration Examples

Production Configuration

DockerClient docker = DefaultDockerClient.builder()
    .uri("https://docker-prod.example.com:2376")
    .dockerCertificates(new DockerCertificates(
        Paths.get("/etc/docker/certs")))
    .connectionPoolSize(100)
    .connectTimeoutMillis(30000)
    .readTimeoutMillis(300000)
    .registryAuthSupplier(new ConfigFileRegistryAuthSupplier())
    .build();

Development Configuration

DockerClient docker = DefaultDockerClient.builder()
    .uri("unix:///var/run/docker.sock")
    .connectionPoolSize(10)
    .connectTimeoutMillis(10000)
    .readTimeoutMillis(60000)
    .build();

Multi-Environment Configuration

public class DockerClientFactory {
    
    public static DockerClient createClient(Environment env) {
        DefaultDockerClient.Builder builder = DefaultDockerClient.builder();
        
        switch (env) {
            case LOCAL:
                return builder
                    .uri("unix:///var/run/docker.sock")
                    .build();
                    
            case STAGING:
                return builder
                    .uri("https://docker-staging.example.com:2376")
                    .dockerCertificates(loadCertificates("staging"))
                    .connectionPoolSize(50)
                    .build();
                    
            case PRODUCTION:
                return builder
                    .uri("https://docker-prod.example.com:2376")
                    .dockerCertificates(loadCertificates("production"))
                    .connectionPoolSize(200)
                    .connectTimeoutMillis(30000)
                    .readTimeoutMillis(300000)
                    .registryAuthSupplier(createAuthSupplier())
                    .build();
        }
    }
    
    private static DockerCertificates loadCertificates(String env) {
        Path certPath = Paths.get("/etc/docker/certs", env);
        return new DockerCertificates(certPath);
    }
}

Builder Reference

DefaultDockerClient.Builder Methods

public class DefaultDockerClient.Builder {
    Builder uri(String uri);
    Builder uri(URI uri);
    Builder dockerCertificates(DockerCertificatesStore dockerCertificatesStore);
    Builder connectionPoolSize(int connectionPoolSize);
    Builder connectTimeoutMillis(long connectTimeoutMillis);  
    Builder readTimeoutMillis(long readTimeoutMillis);
    Builder registryAuthSupplier(RegistryAuthSupplier registryAuthSupplier);
    Builder header(String name, String value);
    Builder useProxy(boolean useProxy);
    Builder requestEntityProcessing(RequestEntityProcessing processing);
    DockerClient build();
}

Connection Troubleshooting

Common Issues

try {
    DockerClient docker = DefaultDockerClient.fromEnv().build();
    String response = docker.ping();
    System.out.println("Docker daemon is reachable: " + response);
} catch (DockerException e) {
    System.err.println("Cannot connect to Docker daemon: " + e.getMessage());
    // Check DOCKER_HOST environment variable
    // Verify Docker daemon is running
    // Check certificate paths and permissions
}

Connection Validation

public boolean validateDockerConnection(DockerClient docker) {
    try {
        String ping = docker.ping();
        Version version = docker.version();
        Info info = docker.info();
        
        System.out.println("Ping: " + ping);
        System.out.println("Version: " + version.version());
        System.out.println("API Version: " + version.apiVersion());
        System.out.println("Containers: " + info.containers());
        
        return true;
    } catch (DockerException | InterruptedException e) {
        System.err.println("Connection validation failed: " + e.getMessage());
        return false;
    }
}

The Docker client configuration system provides comprehensive options for connecting to Docker daemons in various environments while maintaining security and performance requirements.

Install with Tessl CLI

npx tessl i tessl/maven-com-spotify--docker-client

docs

client-configuration.md

tessl/maven-com-spotify--docker-client