Quarkus Docker Client

The Quarkus Docker Client extension provides seamless integration with Docker through a native Java API. It supports multiple named clients, automatic platform-specific socket detection, and built-in health checks.

Key features:

  • Multiple named Docker client instances for different environments

  • Automatic platform-specific Docker daemon socket detection

  • Health check integration for Docker daemon connectivity

  • Registry authentication support

  • TLS/SSL configuration for secure daemon communication

Installation

If you want to use this extension, you need to add the io.quarkiverse.docker:quarkus-docker-client extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.docker</groupId>
    <artifactId>quarkus-docker-client</artifactId>
    <version>0.0.4</version>
</dependency>

Usage

Default Client

Inject the default Docker client:

@Inject
DockerClient dockerClient;

// Use the client
dockerClient.pingCmd().exec();

Named Clients

Configure and use multiple Docker clients:

# Default client configuration
quarkus.docker.docker-host=tcp://localhost:2375

# Production client configuration
quarkus.docker."production".docker-host=tcp://prod-host:2375
quarkus.docker."production".enabled=true
@Inject
@NamedDockerClient("production")
DockerClient productionClient;

Health Checks

Enable health checks to monitor Docker daemon connectivity:

quarkus.docker.health-check=true

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.docker.enabled

Determines whether this Docker client configuration is enabled.

For the clients, this is true by default.

Configuration property: quarkus.docker.[client-name.]enabled

Environment variable: QUARKUS_DOCKER_ENABLED

boolean

true

quarkus.docker.connect-timeout

Specifies the connection timeout when connecting to the Docker daemon.

This timeout applies to the initial connection establishment. If the connection cannot be established within this time, a timeout exception will be thrown.

Configuration property: quarkus.docker.[client-name.]connect-timeout

Environment variable: QUARKUS_DOCKER_CONNECT_TIMEOUT

Duration 

10S

quarkus.docker.read-timeout

Specifies the read timeout for Docker API operations.

This timeout applies to individual API operations after the connection has been established. If an operation takes longer than this timeout, it will be interrupted.

Configuration property: quarkus.docker.[client-name.]read-timeout

Environment variable: QUARKUS_DOCKER_READ_TIMEOUT

Duration 

30S

quarkus.docker.docker-host

Specifies the Docker daemon host URL.

Supported formats include:

  • tcp://host:port

  • unix:///path/to/socket

  • npipe:////./pipe/docker_engine (Windows)

If not specified, the default will be platform-specific: unix:///var/run/docker.sock for Unix-like systems and npipe:////./pipe/docker_engine for Windows.

Configuration property: quarkus.docker.[client-name.]docker-host

Environment variable: QUARKUS_DOCKER_DOCKER_HOST

string

quarkus.docker.docker-config

Specifies the path to the Docker config file.

This file contains registry authentication details and other Docker configuration. If not specified, the default location (~/.docker/config.json) will be used.

Configuration property: quarkus.docker.[client-name.]docker-config

Environment variable: QUARKUS_DOCKER_DOCKER_CONFIG

string

quarkus.docker.api-version

Specifies the Docker API version to use.

If not specified, the latest supported version will be negotiated with the Docker daemon automatically.

Configuration property: quarkus.docker.[client-name.]api-version

Environment variable: QUARKUS_DOCKER_API_VERSION

string

quarkus.docker.docker-context

Specifies the Docker context to use.

Docker contexts allow switching between different Docker endpoints and their associated authentication settings.

Configuration property: quarkus.docker.[client-name.]docker-context

Environment variable: QUARKUS_DOCKER_DOCKER_CONTEXT

string

quarkus.docker.docker-cert-path

Specifies the path to the Docker TLS certificates.

Required when using TLS authentication with the Docker daemon. The directory should contain ca.pem, cert.pem, and key.pem files.

Configuration property: quarkus.docker.[client-name.]docker-cert-path

Environment variable: QUARKUS_DOCKER_DOCKER_CERT_PATH

string

quarkus.docker.docker-tls-verify

Determines whether to verify TLS certificates when connecting to the Docker daemon.

Should be enabled in production environments when using TLS.

Configuration property: quarkus.docker.[client-name.]docker-tls-verify

Environment variable: QUARKUS_DOCKER_DOCKER_TLS_VERIFY

boolean

quarkus.docker.registry-email

Specifies the email address for Docker registry authentication.

Configuration property: quarkus.docker.[client-name.]registry-email

Environment variable: QUARKUS_DOCKER_REGISTRY_EMAIL

string

quarkus.docker.registry-username

Specifies the username for Docker registry authentication.

Configuration property: quarkus.docker.[client-name.]registry-username

Environment variable: QUARKUS_DOCKER_REGISTRY_USERNAME

string

quarkus.docker.registry-password

Specifies the password for Docker registry authentication.

Configuration property: quarkus.docker.[client-name.]registry-password

Environment variable: QUARKUS_DOCKER_REGISTRY_PASSWORD

string

quarkus.docker.registry-url

Specifies the Docker registry URL.

Configuration property: quarkus.docker.[client-name.]registry-url

Environment variable: QUARKUS_DOCKER_REGISTRY_URL

string

quarkus.docker.health-check

Controls whether the Docker client health check is enabled.

When enabled, a health check will be registered that verifies the connection to the Docker daemon for all configured clients. This is useful for monitoring the availability of Docker services.

Configuration property: quarkus.docker.health-check

Example:

quarkus.docker.health-check=true

Environment variable: QUARKUS_DOCKER_HEALTH_CHECK

boolean

quarkus.docker."docker-client-name".enabled

Determines whether this Docker client configuration is enabled.

For the clients, this is true by default.

Configuration property: quarkus.docker.[client-name.]enabled

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__ENABLED

boolean

true

quarkus.docker."docker-client-name".connect-timeout

Specifies the connection timeout when connecting to the Docker daemon.

This timeout applies to the initial connection establishment. If the connection cannot be established within this time, a timeout exception will be thrown.

Configuration property: quarkus.docker.[client-name.]connect-timeout

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__CONNECT_TIMEOUT

Duration 

10S

quarkus.docker."docker-client-name".read-timeout

Specifies the read timeout for Docker API operations.

This timeout applies to individual API operations after the connection has been established. If an operation takes longer than this timeout, it will be interrupted.

Configuration property: quarkus.docker.[client-name.]read-timeout

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__READ_TIMEOUT

Duration 

30S

quarkus.docker."docker-client-name".docker-host

Specifies the Docker daemon host URL.

Supported formats include:

  • tcp://host:port

  • unix:///path/to/socket

  • npipe:////./pipe/docker_engine (Windows)

If not specified, the default will be platform-specific: unix:///var/run/docker.sock for Unix-like systems and npipe:////./pipe/docker_engine for Windows.

Configuration property: quarkus.docker.[client-name.]docker-host

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__DOCKER_HOST

string

quarkus.docker."docker-client-name".docker-config

Specifies the path to the Docker config file.

This file contains registry authentication details and other Docker configuration. If not specified, the default location (~/.docker/config.json) will be used.

Configuration property: quarkus.docker.[client-name.]docker-config

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__DOCKER_CONFIG

string

quarkus.docker."docker-client-name".api-version

Specifies the Docker API version to use.

If not specified, the latest supported version will be negotiated with the Docker daemon automatically.

Configuration property: quarkus.docker.[client-name.]api-version

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__API_VERSION

string

quarkus.docker."docker-client-name".docker-context

Specifies the Docker context to use.

Docker contexts allow switching between different Docker endpoints and their associated authentication settings.

Configuration property: quarkus.docker.[client-name.]docker-context

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__DOCKER_CONTEXT

string

quarkus.docker."docker-client-name".docker-cert-path

Specifies the path to the Docker TLS certificates.

Required when using TLS authentication with the Docker daemon. The directory should contain ca.pem, cert.pem, and key.pem files.

Configuration property: quarkus.docker.[client-name.]docker-cert-path

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__DOCKER_CERT_PATH

string

quarkus.docker."docker-client-name".docker-tls-verify

Determines whether to verify TLS certificates when connecting to the Docker daemon.

Should be enabled in production environments when using TLS.

Configuration property: quarkus.docker.[client-name.]docker-tls-verify

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__DOCKER_TLS_VERIFY

boolean

quarkus.docker."docker-client-name".registry-email

Specifies the email address for Docker registry authentication.

Configuration property: quarkus.docker.[client-name.]registry-email

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__REGISTRY_EMAIL

string

quarkus.docker."docker-client-name".registry-username

Specifies the username for Docker registry authentication.

Configuration property: quarkus.docker.[client-name.]registry-username

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__REGISTRY_USERNAME

string

quarkus.docker."docker-client-name".registry-password

Specifies the password for Docker registry authentication.

Configuration property: quarkus.docker.[client-name.]registry-password

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__REGISTRY_PASSWORD

string

quarkus.docker."docker-client-name".registry-url

Specifies the Docker registry URL.

Configuration property: quarkus.docker.[client-name.]registry-url

Environment variable: QUARKUS_DOCKER__DOCKER_CLIENT_NAME__REGISTRY_URL

string
About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.