https://github.com/devnatan/docker-kotlin
Docker Engine Remote API client
https://github.com/devnatan/docker-kotlin
api client docker docker-kotlin engine java jvm kotlin multiplatform
Last synced: 4 months ago
JSON representation
Docker Engine Remote API client
- Host: GitHub
- URL: https://github.com/devnatan/docker-kotlin
- Owner: devnatan
- License: mit
- Created: 2021-08-05T02:51:17.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2026-01-28T15:21:43.000Z (5 months ago)
- Last Synced: 2026-01-29T06:49:51.605Z (5 months ago)
- Topics: api, client, docker, docker-kotlin, engine, java, jvm, kotlin, multiplatform
- Language: Kotlin
- Homepage: https://docs.devnatan.me/docker-kotlin
- Size: 1.05 MB
- Stars: 29
- Watchers: 3
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Support: SUPPORTED_ENDPOINTS.md
Awesome Lists containing this project
README
# docker-kotlin
docker-kotlin allows you to interact with the Docker Engine Remote API.
```kotlin
dependencies {
implementation("me.devnatan:docker-kotlin:0.14.4")
}
```
> [!NOTE]
> Docker Kotlin **currently supports JVM runtime only**. Native platform support (Linux, macOS, Windows, etc.) is under active development in [#209](https://github.com/devnatan/docker-kotlin/pull/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`](https://docs.docker.com/compose/environment-variables/envvars/#docker_host)
if present otherwise `unix://var/run/docker.sock` if the current platform is Unix-like.
```kotlin
val client = DockerClient {
// this: DockerClientConfigBuilder
}
```
## Resources
* [System](#system)
* [Containers](#containers)
* [Networks](#networks)
* [Exec](#exec)
### System
#### Get Docker Version
```kotlin
val version: SystemVersion = client.system.version()
```
### Containers
#### Create and start a Container with explicit port bindings
```kotlin
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
```kotlin
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
```kotlin
val containers: List = client.containers.list()
```
#### Logs
##### Get logs from a container
```kotlin
val result = client.containers.logs(containerId) {
stdout = true
stderr = true
} as ContainerLogsResult.Complete
println(result.output)
```
##### Stream logs in real-time
```kotlin
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
```kotlin
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
```kotlin
val result = client.containers.logs(containerId) {
stdout = true
tail = "100"
}
```
##### Get logs with timestamps
```kotlin
val result = client.containers.logs(containerId) {
stdout = true
timestamps = true
}
```
##### Get logs since a specific time
```kotlin
val result = client.containers.logs(containerId) {
stdout = true
since = "10m" // last 10 minutes
// or: since = "1609459200" // Unix timestamp
}
```
#### Stream logs using convenience method
```kotlin
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
```kotlin
val networkId: String = client.networks.create {
name = "octopus-net"
driver = "overlay"
}
```
#### List all Networks
```kotlin
val networks = client.networks.list()
```
#### Connect a container to a network
```kotlin
client.networks.connect(networkId, containerId)
```
### Exec
#### Execute a command in a running container
```kotlin
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
```kotlin
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
```kotlin
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
```kotlin
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
```kotlin
client.containers.copyFileFrom(
container = containerId,
sourcePath = "/var/log/app.log",
destinationPath = "/tmp/app.log"
)
```
##### Copy a file from host to container
```kotlin
client.containers.copyFileTo(
container = "bailarina-caputina",
sourcePath = "/home/user/config.json",
destinationPath = "/app/config/"
)
```
#### Copy a directory from container to host
```kotlin
client.containers.copyDirectoryFrom(
container = "knoten",
sourcePath = "/app/logs",
destinationPath = "/tmp/container-logs"
)
```
#### Copy a directory from host to container
```kotlin
client.containers.copyDirectoryTo(
container = "globson",
sourcePath = "/home/user/configs",
destinationPath = "/app/"
)
```
#### Advanced copy with custom options
```kotlin
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.