0
# Spotify Docker Client Java Library
1

2
The Spotify Docker Client is a comprehensive Java library that provides programmatic access to Docker Engine APIs. It offers complete container lifecycle management, image operations, network management, volume operations, and Docker Swarm support with type-safe parameter handling and immutable data classes.
3

4
## Package Information
5

6
- **Package Name**: docker-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Maven dependency below
10

11
## Core Imports
12

13
```java
14
import com.spotify.docker.client.DockerClient;
15
import com.spotify.docker.client.DefaultDockerClient;
16
import com.spotify.docker.client.messages.*;
17
import com.spotify.docker.client.exceptions.DockerException;
18
```
19

20
## Installation
21

22
Add the dependency to your Maven project:
23

24
```xml
25
<dependency>
26
    <groupId>com.spotify</groupId>
27
    <artifactId>docker-client</artifactId>
28
    <version>8.16.0</version>
29
</dependency>
30
```
31

32
For Gradle projects:
33

34
```gradle
35
implementation 'com.spotify:docker-client:8.16.0'
36
```
37

38
## Basic Usage
39

40
### Creating a Docker Client
41

42
```java { .api }
43
import com.spotify.docker.client.*;
44
import com.spotify.docker.client.messages.*;
45
import com.spotify.docker.client.exceptions.DockerException;
46

47
// Create client from environment variables (DOCKER_HOST, DOCKER_CERT_PATH)
48
DockerClient docker = DefaultDockerClient.fromEnv().build();
49

50
// Or configure manually
51
DockerClient docker = DefaultDockerClient.builder()
52
    .uri("unix:///var/run/docker.sock")
53
    .connectionPoolSize(100)
54
    .build();
55
```
56

57
### Container Basics
58

59
```java { .api }
60
// Create and run a container
61
ContainerConfig config = ContainerConfig.builder()
62
    .image("nginx:latest")
63
    .exposedPorts("80/tcp")
64
    .build();
65

66
ContainerCreation container = docker.createContainer(config);
67
docker.startContainer(container.id());
68

69
// List containers
70
List<Container> containers = docker.listContainers();
71

72
// Stop and remove
73
docker.stopContainer(container.id(), 10);
74
docker.removeContainer(container.id());
75
```
76

77
### Image Operations
78

79
```java { .api }
80
// Pull an image
81
docker.pull("ubuntu:20.04");
82

83
// Build from Dockerfile
84
String imageId = docker.build(
85
    Paths.get("/path/to/dockerfile/directory"),
86
    "my-image:latest"
87
);
88

89
// List images
90
List<Image> images = docker.listImages();
91
```
92

93
## Core API Components
94

95
### DockerClient Interface
96

97
The primary interface for all Docker operations:
98

99
```java { .api }
100
public interface DockerClient extends Closeable {
101
    // System operations
102
    String ping() throws DockerException, InterruptedException;
103
    Version version() throws DockerException, InterruptedException;
104
    Info info() throws DockerException, InterruptedException;
105
    
106
    // Container management
107
    List<Container> listContainers(ListContainersParam... params) throws DockerException, InterruptedException;
108
    ContainerCreation createContainer(ContainerConfig config) throws DockerException, InterruptedException;
109
    void startContainer(String containerId) throws DockerException, InterruptedException;
110
    void stopContainer(String containerId, int secondsToWaitBeforeKilling) throws DockerException, InterruptedException;
111
    
112
    // Image management  
113
    List<Image> listImages(ListImagesParam... params) throws DockerException, InterruptedException;
114
    void pull(String image) throws DockerException, InterruptedException;
115
    String build(Path directory, String name, BuildParam... params) throws DockerException, InterruptedException;
116
    
117
    // And 100+ more methods...
118
}
119
```
120

121
### Builder Pattern
122

123
Most configuration objects use Google's AutoValue builder pattern:
124

125
```java { .api }
126
ContainerConfig config = ContainerConfig.builder()
127
    .image("nginx:latest")
128
    .hostname("web-server")
129
    .env("ENV_VAR=value")
130
    .exposedPorts("80/tcp", "443/tcp")
131
    .build();
132

133
HostConfig hostConfig = HostConfig.builder()
134
    .portBindings(Map.of("80/tcp", List.of(PortBinding.of("0.0.0.0", "8080"))))
135
    .memory(512L * 1024 * 1024) // 512MB
136
    .cpuShares(512)
137
    .build();
138
```
139

140
### Parameter Classes
141

142
Type-safe parameter classes for filtering and options:
143

144
```java { .api }
145
// Container listing parameters
146
List<Container> running = docker.listContainers(
147
    ListContainersParam.withStatusRunning()
148
);
149

150
List<Container> labeled = docker.listContainers(
151
    ListContainersParam.withLabel("env", "production")
152
);
153

154
// Image listing parameters  
155
List<Image> danglingImages = docker.listImages(
156
    ListImagesParam.danglingImages()
157
);
158
```
159

160
## Exception Handling
161

162
The library provides comprehensive exception handling:
163

164
```java { .api }
165
import com.spotify.docker.client.exceptions.ContainerNotFoundException;
166
import com.spotify.docker.client.exceptions.NotFoundException;
167

168
try {
169
    ContainerInfo info = docker.inspectContainer("nonexistent");
170
} catch (ContainerNotFoundException e) {
171
    // Handle missing container
172
} catch (NotFoundException e) {
173
    // Handle general not found
174
} catch (DockerException e) {
175
    // Handle Docker API errors
176
}
177
```
178

179
## Resource Management
180

181
Always close resources properly:
182

183
```java { .api }
184
// Auto-closeable client
185
try (DockerClient docker = DefaultDockerClient.fromEnv().build()) {
186
    // Docker operations
187
}
188

189
// Log streams
190
try (LogStream logs = docker.logs(containerId, LogsParam.stdout())) {
191
    String output = logs.readFully();
192
}
193

194
// Event streams
195
try (EventStream events = docker.events()) {
196
    while (events.hasNext()) {
197
        Event event = events.next();
198
        System.out.println("Event: " + event.status());
199
    }
200
}
201
```
202

203
## Sub-Documentation
204

205
This library covers extensive Docker functionality organized into specialized areas:
206

207
- **[Client Configuration](./client-configuration.md)** - Client setup, authentication, SSL certificates, and connection management
208
- **[Container Operations](./containers.md)** - Complete container lifecycle including create, start, stop, exec, logs, and file operations
209
- **[Image Management](./images.md)** - Building, pulling, pushing, tagging, and managing Docker images  
210
- **[Network Management](./networks.md)** - Creating and managing Docker networks and container connectivity
211
- **[Volume Operations](./volumes.md)** - Docker volume creation, inspection, and lifecycle management
212
- **[Docker Swarm](./swarm.md)** - Full swarm mode support including services, tasks, nodes, secrets, and configs
213

214
## Key Features
215

216
- **Comprehensive API Coverage**: 186+ Java classes covering all Docker Engine APIs
217
- **Type Safety**: Immutable message classes and type-safe parameter handling
218
- **Authentication**: Multiple authentication strategies for private registries
219
- **Connection Management**: HTTP/HTTPS, Unix sockets, connection pooling
220
- **Progress Tracking**: Real-time progress handlers for long-running operations
221
- **Exception Handling**: Specific exception types for different error conditions
222
- **Resource Streams**: Streaming APIs for logs, events, and file operations
223
- **Docker Swarm**: Complete orchestration support for production deployments
224

225
## Quick Examples
226

227
### Health Check Container
228

229
```java { .api }
230
// Create a simple health check container
231
ContainerConfig config = ContainerConfig.builder()
232
    .image("nginx:latest")
233
    .healthcheck(HealthConfig.builder()
234
        .test("CMD curl -f http://localhost/ || exit 1")
235
        .interval(Duration.ofSeconds(30))
236
        .timeout(Duration.ofSeconds(10))
237
        .retries(3)
238
        .build())
239
    .build();
240

241
ContainerCreation container = docker.createContainer(config);
242
docker.startContainer(container.id());
243
```
244

245
### Monitor Events
246

247
```java { .api }
248
// Monitor Docker events in real-time
249
try (EventStream eventStream = docker.events(
250
    EventsParam.since(System.currentTimeMillis() / 1000),
251
    EventsParam.type(Event.Type.CONTAINER)
252
)) {
253
    while (eventStream.hasNext()) {
254
        Event event = eventStream.next();
255
        System.out.printf("Container %s: %s%n", 
256
            event.id(), event.status());
257
    }
258
}
259
```
260

261
The Spotify Docker Client provides a robust, production-ready foundation for Java applications that need to integrate with Docker infrastructure.