To start using docker-java
, you need to add at least two dependencies:
com.github.docker-java:docker-java-core
for theDockerClient
- one of
com.github.docker-java:docker-java-transport-*
to communicate with the Docker daemon. See Available Transports for more info.
You will need an instance of DockerClientConfig
to tell the library how to access Docker, which credentials to use to pull from Docker registries, etc etc.
The builder is available and allows you to configure every property of the client:
import com.github.dockerjava.core.DockerClientConfig
import com.github.dockerjava.core.DefaultDockerClientConfig
DockerClientConfig standard = DefaultDockerClientConfig.createDefaultConfigBuilder().build();
import com.github.dockerjava.core.DockerClientConfig
import com.github.dockerjava.core.DefaultDockerClientConfig
DockerClientConfig custom = DefaultDockerClientConfig.createDefaultConfigBuilder()
.withDockerHost("tcp://docker.somewhere.tld:2376")
.withDockerTlsVerify(true)
.withDockerCertPath("/home/user/.docker")
.withRegistryUsername(registryUser)
.withRegistryPassword(registryPass)
.withRegistryEmail(registryMail)
.withRegistryUrl(registryUrl)
.build();
Here you can tune registry auth, DOCKER_HOST and other options.
There are a couple of configuration items, all of which have sensible defaults:
DOCKER_HOST
The Docker Host URL, e.g.tcp://localhost:2376
orunix:///var/run/docker.sock
DOCKER_TLS_VERIFY
enable/disable TLS verification (switch betweenhttp
andhttps
protocol)DOCKER_CERT_PATH
Path to the certificates needed for TLS verificationDOCKER_CONFIG
Path for additional docker configuration files (like.dockercfg
)api.version
The API version, e.g.1.23
.registry.url
Your registry's address.registry.username
Your registry username (required to push containers).registry.password
Your registry password.registry.email
Your registry email.
There are three ways to configure, in descending order of precedence:
DOCKER_HOST=tcp://localhost:2376
DOCKER_TLS_VERIFY=1
DOCKER_CERT_PATH=/home/user/.docker/certs
DOCKER_CONFIG=/home/user/.docker
api.version=1.23
registry.url=https://index.docker.io/v1/
registry.username=dockeruser
registry.password=ilovedocker
[email protected]
java -DDOCKER_HOST=tcp://localhost:2375 -Dregistry.username=dockeruser pkg.Main
export DOCKER_HOST=tcp://localhost:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/home/user/.docker/certs
export DOCKER_CONFIG=/home/user/.docker
In $HOME/.docker-java.properties
In the class path at /docker-java.properties
Should you need to customize the Jackson's ObjectMapper
used by docker-java
, you can create your own DockerClientConfig
and override DockerClientConfig#getObjectMapper()
.
Once you decided which transport to use, you will need to instantiate an HTTP client:
DockerClientConfig config = ...;
DockerHttpClient httpClient = new ApacheDockerHttpClient.Builder()
.dockerHost(config.getDockerHost())
.sslConfig(config.getSSLConfig())
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(30))
.responseTimeout(Duration.ofSeconds(45))
.build();
Please refer to selected transport's builder for other available configuration options (like timeouts).
Once you have an HTTP client, you can make raw requests to the Docker daemon directly:
Request request = Request.builder()
.method(Request.Method.GET)
.path("/_ping")
.build();
try (Response response = httpClient.execute(request)) {
assertThat(response.getStatusCode(), equalTo(200));
assertThat(IOUtils.toString(response.getBody()), equalTo("OK"));
}
To get an instance of DockerClient
, you need to pass both DockerClientConfig
and DockerHttpClient
:
DockerClient dockerClient = DockerClientImpl.getInstance(config, httpClient);
Once you have it, you can start executing Docker commands:
dockerClient.pingCmd().exec();