<commit_before><!--

title: Continuous Deployment with AWS CodeDeploy
last_updated: September 29, 2014

-->

## Getting Started with CodeDeploy on CircleCI

AWS CodeDeploy is a deployment system that enables developers to automate the
deployment of applications to EC2 instances, and to update the applications as
required.

### AWS infrastructure
The first step to continuous deployment with CodeDeploy is setting up your EC2
instances, tagging them so you can define deployment groups, installing the
CodeDeploy agent on your hosts and setting up trust-roles so that CodeDeploy
can communicate with the CodeDeploy agents.
AWS provide a good [getting started with CodeDeploy guide][] for this part of
the process.

[getting started with CodeDeploy guide]: http://docs.aws.amazon.com/en_us/console/codedeploy/applications-user-guide


### CodeDeploy application
A CodeDeploy application is a collection of settings about where your
application can be deployed, how many instances can be deployed to at once,
what should be considered a failed deploy, and information on the trust-role to
use to allow CodeDeploy to interact with your EC2 instances.

**Note**: A CodeDeploy application does not specify what is to be deployed or what to
do during the deployment.
*What* to deploy is an archive of code/resources stored in S3 called an
`application revision`.
*How* to deploy is specified by the `AppSpec` file located inside the
application revision.

The AppSpec file lives in your repo and tells CodeDeploy which files from
your application to deploy, where to deploy them, and also allows you specify
lifecyle scripts to be run at different stages during the deployment. You can
use these lifecycle scripts to stop your service before a new version is
deployed, run database migrations, install dependencies etc.

An application revision is a zipfile or tarball containing the code/resources
to be deployed. It's usually created by packaging up your entire repo but can
be a sub-directory of the repo if desired. The `AppSpec` file must be stored
in the application revision as `<application-root>/appspec.yml`.

Generally speaking you'll have one application in your repo and so your
application revision can be created by packaging up your whole repo (excluding
`.git`). In this case `appspec.yml` should be placed in your repo root directory.

Application revisions are stored in [S3][] and are identified by the
combination of a bucket name, key, eTag, and for versioned buckets, the
object's version.

The most straightforward way to configure a new application is to log on to the
[CodeDeploy console][] which can guide you through the process of [creating a new
application][].

[comment]: <> "[AppSpec]: TODO link to doc on appspecs, linkify occurrences of 'AppSpec'"
[comment]: <> "[application revision]: TODO link to doc on application revisions, linkify occurrences of 'application revisions'"
[S3]: http://aws.amazon.com/s3/
[CodeDeploy console]: https://console.aws.amazon.com/codedeploy/home
[creating a new application]: https://console.aws.amazon.com/codedeploy/home#/applications/new



## Configuring CircleCI

CircleCI will automatically create new application revisions, upload them to
S3, and both trigger and watch deployments when you get a green build.

### Step 1: Create an IAM user for CircleCI to use
You should create an [IAM user][] to use solely for builds on
CircleCI, that way you have control over exactly which of your resources can be
accessed by code running as part of your build.

Take note of the Access Key ID and Secret Access Key allocated to your new IAM
user, you'll need these later.

For deploying with CodeDeploy your IAM user needs to be able to access S3 and
CodeDeploy at a minimum.

#### S3 IAM policy
CircleCI needs to be able to upload application revisions to your S3 bucket.
Permissions can be scoped down to the common-prefix you use for application
revision keys if you don't want to give access to the entire bucket.

The following policy snippet allows us to upload to `my-bucket` as long as the
key starts with `my-app`.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject"
          ],
          "Resource": [
            "arn:aws:s3:::my-bucket/my-app*",<commit_msg>[ci skip] Documentation fix. JSON is the worst.<commit_after><!--

title: Continuous Deployment with AWS CodeDeploy
last_updated: September 29, 2014

-->

## Getting Started with CodeDeploy on CircleCI

AWS CodeDeploy is a deployment system that enables developers to automate the
deployment of applications to EC2 instances, and to update the applications as
required.

### AWS infrastructure
The first step to continuous deployment with CodeDeploy is setting up your EC2
instances, tagging them so you can define deployment groups, installing the
CodeDeploy agent on your hosts and setting up trust-roles so that CodeDeploy
can communicate with the CodeDeploy agents.
AWS provide a good [getting started with CodeDeploy guide][] for this part of
the process.

[getting started with CodeDeploy guide]: http://docs.aws.amazon.com/en_us/console/codedeploy/applications-user-guide


### CodeDeploy application
A CodeDeploy application is a collection of settings about where your
application can be deployed, how many instances can be deployed to at once,
what should be considered a failed deploy, and information on the trust-role to
use to allow CodeDeploy to interact with your EC2 instances.

**Note**: A CodeDeploy application does not specify what is to be deployed or what to
do during the deployment.
*What* to deploy is an archive of code/resources stored in S3 called an
`application revision`.
*How* to deploy is specified by the `AppSpec` file located inside the
application revision.

The AppSpec file lives in your repo and tells CodeDeploy which files from
your application to deploy, where to deploy them, and also allows you specify
lifecyle scripts to be run at different stages during the deployment. You can
use these lifecycle scripts to stop your service before a new version is
deployed, run database migrations, install dependencies etc.

An application revision is a zipfile or tarball containing the code/resources
to be deployed. It's usually created by packaging up your entire repo but can
be a sub-directory of the repo if desired. The `AppSpec` file must be stored
in the application revision as `<application-root>/appspec.yml`.

Generally speaking you'll have one application in your repo and so your
application revision can be created by packaging up your whole repo (excluding
`.git`). In this case `appspec.yml` should be placed in your repo root directory.

Application revisions are stored in [S3][] and are identified by the
combination of a bucket name, key, eTag, and for versioned buckets, the
object's version.

The most straightforward way to configure a new application is to log on to the
[CodeDeploy console][] which can guide you through the process of [creating a new
application][].

[comment]: <> "[AppSpec]: TODO link to doc on appspecs, linkify occurrences of 'AppSpec'"
[comment]: <> "[application revision]: TODO link to doc on application revisions, linkify occurrences of 'application revisions'"
[S3]: http://aws.amazon.com/s3/
[CodeDeploy console]: https://console.aws.amazon.com/codedeploy/home
[creating a new application]: https://console.aws.amazon.com/codedeploy/home#/applications/new



## Configuring CircleCI

CircleCI will automatically create new application revisions, upload them to
S3, and both trigger and watch deployments when you get a green build.

### Step 1: Create an IAM user for CircleCI to use
You should create an [IAM user][] to use solely for builds on
CircleCI, that way you have control over exactly which of your resources can be
accessed by code running as part of your build.

Take note of the Access Key ID and Secret Access Key allocated to your new IAM
user, you'll need these later.

For deploying with CodeDeploy your IAM user needs to be able to access S3 and
CodeDeploy at a minimum.

#### S3 IAM policy
CircleCI needs to be able to upload application revisions to your S3 bucket.
Permissions can be scoped down to the common-prefix you use for application
revision keys if you don't want to give access to the entire bucket.

The following policy snippet allows us to upload to `my-bucket` as long as the
key starts with `my-app`.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject"
          ],
          "Resource": [
            "arn:aws:s3:::my-bucket/my-app*"
{'fraction_non_alphanumeric': 0.060218767990788714, 'fraction_numerical': 0.0064478986758779505, 'mean_word_length': 4.270631067961165, 'pattern_counts': {'":': 10, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2267776', 'n_tokens_mistral': 2277, 'n_tokens_neox': 2177, 'n_words': 1234}