Docker Compose CLI Cloud Integration Guide

⚠️ Retirement Notice: Docker Compose's integration for ECS and ACI retired in November 2023. This repository only receives critical security fixes. ECS users should migrate to compose-ecs.

Prerequisites

• Docker Desktop (macOS, Windows, or WSL2) OR Linux with Docker Engine installed
• Go 1.16+ (for building from source)
• AWS Account (for ECS deployments) or Azure Account (for ACI deployments)
• AWS CLI v2 configured with appropriate IAM permissions (ECS, CloudFormation, EC2, EFS, ELB, IAM, S3, Secrets Manager)
• Azure CLI (for ACI deployments)
• Git

Installation

Option 1: Docker Desktop (macOS/Windows)

Download and install Docker Desktop. The Compose CLI cloud integrations are included by default for macOS, Windows, and WSL2 environments.

Option 2: Linux Install Script

curl -L https://raw.githubusercontent.com/docker/compose-cli/main/scripts/install/install_linux.sh | sh

Option 3: Build from Source

git clone https://github.com/docker/compose-cli.git
cd compose-cli
go build -o docker-compose-cli ./cli

Configuration

AWS ECS Setup

1. Configure AWS credentials:

   aws configure
   

   Required IAM permissions include: AmazonECS_FullAccess, CloudFormationFullAccess, AmazonEC2FullAccess, AmazonS3FullAccess, IAMFullAccess, ElasticLoadBalancingFullAccess, AmazonEFSFullAccess, SecretsManagerReadWrite.

2. Create ECS context:

   docker context create ecs myecscontext
   

   Select your AWS profile and region when prompted.

3. Activate context:

   docker context use myecscontext
   

Azure ACI Setup

1. Login to Azure:

   docker login azure
   

2. Create ACI context:

   docker context create aci myacicontext \
     --subscription-id <subscription-id> \
     --resource-group <resource-group> \
     --location <region>
   

3. Activate context:

   docker context use myacicontext
   

Build & Run

Development Build

# Download dependencies
go mod download

# Build binary
make build

# Or manually:
go build -o bin/docker-compose-cli ./cli

Running Tests

# Unit tests
make test

# End-to-end tests (requires cloud credentials)
make e2e-local    # Local container tests
make e2e-ecs      # AWS ECS tests (requires AWS setup)
make e2e-aci      # Azure ACI tests (requires Azure setup)

Local Development Server

# Run the CLI locally
./bin/docker-compose-cli --help

Deployment

Deploy to AWS ECS

The CLI converts Docker Compose files to CloudFormation templates.

1. Deploy application:

   docker context use myecscontext
   docker compose up
   

   This creates:

   • CloudFormation stack
   • ECS Cluster and Task Definitions
   • Application Load Balancers (for exposed ports)
   • EFS volumes (if specified in compose file)
   • CloudWatch Log Groups
   • Service Discovery namespaces (for service communication)

2. View generated CloudFormation (without deploying):

   docker compose convert > template.yaml
   

3. Check deployment status:

   docker compose ps
   docker compose logs <service-name>
   

4. Teardown:

   docker compose down
   

   This deletes the CloudFormation stack and all associated AWS resources.

Deploy to Azure ACI

1. Deploy containers:

   docker context use myacicontext
   docker compose up
   

2. Manage deployment:

   docker ps                    # List running containers
   docker logs <container-id> # View logs
   docker exec <container-id> # Execute commands in container
   

3. Teardown:

   docker compose down
   

Kubernetes (Experimental)

docker context create kubernetes myk8scontext
docker context use myk8scontext
docker compose up

Troubleshooting

AWS ECS Issues

CloudFormation Stack Failures

• Check the CloudFormation console for specific error details
• Verify VPC and subnets exist in the target region
• Ensure IAM user has permissions for all required services (ECS, CloudFormation, EC2, EFS, ELB, IAM)

Image Pull Errors

• Ensure images are accessible (ECR or public registries)
• For private registries, add x-aws-pull_credentials to your compose file

Service Communication Failures

• Verify CloudMap namespace creation
• Check security groups allow traffic between services on required ports

Context Not Found

# List available contexts
docker context ls

# Create if missing
docker context create ecs <name>

Azure ACI Issues

Authentication Failures

• Re-authenticate: docker login azure
• Verify subscription ID and resource group exist in Azure Portal

Container Start Failures

• Check resource limits (CPU/memory) against ACI quotas
• Review logs: docker logs <container-id>

Build Issues

Go Module Errors

go clean -modcache
go mod download

Missing Protobuf Files If modifying .proto files, regenerate Go code:

protoc --go_out=. --go-grpc_out=. cli/server/protos/**/*.proto

Migration Notice

For ongoing ECS development, migrate to compose-ecs which provides updated ECS integration support.