From 59eaa8e93b1a0cee99ca2692d863799d79d2ea52 Mon Sep 17 00:00:00 2001 From: Chris Crone Date: Fri, 21 Aug 2020 17:14:03 +0200 Subject: [PATCH] readme: Prep for open source Signed-off-by: Chris Crone --- README.md | 171 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 126 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 09c31828..bef10995 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,166 @@ -# Docker API +# Docker Compose CLI [![Actions Status](https://github.com/docker/compose-cli/workflows/Continuous%20integration/badge.svg)](https://github.com/docker/compose-cli/actions) -## Dev Setup +This CLI tool makes it easy to run containers in the cloud using either Amazon +Elastic Container Service +([ECS](https://aws.amazon.com/ecs)) +or Microsoft Azure Container Instances +([ACI](https://azure.microsoft.com/services/container-instances)) +using the Docker commands you already know. -The recommended way is to use the main `Makefile` that runs everything inside a container. +To get started, all you need is: +* An [AWS](https://aws.amazon.com) or [Azure](https://azure.microsoft.com) + account +* Windows: Edge release of + [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-windows) +* macOS: The Edge release of + [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac) +* Linux: + TODO -If you don't have or want to use Docker for building you need to make sure you have all the needed tools installed locally: +:warning: *This CLI is currently in beta please create* +*[issues](https://github.com/docker/compose-cli/issues) to leave feedback* -* go 1.15 -* [protoc](https://github.com/protocolbuffers/protobuf) -* `go get github.com/golang/protobuf/protoc-gen-go@v1.4.1` -* `go get golang.org/x/tools/cmd/goimports` -* `go get github.com/golangci/golangci-lint/cmd/golangci-lint@v1.30.0` +## Examples -And then you can call the same make targets but you need to pass it the `builder.Makefile` (`make -f builder.Makefile`). +* ECS: [Deploying Wordpress to the cloud](https://www.docker.com/blog/deploying-wordpress-to-the-cloud/) +* ACI: [Deploying a Minecraft server to the cloud](https://www.docker.com/blog/deploying-a-minecraft-docker-server-to-the-cloud/) -The new CLI delegates to the classic docker for default contexts ; delegation is done to `com.docker.cli`. -* `make moby-cli-link` will create a `com.docker.cli` link in `/usr/local/bin` if you don't already have it from Docker Desktop +## Developing -## Building the project +### Prerequisites -```bash -$ make +* Windows: + * [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-windows) + * make +* macOS: + * [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac) + * make +* Linux: + * [Docker 19.03 or later](https://docs.docker.com/engine/install/) + * make + +### Building the CLI + +Once you have the prerequisites installed, you can build the CLI using: + +```console +make ``` -This will make the cli with all backends enabled. `make cross` on the other hand will cross-compile the cli without the -example and local backend. We use `make cross` to build for our release, hence the exclusion of those backends. You can -still cross-compile with all backends enabled: `BUILD_TAGS=example,local make cross`. +This will output a CLI for your host machine in `./bin`. -If you make changes to the `.proto` files, make sure to `make protos` to generate go code. +You will then need to make sure that you have the existing Docker CLI in your +`PATH` with the name `com.docker.cli`. A make target is provided to help with +this: -## Tests +```console +make moby-cli-link +``` + +This will create a symbolic link from the existing Docker CLI to +`/usr/local/bin` with the name `com.docker.cli`. + +You can statically cross compile the CLI for Windows, macOS, and Linux using the +`cross` target. + +### Building with specific backends + +You can specify which backends are build using the `BUILD_TAGS` variable. +The available backends are: +* `aci`: For ACI support (always built) +* `ecs`: For ECS support (on by default) +* `example`: Testing backend (off by default) +* `local`: Beginnings of a [moby](https://github.com/moby/moby) backend + (off by default) + +If you want the ACI, ECS and example backends, then you can build as follows: + +```console +make BUILD_TAGS=example cli +``` + +### Updating the API code + +The API provided by the CLI is defined using protobuf. If you make changes to +the `.proto` files in [`protos/`](./protos), you will need to regenerate the API +code: + +```console +make protos +``` ### Unit tests -``` +To run all of the unit tests, run: + +```console make test ``` If you need to update a golden file simply do `go test ./... -test.update-golden`. -### e2e tests +### End to end tests -``` +#### Local tests + +To run the local end to end tests, run: + +```console make e2e-local ``` -This requires a local Docker Engine running -Local ACI E2E tests: +Note that this requires the CLI to be built and a local Docker Engine to be +running. + +#### ACI tests + +To run the end to end ACI tests, you will first need to have an Azure account +and have created a service principal. You can create a service principle using +the Azure CLI after you have done a `docker login azure`: + +```console +$ docker login azure +$ az ad sp create-for-rbac --name 'MyTestServicePrincipal' --sdk-auth ``` + +You can then run the ACI tests using the `e2e-aci` target with the various +`AZURE_` environment variables set: + +```console AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make e2e-aci ``` -This requires azure service principal credentials to login to azure. -To get the values to be set in local environment variables, you can create a new service principal once you're logged in azure (with `docker login azure`) -``` -az ad sp create-for-rbac --name 'MyTestServicePrincipal' --sdk-auth -``` -Running the ACI e2e tests will override your local login, the service principal credentials use a token that cannot be refreshed automatically. -You might need to run again `docker login azure` to properly use the command line after running ACI e2e tests. +Running the ACI tests will override your local login and the service principal +credentials use a token that cannot be refreshed automatically. -You can also run a single ACI test from the test suite: -``` +*Note:* You will need to rerun `docker login azure` if you would like to use the +CLI after running the ACI tests. + +You can also run a single ACI test by specifying the test name with the +`E2E_TEST` variable: +```console AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make E2E_TEST=TestContainerRun e2e-aci ``` -Local ECS E2E tests: -``` +#### ECS tests + +To run the end to end ECS tests, you will need to have an AWS account and have +credentials for it in the `~/.aws/credentials` file. + +You can then use the `e2e-ecs` target: + +```console TEST_AWS_PROFILE=myProfile TEST_AWS_REGION=eu-west-3 make e2e-ecs ``` -This requires a valid AWS profile defined in ~/.aws/credentials. - -## Release +## Releases To create a new release: -* check that the CI is green on the main branch's commit you want to release -* simply create a new tag of the form vx.y.z, following existing tags, and push the tag +* Check that the CI is green on the main branch for commit you want to release +* Create a new tag of the form vx.y.z, following existing tags, and push the tag -Pushing the tag will automatically create a new release and make binaries (mac, win, linux) available for download. - -Note: Linux binaries are not automatically copied to /docker/aci-integration-beta, if you want to make the linux binary publicly available, you'll need to manually create a release in aci-integration-beta and upload the binary. -For Desktop integration, you need to make a PR in /docker/pinata and update the cli release number [here](https://github.com/docker/pinata/blob/master/build.json#L25) +Pushing the tag will automatically create a new release and make binaries for +Windows, macOS, and Linux available for download on the +[releases page](https://github.com/docker/compose-cli/releases).