# Docker with Amazon ECS

Looking to deploy your Docker containers with Amazon Elastic Container Service (ECS)? Here's a brief guide to get you going. This article uses the AWS and ECS CLI tooling in the process.

---

Amazon ECS is a highly scalable, high-performance [container](https://aws.amazon.com/containers/) orchestration service that supports [Docker](https://aws.amazon.com/docker/) containers and allows you to easily run and scale containerized applications on AWS.

## The AWS CLI

This section provides some brief instructions on how to install and configure the AWS CLI. For the most recent information on how to install the AWS Command Line Interface see the [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) guide. The steps below provide a quick short-hand of this guide.

<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><strong>Requirements</strong>: Python 2 (version 2.6.5+) or Python 3 (version 3.3+)</div>
</div>

### Installing `awscli` on Linux

Run the following command to install the `awscli` package using `pip`:

```bash
pip install awscli --upgrade --user
```

After installing `awscli` you may have to add the [AWS CLI Executable to your Command-Line Path](https://docs.aws.amazon.com/cli/latest/userguide/awscli-install-linux.html#awscli-install-linux-path).

### Installing `awscli` on macOS

We use [Homebrew](https://brew.sh/) to install the required package(s).

```bash
brew install awscli
```

### Configuring `awscli`

Verify that the AWS CLI is installed correctly:

```bash
aws --version
```

Next, we'll need to configure the AWS CLI. For the most recent information on how to configure the AWS Command Line Interface see the [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) guide. The steps below provide a quick short-hand of this guide.

Run the following command to configure the AWS CLI in your environment:

```bash
aws configure
```

You'll be prompted to provide the following information:

* AWS Access Key ID
    
* AWS Secret Access Key
    
* Default region name (e.g. `us-east-1`)
    
* Default output format (e.g. `json`)
    

You can retrieve the AWS Access Key ID and AWS Secret Access Key in your [AWS Console](https://https//console.aws.amazon.com) | My Account | Security Credentials. For the Default region name you may choose the region ID (e.g. `us-east-1`) suggested by the `region` query parameter in the URL of the AWS console session you're logged in with, e.g.:

```bash
https://console.aws.amazon.com/console/home?region=us-east-1
```

## The Amazon ECS CLI

This section provides some brief instructions on how to install and configure the Amazon ECS CLI. For the most recent information on how to install the Amazon ECS CLI see the [Installing the Amazon ECS CLI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_CLI_installation.html) guide. The steps below provide a quick short-hand of this guide.

Download the latest version of the ECS CLI, based on your platform of choice.

Linux:

```bash
sudo curl -o /usr/local/bin/ecs-cli https://s3.amazonaws.com/amazon-ecs-cli/ecs-cli-linux-amd64-latestmacOS
```

macOS:

```bash
sudo curl -o /usr/local/bin/ecs-cli https://s3.amazonaws.com/amazon-ecs-cli/ecs-cli-darwin-amd64-latest
```

Grant execute permissions to the `ecs-sli` binary:

```bash
sudo chmod +x /usr/local/bin/ecs-cli
```

Verify that the ECS CLI is working properly:

```bash
ecs-cli --version
```

Next, we'll need to configure the Amazon ECS CLI. For the most recent information on how to configure the Amazon ECS CLI see the [Configuring the Amazon ECS CLI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_CLI_Configuration.html) guide. The steps below provide a quick short-hand of this guide.

The Amazon ECS CLI requires the following basic configuration information:

* ECS profile
    
* AWS credentials
    
* AWS Region in which to create your cluster
    
* default ECS cluster name
    

This information is stored in the following configuration file (based on your OS platform):

* Linux, macOS: `~/.ecs/config`
    
* Windows:  `%userprofile%\AppData\local\ecs\config`
    

To set up an ECS CLI profile run the following command, substituting `$ECS_PROFILE_NAME`  with your desired profile name, `$AWS_ACCESS_KEY_ID` and `$AWS_SECRET_ACCESS_KEY` with your AWS security credentials.

```bash
ecs-cli configure profile --profile-name $ECS_PROFILE_NAME --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY
```

Next, create a cluster configuration, which defines the AWS region to use, resource creation prefixes, and the cluster name to use with the ECS CLI. Replace the related variables with your own preferences (see the example below).

```bash
ecs-cli configure --cluster $ECS_CLUSTER_NAME --default-launch-type $ECS_TYPE --region $ECS_REGION --config-name $ECS_CONFIG_NAME
```

In the command above you may choose to leave out the `--config_name` option and have the default cluster configuration in place. Below is an example of the various configuration attributes involved:

```bash
ECS_CLUSTER_NAME="devshell-ecs"
ECS_TYPE="EC2" # or FARGATE
ECS_REGION="us-east-1"
ECS_CONFIG_NAME="devshell-ecs"
```

## Deploying your app

To illustrate a simple Amazon ECS deployment, let's assume we have a Docker composition manifest named `devshell.ecs.yml` describing our app. Here are the steps to deploy, set up, and teardown our app:

Start the ECS cluster (replace your `--instance-type` and `--keypair` attribute values with your own):

```bash
ecs-cli up --capability-iam --instance-type t2.large --keypair keypair_name
```

Deploy the app with the related Docker composition manifest (replace the `--file` and `--project-name` attribute values with your own):

```bash
ecs-cli compose --file devshell.ecs.yml --project-name devshell service up
```

View your ECS app service(s) (this would list the related Docker composition stack):

```bash
ecs-cli ps
```

Stop (teardown) the running app (replace the `--file` and `--project-name` attribute values with your own):

```bash
ecs-cli compose --file devshell.ecs.yml --project-name devshell service down
```

Stop the ECS cluster:

```bash
ecs-cli down
```

You may see the related (deployment) ECS resources in your AWS Console:

* [ECS clusters](https://console.aws.amazon.com/ecs/home?region=us-east-1#/clusters)
    
* [ECS task definitions](https://console.aws.amazon.com/ecs/home?region=us-east-1#/taskDefinitions)