chore: evaluate Docker Go SDK for context-aware container runtime support

Open
  • Is something wrong?
#539 9 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

@SafeeImran is already working on this.

Since Sep 26, 2026.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
docker, go
Domain
cli, devtools, tooling

Research direction

The evaluation focuses on the container client in pkg/connectors. Start by reviewing the current github.com/docker/docker/client usage there. Create a proof-of-concept using docker/go-sdk to test the required capabilities, especially context resolution for Docker Desktop. Run existing container-client tests to ensure compatibility. The outcome is a recommendation, not a full migration.

Written by the indexing model from the issue text.

Description

component/connectors help wanted keep-open kind/task

Description

Evaluate the official docker/go-sdk as a replacement for the current low-level github.com/docker/docker/client integration.

The current client reads DOCKER_HOST but does not resolve Docker CLI contexts. Consequently, microcks-cli may try /var/run/docker.sock even when Docker Desktop uses the active desktop-linux context and exposes its socket at $HOME/.docker/run/docker.sock.

The Docker Go SDK provides Docker-context discovery, but it has not reached v1.0.0. We should verify that it supports all capabilities required by microcks-cli before adopting it.

Goals

  • Test whether docker/go-sdk/client correctly resolves the active Docker context.
  • Verify that it supports all current container operations.
  • Determine whether it can preserve Docker and Podman compatibility.
  • Estimate the migration from github.com/docker/docker to the newer Docker/Moby API packages.
  • Produce a go/no-go recommendation.

Required capabilities

Verify support for:

  • Pulling container images and streaming pull progress.
  • Creating containers with port bindings and auto-remove.
  • Starting and stopping containers.
  • Inspecting whether a container exists.
  • Closing the client cleanly.
  • Docker API-version negotiation.
  • Explicit DOCKER_HOST configuration.
  • Active Docker context resolution.
  • DOCKER_CONTEXT overrides.
  • Docker Desktop’s $HOME/.docker/run/docker.sock.
  • Linux’s /var/run/docker.sock.
  • Windows named pipes.
  • Remote contexts and their TLS configuration.
  • Podman through its Docker-compatible socket.

Compatibility scenarios

At minimum, test:

  1. Docker Desktop on macOS with the /var/run/docker.sock compatibility symlink disabled.
  2. Docker Desktop on macOS with the compatibility symlink enabled.
  3. Explicit DOCKER_HOST.
  4. Local Docker Engine on Linux.
  5. Podman machine on macOS or Windows.
  6. Rootless Podman on Linux.
  7. A named Docker context.
  8. An unreachable or invalid context, ensuring the error is actionable.

Dependency assessment

Document:

  • The exact docker/go-sdk version tested.
  • Its API stability and release status.
  • Required changes to existing Docker API type imports.
  • Interaction with testcontainers-go and microcks.io/testcontainers-go.
  • Any dependency-version conflicts.
  • Binary-size impact, if material.
  • Whether adopting it requires a complete Moby API migration or can be isolated to pkg/connectors.

Because the SDK is pre-v1, any adoption should pin an exact released version rather than a branch or pseudo-version.

Acceptance criteria

  • A small proof of concept exercises the operations currently used by containerClient.

  • The proof of concept successfully connects through the desktop-linux context without setting DOCKER_HOST.

  • DOCKER_HOST and DOCKER_CONTEXT precedence is verified.

  • Docker and Podman behavior is documented.

  • Existing container-client tests continue to pass or required changes are identified.

  • The issue concludes with one of:

    • Adopt: create a focused migration issue with the required changes.
    • Defer: document the missing capabilities or stability concerns and retain the current client.
    • Reject: document the incompatibilities and the preferred alternative.

Non-goals

  • Rewriting the complete container abstraction during the evaluation.
  • Migrating production code before compatibility is demonstrated.
  • Replacing the separate Testcontainers integration unless the evaluation identifies a concrete requirement.
Dominant language
Go
Stars
59
Forks
74
Avg merge
4d 5h
Merged PRs (30d)
15

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microcks/microcks-cli

All issues in microcks/microcks-cli

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.