Skip to main content

Implement for AWS ECS and Docker Compose what SAM is to Serverless for AWS Lambda

Project description


CodeStyle TDD with pytest BDD with Behave

Code scan with SonarCloud


Be for AWS ECS and docker-compose what AWS SAM is to Lambda


On AWS using AWS CloudFormation Macro

Region Lambda Layer based Macro Docker based Macro

Via pip

pip install ecs_composex


usage: ecs-composex [-h] {up,render,create,config,init,version} ...

positional arguments:
                        Command to execute.
    up                  Generates & Validates the CFN templates,
                        Creates/Updates stack in CFN
    render              Generates & Validates the CFN templates locally. No
                        upload to S3
    create              Generates & Validates the CFN templates locally.
                        Uploads files to S3
    config              Merges docker-compose files to provide with the final
                        compose content version
    init                Initializes your AWS Account with prerequisites
                        settings for ECS
    version             ECS ComposeX Version

optional arguments:
  -h, --help            show this help message and exit

CLI for up and render

usage: ecs_composex up [-h] -n NAME -f DOCKERCOMPOSEXFILE [-d OUTPUTDIRECTORY]
                       [--format {json,yaml,text}] [--region REGIONNAME]
                       [--az ZONES] [-b BUCKETNAME] [--use-spot-fleet]

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Name of your stack
                        Path to the Docker compose file
                        Output directory to write all the templates to.
  --format {json,yaml,text}
                        Defines the format you want to use.
  --region REGIONNAME   Specify the region you want to build fordefault use
                        default region from config or environment vars
  --az ZONES            List AZs you want to deploy to specifically within the
  -b BUCKETNAME, --bucket-name BUCKETNAME
                        Bucket name to upload the templates to
  --use-spot-fleet      Runs spotfleet for EC2. If used in combination of
                        --use-fargate, it will create an additional SpotFleet


Each sub menu has its own manual, alike the aws cli

AWS & Docker Resources support


  • healthcheck
  • environment
  • secrets
  • deploy/replicas: Define how many tasks you want running for your service.
  • deploy/resources: Automatically map your services resources to an AWS Fargate compatible CPU/RAM combination
  • image (that’d be a problem if that did not work!)

Why use ECS ComposeX ?

ECS ComposeX (or ComposeX for friends) first came out in early March, with some very basic features and has grown over the past few months to add more and more features.

Since then, AWS released Copilot and has announced working with Docker to implement similar capabilities to allow developers to have a better experience at developing as they would normally do and deploying to ECS.

However, I found that the feature set still remains somewhat limited, and as a Cloud Engineer working daily with developers, I constantly have to balance features for developers and best practice in using AWS.

And at this point in time, neither of the previous tools are mentioned allow to do what ECS ComposeX do:

  • Retain full docker-compose format specification compatibility without introducing a new format (Copilot has its own Environment file format)
  • Provide support for more AWS services, such as RDS, DynamoDB, SQS etc., which is not something supported in the Docker ecs-plugin or desktop app.

Trying to implement DevOps starting with developers

Whilst this is something that can be used by AWS Cloud Engineers tomorrow to deploy applications on ECS on the behalf of their developers, the purpose of ECS ComposeX is to enable developers with a simplistic and familiar syntax that takes away the need to be an AWS Expert. If tomorrow developers using ComposeX feel comfortable to deploy services by themselves, I would be able to stop hand-holding them all the time and focus on other areas.


CloudFormation is awesome, the documentation is excellent and the format easy. So ECS ComposeX wants to keep the format of resources Properties as close to the orignal as possible as well as making it easier as well, just alike resources like AWS::Serverless::Function which will create all the resources around your Lambda Function as well as the function.

Community focused

Any new Feature Request submitted by someone other than myself will get their request prioritized to try address their use-cases as quickly as possible.

Submit your Feature Request here

Ensure things work

It takes an insane amount of time to test everything as, generating CFN templates is easy, testing that everything works end-to-end is a completely different thing.

I will always do my best to ensure that any new feature is tested end-to-end, but shall anything slip through the cracks, please feel free to report your errors here

Modularity or “Plug & Play”

The majority of people who are going to use ECS ComposeX on a daily basis should be developers who need to have an environment of their own and want to quickly iterate over it. However, it is certainly something that Cloud Engineers in charge of the AWS accounts etc. would want to use to make their own lives easy too.

In many areas, you as the end-user of ComposeX will already have infrastructure in place: VPC, DBs and what not. So as much as possible, you will be able in ComposeX to define Lookup sections which will find your existing resources, and map these to the services.

Fargate First

However the original deployments and work on this project was done using EC2 instances (using SpotFleet), everything is now implemented to work on AWS Fargate First (2020-06-06).


Follow the news and technical articles on using ECS ComposeX on the Blog


This package would not have been possible without the amazing job done by the AWS CloudFormation team! This package would not have been possible without the amazing community around Troposphere! This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ecs-composex, version 0.12.2
Filename, size File type Python version Upload date Hashes
Filename, size ecs_composex-0.12.2-py2.py3-none-any.whl (319.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size ecs_composex-0.12.2.tar.gz (262.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page