docker-kotlin

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

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

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 createdContainerId = client.containers.create("busybox:latest") {
    // Only if your container doesn't already expose this port
    exposedPort(80u)
    
    hostConfig {
        portBindings(80u)
    }
}

client.containers.start(createdContainerId)

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

List All Containers

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

Logs

Get logs from a container

val result = client.containers.logs(containerId) {
    stdout = true
    stderr = true
} as ContainerLogsResult.Complete

println(result.output)

Stream logs in real-time

val result = client.containers.logs(containerId) {
    stdout = true
    stderr = true
    follow = true
} as ContainerLogsResult.Stream

result.output.collect { frame ->
    println(frame.value)
}

Get logs with separated stdout/stderr

val result = client.containers.logs(containerId, demux = true) {
    stdout = true
    stderr = true
} as ContainerLogsResult.CompleteDemuxed

println("STDOUT: ${result.stdout}")
println("STDERR: ${result.stderr}")

Get last N lines of logs

val result = client.containers.logs(containerId) {
    stdout = true
    tail = "100"
}

Get logs with timestamps

val result = client.containers.logs(containerId) {
    stdout = true
    timestamps = true
}

Get logs since a specific time

val result = client.containers.logs(containerId) {
    stdout = true
    since = "10m"      // last 10 minutes
    // or: since = "1609459200"  // Unix timestamp
}

Stream logs using convenience method

client.containers.logsAsFlow(containerId) {
    stdout = true
    stderr = true
    follow = true
}.collect { frame ->
    val prefix = if (frame.stream == Stream.StdErr) "[ERR]" else "[OUT]"
    print("$prefix ${frame.value}")
}

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
}

when (
    val result = client.exec.start(execId, ExecStartOptions())
) {
    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
}

when (
    val result = client.exec.start(execId) { demux = true }
) {
    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.