compose/README.md

Docker Compose CLI

This CLI tool makes it easy to run containers in the cloud using either Amazon Elastic Container Service (ECS) or Microsoft Azure Container Instances (ACI) using the Docker commands you already know.

To get started, all you need is:

• An AWS or Azure account
• Windows: Edge release of Docker Desktop
• macOS: The Edge release of Docker Desktop
• Linux: TODO

⚠️ This CLI is currently in beta please create issues to leave feedback

Examples

• ECS: Deploying Wordpress to the cloud
• ACI: Deploying a Minecraft server to the cloud

Developing

Prerequisites

• Windows:
  • Docker Desktop
  • make
• macOS:
  • Docker Desktop
  • make
• Linux:
  • Docker 19.03 or later
  • make

Building the CLI

Once you have the prerequisites installed, you can build the CLI using:

make

This will output a CLI for your host machine in ./bin.

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:

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 backend (off by default)

If you want the ACI, ECS and example backends, then you can build as follows:

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/, you will need to regenerate the API code:

make protos

Unit tests

To run all of the unit tests, run:

make test

If you need to update a golden file simply do go test ./... -test.update-golden.

End to end tests

Local tests

To run the local end to end tests, run:

make e2e-local

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:

$ 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:

AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make e2e-aci

Running the ACI tests will override your local login and the service principal credentials use a token that cannot be refreshed automatically.

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:

AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make E2E_TEST=TestContainerRun e2e-aci

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:

TEST_AWS_PROFILE=myProfile TEST_AWS_REGION=eu-west-3 make e2e-ecs

Releases

To create a new release:

• 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 for Windows, macOS, and Linux available for download on the releases page.