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.