diff --git a/README.md b/README.md index 58a76a77..b8a371f9 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,8 @@ See the [Agent Mode](https://dozzle.dev/guide/agent) documentation for more deta Dozzle uses automatic API negotiation, which works with most Docker configurations. Dozzle also works with [Colima](https://github.com/abiosoft/colima) and [Podman](https://podman.io/). +Dozzle requires Docker Engine 19.03 or newer (API version 1.40+). Older daemons are not supported by the underlying Docker SDK. + ### Installation on Podman By default, Podman doesn't have a background process, but you can enable the remote socket for Dozzle to work. diff --git a/docs/guide/faq.md b/docs/guide/faq.md index 49c9561e..de9f88db 100644 --- a/docs/guide/faq.md +++ b/docs/guide/faq.md @@ -4,6 +4,12 @@ title: FAQ # Frequently Asked Questions +## Dozzle fails to start with `client version 1.x is too new`. What does this mean? + +Dozzle requires Docker Engine 19.03 or newer (API version 1.40+). Older daemons — for example Docker 18.06 (API 1.38) — are not supported by the underlying Docker SDK and will fail at startup with an error like `failed to create docker client: ... client version 1.54 is too new. Maximum supported API version is 1.38`. + +Upgrade Docker Engine to a supported version. As a temporary workaround, pin Dozzle to `v10.5.2` or earlier, which used a Docker SDK that still negotiated down to older API versions. + ## How do I upgrade Dozzle? Dozzle follows standard Docker image practices. To upgrade, pull the new image and recreate the container: diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 3b96f7a8..cd3c3c2e 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -6,6 +6,9 @@ title: Getting Started Dozzle supports multiple ways to run the application. You can run it using Docker CLI, Docker Compose, Swarm, or Kubernetes. The following sections will guide you through the process of setting up Dozzle. +> [!IMPORTANT] +> Dozzle requires Docker Engine **19.03 or newer** (API version 1.40+). Older daemons are not supported by the underlying Docker SDK. + > [!TIP] > If Docker Hub is blocked in your network, you can use the [GitHub Container Registry](https://ghcr.io/amir20/dozzle:latest) to pull the image. Use `ghcr.io/amir20/dozzle:latest` instead of `amir20/dozzle:latest`. diff --git a/internal/docker/client.go b/internal/docker/client.go index 3c5bc326..24a36023 100644 --- a/internal/docker/client.go +++ b/internal/docker/client.go @@ -83,6 +83,10 @@ func NewLocalClient(hostname string) (*DockerClient, error) { return nil, err } + if _, err := cli.Ping(context.Background(), client.PingOptions{NegotiateAPIVersion: true}); err != nil { + return nil, fmt.Errorf("docker daemon unreachable or unsupported (minimum API version %s required): %w", client.MinAPIVersion, err) + } + infoResult, err := cli.Info(context.Background(), client.InfoOptions{}) if err != nil { return nil, err @@ -126,6 +130,10 @@ func NewRemoteClient(host container.Host) (*DockerClient, error) { return nil, err } + if _, err := cli.Ping(context.Background(), client.PingOptions{NegotiateAPIVersion: true}); err != nil { + return nil, fmt.Errorf("docker daemon unreachable or unsupported (minimum API version %s required): %w", client.MinAPIVersion, err) + } + host.Type = "remote" return NewClient(cli, host), nil