{"id":44332559,"url":"https://github.com/joshrotenberg/docker-wrapper-kotlin","last_synced_at":"2026-02-11T10:10:22.364Z","repository":{"id":331991243,"uuid":"1132371680","full_name":"joshrotenberg/docker-wrapper-kotlin","owner":"joshrotenberg","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-13T19:52:57.000Z","size":386,"stargazers_count":0,"open_issues_count":24,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-02T07:38:22.044Z","etag":null,"topics":["docker","docker-compose","java","jvm","kotlin","testing-tools"],"latest_commit_sha":null,"homepage":"https://joshrotenberg.com/docker-wrapper-kotlin/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshrotenberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T20:48:58.000Z","updated_at":"2026-01-12T03:20:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joshrotenberg/docker-wrapper-kotlin","commit_stats":null,"previous_names":["joshrotenberg/docker-wrapper-kotlin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/joshrotenberg/docker-wrapper-kotlin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fdocker-wrapper-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fdocker-wrapper-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fdocker-wrapper-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fdocker-wrapper-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshrotenberg","download_url":"https://codeload.github.com/joshrotenberg/docker-wrapper-kotlin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshrotenberg%2Fdocker-wrapper-kotlin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29331755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","java","jvm","kotlin","testing-tools"],"created_at":"2026-02-11T10:10:21.522Z","updated_at":"2026-02-11T10:10:22.349Z","avatar_url":"https://github.com/joshrotenberg.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docker-kotlin\n\nA type-safe Docker CLI wrapper for Kotlin/JVM.\n\n[![CI](https://github.com/joshrotenberg/docker-wrapper-jvm/actions/workflows/ci.yml/badge.svg)](https://github.com/joshrotenberg/docker-wrapper-jvm/actions/workflows/ci.yml)\n[![Documentation](https://github.com/joshrotenberg/docker-wrapper-jvm/actions/workflows/docs.yml/badge.svg)](https://joshrotenberg.github.io/docker-wrapper-jvm/)\n\n## Overview\n\ndocker-kotlin provides a type-safe, idiomatic Kotlin API for interacting with Docker via the CLI. It wraps the `docker` command-line tool rather than using the Docker HTTP API.\n\n## Why CLI over HTTP API?\n\n| Approach | Pros | Cons |\n|----------|------|------|\n| **CLI wrapper** (this library) | Uses existing Docker installation; no additional dependencies; works with Docker Desktop, Podman, Colima; supports all CLI features immediately | Requires Docker CLI installed; shell process overhead |\n| **HTTP API** (docker-java, etc.) | Direct daemon communication; no CLI dependency | Complex socket/TLS configuration; Docker Desktop compatibility issues; feature lag behind CLI |\n\nThis library is ideal when:\n- You already have Docker CLI installed (most development environments)\n- You want to avoid socket/TLS configuration complexity\n- You need features that work across Docker Desktop, Podman, or Colima\n- You prefer simple, predictable behavior matching CLI usage\n\n## Why not Testcontainers?\n\n[Testcontainers](https://testcontainers.org/) is excellent for integration testing with its extensive module ecosystem. docker-kotlin serves different use cases:\n\n| Use Case | Testcontainers | docker-kotlin |\n|----------|---------------|---------------|\n| Pre-built database/service modules | Best choice | Not the focus |\n| Custom container orchestration | Limited | Full control |\n| Docker Compose workflows | Basic support | First-class DSL |\n| Non-test Docker automation | Not designed for this | Primary use case |\n| Learning Docker commands | Abstracts away | Maps 1:1 to CLI |\n\nUse Testcontainers when you need ready-made modules for common services. Use docker-kotlin when you need direct Docker control, custom workflows, or Compose DSL capabilities.\n\n## Installation\n\n```kotlin\n// build.gradle.kts\ndependencies {\n    implementation(\"io.github.joshrotenberg:docker-kotlin-core:0.1.0\")\n    \n    // Optional modules\n    implementation(\"io.github.joshrotenberg:docker-kotlin-compose:0.1.0\")\n    implementation(\"io.github.joshrotenberg:docker-kotlin-testing:0.1.0\")\n    implementation(\"io.github.joshrotenberg:docker-kotlin-templates:0.1.0\")\n}\n```\n\n## Quick Start\n\n### Running Containers\n\n```kotlin\nimport io.github.joshrotenberg.dockerkotlin.core.command.*\n\n// Pull and run a container\nPullCommand(\"nginx:alpine\").executeBlocking()\n\nval containerId = RunCommand(\"nginx:alpine\")\n    .name(\"my-nginx\")\n    .publish(8080, 80)\n    .detach()\n    .executeBlocking()\n\n// Execute commands in the container\nExecCommand(containerId, \"nginx\", \"-v\").executeBlocking()\n\n// View logs\nval logs = LogsCommand(containerId).tail(100).executeBlocking()\n\n// Stop and remove\nStopCommand(containerId).executeBlocking()\nRmCommand(containerId).executeBlocking()\n```\n\n### Compose DSL\n\nDefine Docker Compose configurations in Kotlin:\n\n```kotlin\nimport io.github.joshrotenberg.dockerkotlin.compose.dsl.*\n\nval stack = dockerCompose {\n    service(\"postgres\") {\n        image = \"postgres:16-alpine\"\n        environment {\n            \"POSTGRES_USER\" to \"app\"\n            \"POSTGRES_PASSWORD\" to \"secret\"\n            \"POSTGRES_DB\" to \"mydb\"\n        }\n        ports(\"5432:5432\")\n        healthcheck {\n            testCmd(\"pg_isready\", \"-U\", \"app\")\n            interval = \"10s\"\n            retries = 5\n        }\n    }\n    \n    service(\"redis\") {\n        image = \"redis:7-alpine\"\n        ports(\"6379:6379\")\n    }\n    \n    volume(\"pgdata\")\n}\n\n// Generate YAML\nstack.writeTo(\"docker-compose.yml\")\n\n// Or run directly with automatic cleanup\nstack.use(\"my-project\") {\n    // Stack is running, do your work\n    // Automatically cleaned up when block exits\n}\n```\n\n### Testing Support\n\nJUnit 5 extension for container lifecycle management:\n\n```kotlin\nimport io.github.joshrotenberg.dockerkotlin.testing.*\n\n@ExtendWith(DockerExtension::class)\nclass MyIntegrationTest {\n\n    @Container\n    val redis = ContainerGuard(\n        RunCommand(\"redis:7-alpine\")\n            .publish(6379, 6379)\n    )\n\n    @Test\n    fun `test with redis`() {\n        // Container is started before test, stopped after\n        val client = Redis.connect(\"localhost\", 6379)\n        // ...\n    }\n}\n```\n\n## Modules\n\n| Module | Description |\n|--------|-------------|\n| `docker-kotlin-core` | Core Docker commands (run, exec, build, etc.) |\n| `docker-kotlin-compose` | Docker Compose commands and Kotlin DSL |\n| `docker-kotlin-testing` | JUnit 5 extensions and test utilities |\n| `docker-kotlin-templates` | Pre-configured container templates |\n| `docker-kotlin-redis` | Redis-specific template and utilities |\n\n## Supported Commands\n\n### Container\n`run`, `start`, `stop`, `restart`, `kill`, `pause`, `unpause`, `wait`, `rm`, `exec`, `attach`, `logs`, `top`, `stats`, `port`, `diff`, `cp`, `commit`, `export`, `create`, `update`, `rename`, `inspect`, `ps`\n\n### Image\n`pull`, `push`, `build`, `images`, `rmi`, `tag`, `save`, `load`, `import`, `search`, `history`, `prune`\n\n### Network\n`create`, `ls`, `rm`, `inspect`, `connect`, `disconnect`, `prune`\n\n### Volume\n`create`, `ls`, `rm`, `inspect`, `prune`\n\n### System\n`info`, `version`, `events`, `df`, `prune`\n\n### Compose\n`up`, `down`, `ps` (plus Kotlin DSL for configuration)\n\n### Auth\n`login`, `logout`\n\n## Java Interoperability\n\nAll commands support blocking execution and builder patterns for Java:\n\n```java\nimport io.github.joshrotenberg.dockerkotlin.core.command.*;\n\n// Builder pattern\nString containerId = RunCommand.builder(\"nginx:alpine\")\n    .name(\"my-nginx\")\n    .publish(8080, 80)\n    .detach()\n    .executeBlocking();\n\n// Compose DSL via builders\nComposeSpec compose = ComposeBuilder.create()\n    .service(\"web\", web -\u003e web\n        .image(\"nginx:alpine\")\n        .ports(\"8080:80\"))\n    .build();\n```\n\n## Requirements\n\n- JDK 17+\n- Docker CLI installed and available in PATH\n- Docker daemon running\n\n## Runtime Compatibility\n\nThe library automatically detects and works with Docker-compatible runtimes:\n\n| Runtime | Status | Notes |\n|---------|--------|-------|\n| Docker Engine | Tested | Full support |\n| Docker Desktop | Tested | Full support (macOS, Windows, Linux) |\n| Colima | Supported | Uses `docker` CLI |\n| OrbStack | Supported | Uses `docker` CLI |\n| Rancher Desktop | Supported | Uses `docker` CLI (dockerd mode) |\n| Podman | Supported | Alias `docker=podman` or use native detection |\n\nThe library detects the runtime via `docker context show` and configures socket paths automatically. For Podman, you can either:\n- Use the alias: `alias docker=podman` (recommended by Podman docs)\n- Let the library detect Podman natively and use the `podman` command\n\n## Documentation\n\nFull documentation: [https://joshrotenberg.github.io/docker-wrapper-jvm/](https://joshrotenberg.github.io/docker-wrapper-jvm/)\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshrotenberg%2Fdocker-wrapper-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshrotenberg%2Fdocker-wrapper-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshrotenberg%2Fdocker-wrapper-kotlin/lists"}