tyler.durden/compose
1
0
Fork 0
mirror of https://github.com/docker/compose.git synced 2025-07-05 12:54:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

readme: Prep for open source

Browse Source 
Signed-off-by: Chris Crone <christopher.crone@docker.com>
This commit is contained in:
Chris Crone 2020-08-21 17:14:03 +02:00 committed by Guillaume Tardif
parent e4d4da3968
commit 59eaa8e93b
1 changed files with 126 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
README.md
View File

@ -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) [![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 <!-- Move instructions from https://github.com/docker/aci-integration-beta to this repo-->
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 ## Examples
* [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`
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`. ## Developing
* `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
## Building the project ### Prerequisites
```bash * Windows:
$ make * [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 This will output a CLI for your host machine in `./bin`.
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`.
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 ### Unit tests
``` To run all of the unit tests, run:
```console
make test make test
``` ```
If you need to update a golden file simply do `go test ./... -test.update-golden`. 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 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 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. Running the ACI tests will override your local login and the service principal
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`) credentials use a token that cannot be refreshed automatically.
```
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.
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 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 TEST_AWS_PROFILE=myProfile TEST_AWS_REGION=eu-west-3 make e2e-ecs
``` ```
This requires a valid AWS profile defined in ~/.aws/credentials. ## Releases
## Release
To create a new release: To create a new release:
* check that the CI is green on the main branch's commit you want to release * Check that the CI is green on the main branch for commit you want to release
* simply create a new tag of the form vx.y.z, following existing tags, and push the tag * 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. Pushing the tag will automatically create a new release and make binaries for
Windows, macOS, and Linux available for download on the
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. [releases page](https://github.com/docker/compose-cli/releases).
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)