0
# Client Configuration
1

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

4
## Creating Docker Clients
5

6
### Environment-Based Configuration
7

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

10
```java { .api }
11
import com.spotify.docker.client.*;
12
import com.spotify.docker.client.exceptions.DockerCertificateException;
13

14
// Create from environment
15
DockerClient docker = DefaultDockerClient.fromEnv().build();
16
```
17

18
### Builder Configuration
19

20
For custom configuration, use the builder pattern:
21

22
```java { .api }
23
DockerClient docker = DefaultDockerClient.builder()
24
    .uri("https://docker.example.com:2376")
25
    .connectionPoolSize(50)
26
    .connectTimeoutMillis(30000)
27
    .readTimeoutMillis(60000)
28
    .build();
29
```
30

31
## Connection Types
32

33
### Unix Socket Connection
34

35
For local Docker daemon access on Linux/macOS:
36

37
```java { .api }
38
DockerClient docker = DefaultDockerClient.builder()
39
    .uri("unix:///var/run/docker.sock")
40
    .build();
41

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

46
### Named Pipe Connection (Windows)
47

48
For Windows Docker Desktop:
49

50
```java { .api }
51
DockerClient docker = DefaultDockerClient.builder()
52
    .uri("npipe:////./pipe/docker_engine")
53
    .build();
54
```
55

56
### TCP Connection
57

58
For remote Docker daemon access:
59

60
```java { .api }
61
DockerClient docker = DefaultDockerClient.builder()
62
    .uri("tcp://docker.example.com:2376")
63
    .build();
64
```
65

66
### HTTPS Connection with TLS
67

68
For secure remote connections:
69

70
```java { .api }
71
DockerClient docker = DefaultDockerClient.builder()
72
    .uri("https://docker.example.com:2376")
73
    .dockerCertificates(new DockerCertificates(Paths.get("/path/to/certs")))
74
    .build();
75
```
76

77
## SSL Certificates and Security
78

79
### Using DockerCertificates
80

81
```java { .api }
82
import com.spotify.docker.client.DockerCertificates;
83
import java.nio.file.Paths;
84

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

88
DockerClient docker = DefaultDockerClient.builder()
89
    .uri("https://docker.example.com:2376")
90
    .dockerCertificates(certs)
91
    .build();
92
```
93

94
### Certificate Files
95

96
The certificate directory should contain:
97
- `ca.pem` - Certificate authority
98
- `cert.pem` - Client certificate  
99
- `key.pem` - Client private key
100

101
```java { .api }
102
Path certPath = Paths.get(System.getProperty("user.home"), ".docker", "machine-name");
103
DockerCertificates certs = new DockerCertificates(certPath);
104
```
105

106
### DockerCertificatesStore
107

108
For advanced certificate management:
109

110
```java { .api }
111
import com.spotify.docker.client.DockerCertificatesStore;
112

113
DockerCertificatesStore certStore = DockerCertificates.builder()
114
    .dockerCertPath(Paths.get("/path/to/certs"))
115
    .caCertPath(Paths.get("/path/to/ca.pem"))
116
    .clientKeyPath(Paths.get("/path/to/key.pem"))
117
    .clientCertPath(Paths.get("/path/to/cert.pem"))
118
    .build()
119
    .orElse(null);
120

121
DockerClient docker = DefaultDockerClient.builder()
122
    .dockerCertificates(certStore)
123
    .build();
124
```
125

126
## Connection Pool Configuration
127

128
### Basic Pool Settings
129

130
```java { .api }
131
DockerClient docker = DefaultDockerClient.builder()
132
    .uri("https://docker.example.com:2376")
133
    .connectionPoolSize(100)  // Maximum concurrent connections
134
    .build();
135
```
136

137
### Timeout Configuration
138

139
```java { .api }
140
DockerClient docker = DefaultDockerClient.builder()
141
    .connectTimeoutMillis(30000)    // 30 second connect timeout
142
    .readTimeoutMillis(300000)      // 5 minute read timeout
143
    .connectionPoolSize(50)
144
    .build();
145
```
146

147
## Registry Authentication
148

149
### Authentication Suppliers
150

151
The library provides several authentication mechanisms:
152

153
```java { .api }
154
import com.spotify.docker.client.auth.*;
155

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

159
DockerClient docker = DefaultDockerClient.builder()
160
    .registryAuthSupplier(authSupplier)
161
    .build();
162
```
163

164
### Fixed Registry Authentication
165

166
```java { .api }
167
RegistryAuth auth = RegistryAuth.builder()
168
    .username("myuser")
169
    .password("mypass")
170
    .email("user@example.com")
171
    .serverAddress("https://index.docker.io/v1/")
172
    .build();
173

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

178
DockerClient docker = DefaultDockerClient.builder()
179
    .registryAuthSupplier(authSupplier)
180
    .build();
181
```
182

183
### Multiple Registry Authentication
184

185
```java { .api }
186
RegistryAuthSupplier dockerHub = new ConfigFileRegistryAuthSupplier();
187
RegistryAuthSupplier gcr = new ContainerRegistryAuthSupplier(
188
    "path/to/service-account.json", "my-project"
189
);
190

191
RegistryAuthSupplier multiAuth = new MultiRegistryAuthSupplier(
192
    dockerHub, gcr
193
);
194

195
DockerClient docker = DefaultDockerClient.builder()
196
    .registryAuthSupplier(multiAuth)
197
    .build();
198
```
199

200
### Google Container Registry
201

202
```java { .api }
203
import com.spotify.docker.client.auth.gcr.ContainerRegistryAuthSupplier;
204

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

210
DockerClient docker = DefaultDockerClient.builder()
211
    .registryAuthSupplier(gcrAuth)
212
    .build();
213
```
214

215
## Configuration from Docker Environment
216

217
### Reading Docker Configuration
218

219
```java { .api }
220
import com.spotify.docker.client.DockerConfigReader;
221

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

225
// Read from specific path  
226
DockerConfig config = DockerConfigReader.fromConfigPath(
227
    Paths.get("/custom/config.json")
228
);
229

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

234
### Environment Variables
235

236
The client automatically recognizes these environment variables:
237

238
- `DOCKER_HOST` - Docker daemon endpoint
239
- `DOCKER_CERT_PATH` - Path to certificate directory  
240
- `DOCKER_TLS_VERIFY` - Enable TLS verification
241

242
```java { .api }
243
// Automatically uses environment variables
244
DockerClient docker = DefaultDockerClient.fromEnv().build();
245

246
// Override specific settings
247
DockerClient docker = DefaultDockerClient.fromEnv()
248
    .connectionPoolSize(200)
249
    .readTimeoutMillis(120000)
250
    .build();
251
```
252

253
## Advanced Configuration
254

255
### Custom Headers
256

257
```java { .api }
258
DockerClient docker = DefaultDockerClient.builder()
259
    .uri("https://docker.example.com:2376")
260
    .header("X-Custom-Header", "value")
261
    .header("Authorization", "Bearer " + token)
262
    .build();
263
```
264

265
### Proxy Configuration
266

267
```java { .api }
268
// System properties based proxy
269
System.setProperty("http.proxyHost", "proxy.example.com");
270
System.setProperty("http.proxyPort", "8080");
271

272
DockerClient docker = DefaultDockerClient.builder()
273
    .uri("https://docker.example.com:2376")
274
    .useProxy(true)
275
    .build();
276
```
277

278
### Request Entity Processing
279

280
```java { .api }
281
import org.glassfish.jersey.client.ClientProperties;
282

283
DockerClient docker = DefaultDockerClient.builder()
284
    .requestEntityProcessing(ClientProperties.RequestEntityProcessing.CHUNKED)
285
    .build();
286
```
287

288
## Configuration Examples
289

290
### Production Configuration
291

292
```java { .api }
293
DockerClient docker = DefaultDockerClient.builder()
294
    .uri("https://docker-prod.example.com:2376")
295
    .dockerCertificates(new DockerCertificates(
296
        Paths.get("/etc/docker/certs")))
297
    .connectionPoolSize(100)
298
    .connectTimeoutMillis(30000)
299
    .readTimeoutMillis(300000)
300
    .registryAuthSupplier(new ConfigFileRegistryAuthSupplier())
301
    .build();
302
```
303

304
### Development Configuration
305

306
```java { .api }
307
DockerClient docker = DefaultDockerClient.builder()
308
    .uri("unix:///var/run/docker.sock")
309
    .connectionPoolSize(10)
310
    .connectTimeoutMillis(10000)
311
    .readTimeoutMillis(60000)
312
    .build();
313
```
314

315
### Multi-Environment Configuration
316

317
```java { .api }
318
public class DockerClientFactory {
319
    
320
    public static DockerClient createClient(Environment env) {
321
        DefaultDockerClient.Builder builder = DefaultDockerClient.builder();
322
        
323
        switch (env) {
324
            case LOCAL:
325
                return builder
326
                    .uri("unix:///var/run/docker.sock")
327
                    .build();
328
                    
329
            case STAGING:
330
                return builder
331
                    .uri("https://docker-staging.example.com:2376")
332
                    .dockerCertificates(loadCertificates("staging"))
333
                    .connectionPoolSize(50)
334
                    .build();
335
                    
336
            case PRODUCTION:
337
                return builder
338
                    .uri("https://docker-prod.example.com:2376")
339
                    .dockerCertificates(loadCertificates("production"))
340
                    .connectionPoolSize(200)
341
                    .connectTimeoutMillis(30000)
342
                    .readTimeoutMillis(300000)
343
                    .registryAuthSupplier(createAuthSupplier())
344
                    .build();
345
        }
346
    }
347
    
348
    private static DockerCertificates loadCertificates(String env) {
349
        Path certPath = Paths.get("/etc/docker/certs", env);
350
        return new DockerCertificates(certPath);
351
    }
352
}
353
```
354

355
## Builder Reference
356

357
### DefaultDockerClient.Builder Methods
358

359
```java { .api }
360
public class DefaultDockerClient.Builder {
361
    Builder uri(String uri);
362
    Builder uri(URI uri);
363
    Builder dockerCertificates(DockerCertificatesStore dockerCertificatesStore);
364
    Builder connectionPoolSize(int connectionPoolSize);
365
    Builder connectTimeoutMillis(long connectTimeoutMillis);  
366
    Builder readTimeoutMillis(long readTimeoutMillis);
367
    Builder registryAuthSupplier(RegistryAuthSupplier registryAuthSupplier);
368
    Builder header(String name, String value);
369
    Builder useProxy(boolean useProxy);
370
    Builder requestEntityProcessing(RequestEntityProcessing processing);
371
    DockerClient build();
372
}
373
```
374

375
## Connection Troubleshooting
376

377
### Common Issues
378

379
```java { .api }
380
try {
381
    DockerClient docker = DefaultDockerClient.fromEnv().build();
382
    String response = docker.ping();
383
    System.out.println("Docker daemon is reachable: " + response);
384
} catch (DockerException e) {
385
    System.err.println("Cannot connect to Docker daemon: " + e.getMessage());
386
    // Check DOCKER_HOST environment variable
387
    // Verify Docker daemon is running
388
    // Check certificate paths and permissions
389
}
390
```
391

392
### Connection Validation
393

394
```java { .api }
395
public boolean validateDockerConnection(DockerClient docker) {
396
    try {
397
        String ping = docker.ping();
398
        Version version = docker.version();
399
        Info info = docker.info();
400
        
401
        System.out.println("Ping: " + ping);
402
        System.out.println("Version: " + version.version());
403
        System.out.println("API Version: " + version.apiVersion());
404
        System.out.println("Containers: " + info.containers());
405
        
406
        return true;
407
    } catch (DockerException | InterruptedException e) {
408
        System.err.println("Connection validation failed: " + e.getMessage());
409
        return false;
410
    }
411
}
412
```
413

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