README.md

docker-client

A Docker client library for Kotlin/JVM and Kotlin/Native.

Status

🚧 This project is an ongoing work in progress. It is used by Batect as of v0.80, and should be stable enough for production use.

However, it only has the APIs required by Batect. Others are likely missing. If you require an API not provided here, please open a new issue.

How to use

Referencing in Gradle

Using the Kotlin Gradle DSL:

dependencies {
  implementation("dev.batect.docker:client:<version number here>") // Get the latest version number from https://github.com/batect/docker-client/releases/latest
}

Check the releases page for the latest release information, and the Maven Central page for examples of how to reference the library in other build systems.

Usage samples

Full sample projects demonstrating how to use this library are available in the samples directory.

Create a client

val client = DockerClient.create()

Pull an image

val image = client.pullImage("ubuntu:22.04")

Run a container

val containerSpec = ContainerCreationSpec.Builder(image)
    .withTTY()
    .withStdinAttached()
    .build()

val container = client.createContainer(containerSpec)

try {
    val exitCode = client.run(container, TextOutput.StandardOutput, TextOutput.StandardError, TextInput.StandardInput)

    println("Container exited with code $exitCode.")
} finally {
    client.removeContainer(container, force = true)
}

Documentation

Dokka documentation for the latest version of the library is available at https://batect.github.io/docker-client/.

Requirements

Operating system and architecture

This library supports the following:

Operating system	Architecture	Kotlin/JVM	Kotlin/Native
macOS	x64 (Intel)	✅	✅
macOS	ARM64 (Silicon)	✅	✅
Linux	x64	✅	✅
Linux	ARM64	✅	❌
Windows	x64	✅	✅

Support for ARM64 Linux with Kotlin/Native will be added once Okio supports it (see square/okio#1242).

Docker daemon

This library supports Docker 19.03.10 or later. However, using the most recent version of Docker is highly recommended.

This library may work with earlier versions of Docker, but this is untested and unsupported.

How is this different to other Docker client libraries?

(or: why have you created another client library?)

There are two major differences compared to other client libraries:

• This library supports both Kotlin/JVM and Kotlin/Native, whereas most other existing libraries only support the JVM.

• This library embeds the official Golang Docker client libraries, rather than invoking the docker executable or calling the Docker API itself.

  This makes it much easier to add support for new Docker features and easier to provide features that require a lot of client logic (eg. BuildKit) without sacrificing performance.