diff --git a/README.md b/README.md index 8a87ffd33ea..d721ccf7aa4 100644 --- a/README.md +++ b/README.md @@ -41,25 +41,12 @@ _buildx is Tech Preview_ # Installing -Using `buildx` as a docker CLI plugin requires using Docker 19.03.0 beta. A limited set of functionality works with older versions of Docker when invoking the binary directly. +Using `buildx` as a docker CLI plugin requires using Docker 19.03. A limited set of functionality works with older versions of Docker when invoking the binary directly. -### Docker Desktop (Edge) +### Docker CE -`buildx` is included with Docker Desktop Edge builds since 19.03.0-beta3. - -For more information see https://docs.docker.com/docker-for-mac/edge-release-notes/ - -### Docker CE nightly builds - -`buildx` comes bundled with the Docker CE nightly builds. -- Mac: https://download.docker.com/mac/static/nightly/ -- Linux: -``` -$ # uncomment next line to uninstall previous Docker CE installation if present -$ # apt purge docker-ce docker-ce-cli -$ curl -fsSL https://get.docker.com/ -o docker-install.sh -$ CHANNEL=nightly sh docker-install.sh -``` +`buildx` comes bundled with Docker CE starting with 19.03, but requires experimental mode to be enabled on the Docker CLI. +To enable it, `"experimental": "enabled"` can be added to the CLI configuration file `~/.docker/config.json`. An alternative is to set the `DOCKER_CLI_EXPERIMENTAL=enabled` environment variable. ### Binary release @@ -344,21 +331,16 @@ Options: | Flag | Description | | --- | --- | -| --append | Append a node to builder instead of changing it -| --driver string | Driver to use (eg. docker-container) -| --leave | Remove a node from builder instead of changing it -| --name string | Builder instance name -| --node string | Create/modify node with given name -| --platform stringArray | Fixed platforms for current node -| --use | Set the current builder instance - -#### `--driver DRIVER` - -Sets the builder driver to be used. There are two available drivers, each have their own specificities. - -- `docker` - Uses the builder that is built into the docker daemon. With this driver, the [`--load`](#--load) flag is implied by default on `buildx build`. However, building multi-platform images or exporting cache is not currently supported. - -- `docker-container` - Uses a buildkit container that will be spawned via docker. With this driver, both building multi-platform images and exporting cache are supported. However, images built will not automatically appear in `docker images` (see [`build --load`](#--load)). +| --append | Append a node to builder instead of changing it +| --buildkitd-flags string | Flags for buildkitd daemon +| --config string | BuildKit config file +| --driver string | Driver to use (eg. docker-container) +| --driver-opt stringArray | Options for the driver +| --leave | Remove a node from builder instead of changing it +| --name string | Builder instance name +| --node string | Create/modify node with given name +| --platform stringArray | Fixed platforms for current node +| --use | Set the current builder instance #### `--append` @@ -372,6 +354,41 @@ $ docker buildx create --name eager_beaver --append mycontext2 eager_beaver ``` +#### `--buildkitd-flags FLAGS` + +Adds flags when starting the buildkitd daemon. They take precedence over the configuration file specified by `--config`. See `buildkitd --help` for the available flags. + +Example: +``` +--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666' +``` + +#### `--config FILE` + +Specifies the configuration file for the buildkitd daemon to use. The configuration can be overridden by `--buildkitd-flags`. See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md). + +#### `--driver DRIVER` + +Sets the builder driver to be used. There are two available drivers, each have their own specificities. + +- `docker` - Uses the builder that is built into the docker daemon. With this driver, the [`--load`](#--load) flag is implied by default on `buildx build`. However, building multi-platform images or exporting cache is not currently supported. + +- `docker-container` - Uses a buildkit container that will be spawned via docker. With this driver, both building multi-platform images and exporting cache are supported. However, images built will not automatically appear in `docker images` (see [`build --load`](#--load)). + + +#### `--driver-opt OPTIONS` + +Passes additional driver-specific options. Details for each driver: + +- `docker` - No driver options +- `docker-container` + - `image` - Sets the container image to be used for running buildkit. + - `network` - Sets the network mode for running the buildkit container. + - Example: + ``` + --driver docker-container --driver-opt image=moby/buildkit:master,network=host + ``` + #### `--leave` Changes the action of the command to removes a node from a builder. The builder needs to be specified with `--name` and node that is removed is set with `--node`.