conda-forge / conda-forge/docker-cli-feedstock

docker-buildx installed via conda is not discoverable by the Docker CLI

Open
#42 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Shell
Stars
0
Forks
4
Avg merge
11m
Merged PRs (30d)
1

Description

### Solution to issue cannot be found in the documentation.

- [x] I checked the documentation.

### Issue

When `docker-buildx` is installed via conda-forge, the binary is placed on `$PATH` but the Docker CLI never finds it, resulting in:

```
ERROR: BuildKit is enabled but the buildx component is missing or broken.
Install the buildx component to build images with BuildKit:
https://docs.docker.com/go/buildx/
```

### Root Cause

The Docker CLI **does not search `$PATH`** for CLI plugins. Instead, it searches a fixed set of directories in order:

1. `$DOCKER_CONFIG/cli-plugins/` (defaults to `~/.docker/cli-plugins/`)
2. Directories listed in `cliPluginsExtraDirs` in the config file
3. Platform-specific system directories:
- `/usr/local/lib/docker/cli-plugins`
- `/usr/local/libexec/docker/cli-plugins`
- `/usr/lib/docker/cli-plugins`
- `/usr/libexec/docker/cli-plugins`

The relevant code is in [`cli-plugins/manager/manager.go`](https://github.com/docker/cli/blob/master/cli-plugins/manager/manager.go).

Since conda installs binaries into `$CONDA_PREFIX/bin/`, none of the searched directories contain the binary, and plugin discovery fails.

### Suggested Fix

There are two approaches, which could also be combined:

#### Option A: Patch docker-cli to support an environment variable for plugin dirs

The `docker-cli-feedstock` could patch [`cli-plugins/manager/manager.go:getPluginDirs`](https://github.com/docker/cli/blob/master/cli-plugins/manager/manager.go) to check an environment variable (e.g., `DOCKER_CLI_PLUGIN_PATH`) in addition to the existing search locations. The `docker-buildx-feedstock` would then install the binary into `$CONDA_PREFIX/lib/docker/cli-plugins/` and set this variable via an activation script.

This avoids any interference with the user's `~/.docker/` config and is the cleanest solution. The patch could also be proposed upstream to benefit other package managers (Nix, Homebrew, etc.).

#### Option B: Override DOCKER_CONFIG

This requires coordination between `docker-cli-feedstock` and `docker-buildx-feedstock`:

**docker-cli-feedstock** should:
- Set `DOCKER_CONFIG` to `$CONDA_PREFIX/etc/docker/` via an activation script
- Ship a `config.json` at that location with `cliPluginsExtraDirs` pointing to a plugin directory within the prefix, e.g.:

```json
{
"cliPluginsExtraDirs": ["$CONDA_PREFIX/lib/docker/cli-plugins"]
}
```

**Note:** Overriding `DOCKER_CONFIG` means the Docker CLI will no longer read `~/.docker/config.json`. Any user-level configuration (auth credentials, proxies, custom settings, etc.) would need to live in the conda-managed config directory instead. The activation script should document this, or consider copying/merging the user's existing config into the conda-managed location on first activation.

**docker-buildx-feedstock** should:
- Install (or symlink) the `docker-buildx` binary into `$CONDA_PREFIX/lib/docker/cli-plugins/`

### Workaround

Users can manually symlink the binary into a recognized plugin directory:

```bash
mkdir -p ~/.docker/cli-plugins
ln -s "$(which docker-buildx)" ~/.docker/cli-plugins/docker-buildx
```

### Environment

- OS: macOS / Linux
- Installation method: `conda install docker-buildx`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.