docker-kotlin

docker-kotlin allows you to interact with the Docker Engine Remote API.

dependencies {
    implementation("me.devnatan:docker-kotlin:0.11.1")
}

Note

Docker Kotlin currently supports JVM runtime only. Native platform support (Linux, macOS, Windows, etc.) is under active development in #209.

If you attempt to use Docker Kotlin on native targets before this work is complete, you'll encounter NotImplementedError. We're working hard to bring full multiplatform support soon!

Basic Usage

Use DockerKotlin { ... } to create a new Docker client instance with the default settings. Default settings are based on the current platform or environment variables, e.g.: socket path will be set to DOCKER_HOST if present otherwise unix://var/run/docker.sock if the current platform is Unix-like.

val client = DockerClient {
    // this: DockerClientConfigBuilder
}

Resources

• System
• Containers
• Networks
• Exec

System

Get Docker Version

val version: SystemVersion = client.system.version()

Containers

Create and start a Container with explicit port bindings

val containerId = client.containers.create("busybox:latest") {
    // Only if your container doesn't already expose this port
    exposedPort(80u)

    hostConfig {
        portBindings(80u) {
            add(PortBinding("0.0.0.0", 8080u))
        }
    }
}

client.containers.start(containerId)

Create and start a Container with auto-assigned port bindings

val containerId = client.containers.create("busybox:latest") {
    // Only if your container doesn't already expose this port
    exposedPort(80u)
    
    hostConfig {
        portBindings(80u)
    }
}

client.containers.start(containerId)

// Inspect the container to retrieve the auto-assigned ports
val container = testClient.containers.inspect(id)
val ports = container.networkSettings.ports

List All Containers

val containers: List<Container> = client.containers.list()

Stream Container Logs

val logs: Flow<Frame> = client.containers.logs("floral-fury") {
    stderr = true
    stdout = true
}

logs.onStart { /* streaming started */ }
    .onCompletion { /* streaming finished */ }
    .catch { /* something went wrong */ }
    .collect { log -> /* do something with each log */ }

Networks

Create a new Network

val networkId: String = client.networks.create {
    name = "octopus-net"
    driver = "overlay"
}

List all Networks

val networks = client.networks.list()

Connect a container to a network

client.networks.connect(networkId, containerId)

Exec

Execute a command in a running container

val execId = client.exec.create(containerId) {
    command = listOf("echo", "Hello, Docker!")
    attachStdout = true
}

val result = client.exec.start(execId, ExecStartOptions())
when (result) {
    is ExecStartResult.Complete -> println(result.output)
    else -> error("Unexpected result")
}

Execute a command with streaming output

val execId = client.exec.create(containerId) {
    command = listOf("sh", "-c", "for i in 1 2 3; do echo line \$i; sleep 1; done")
    attachStdout = true
}

val result = client.exec.start(execId) { stream = true }
when (result) {
    is ExecStartResult.Stream -> {
        result.output.collect { chunk ->
            print(chunk)
        }
    }
    else -> error("Unexpected result")
}

Execute a command with separated stdout/stderr

val execId = client.exec.create(containerId) {
    command = listOf("sh", "-c", "echo stdout; echo stderr >&2")
    attachStdout = true
    attachStderr = true
}

val result = client.exec.start(execId) { demux = true }
when (result) {
    is ExecStartResult.CompleteDemuxed -> {
        println("STDOUT: ${result.output.stdout}")
        println("STDERR: ${result.output.stderr}")
    }
    else -> error("Unexpected result")
}

Check exec exit code

val execId = client.exec.create(containerId) {
    command = listOf("false")
}

client.exec.start(execId) { detach = true }

val execInfo = client.exec.inspect(execId)
println("Exit code: ${execInfo.exitCode}") // Exit code: 1

File Operations

Copy a file from container to host

client.containers.copyFileFrom(
    container = containerId,
    sourcePath = "/var/log/app.log",
    destinationPath = "/tmp/app.log"
)

Copy a file from host to container

client.containers.copyFileTo(
    container = "bailarina-caputina",
    sourcePath = "/home/user/config.json",
    destinationPath = "/app/config/"
)

Copy a directory from container to host

client.containers.copyDirectoryFrom(
    container = "knoten",
    sourcePath = "/app/logs",
    destinationPath = "/tmp/container-logs"
)

Copy a directory from host to container

client.containers.copyDirectoryTo(
    container = "globson",
    sourcePath = "/home/user/configs",
    destinationPath = "/app/"
)

Advanced copy with custom options

client.containers.copyTo(
    container = "tapioca",
    destinationPath = "/app/data",
    tarArchive = myTarArchive
) {
    path = "/app/data"
    noOverwriteDirNonDir = true  // Don't overwrite if types mismatch
    copyUIDGID = true            // Preserve UID/GID
}

// Get raw tar archive from container
val result = client.containers.copyFrom(containerId, "/app/config")
val tarData = result.archiveData

// Archive info including file metadata
val stats = result.stat 

License

docker-kotlin is licensed under the MIT license.