Prerequisites Create a local deployment Examples

Use the CodeDeploy agent to validate a deployment package on a local machine

Using the CodeDeploy agent, you can deploy content on an instance you are logged in to. This allows you to test the integrity of an application specification file (AppSpec file) that you intend to use in a deployment and the content you intend to deploy.

You do not need to create an application and deployment group. If you want to deploy content stored on the local instance, you do not even need an Amazon account. For the simplest testing, you can run the codedeploy-local command, without specifying any options, in a directory that contains the AppSpec file and the content to be deployed. There are options for other test cases in the tool.

By validating a deployment package on a local machine you can:

Test the integrity of an application revision.
Test the contents of an AppSpec file.
Try out CodeDeploy for the first time with your existing application code.
Deploy content rapidly when you are already logged in to an instance.

You can use deploy content that is stored on the local instance or in a supported remote repository type (Amazon S3 buckets or public GitHub repositories).

Prerequisites

Before you start a local deployment, complete the following steps:

Create or use an instance type supported by the CodeDeploy agent. For information, see Operating systems supported by the CodeDeploy agent.
Install version 1.0.1.1352 or later of the CodeDeploy agent. For information, see Install the CodeDeploy agent.
If you are deploying your content from an Amazon S3 bucket or GitHub repository, provision a user to use with CodeDeploy. For information, see Step 1: Setting up.
If you are deploying your application revision from an Amazon S3 bucket, create an Amazon S3 bucket in the region you are working in and apply an Amazon S3 bucket policy to the bucket. This policy grants your instances the permissions required to download the application revision.

For example, the following Amazon S3 bucket policy allows any Amazon EC2 instance with an attached IAM instance profile containing the ARN arn:aws-cn:iam::444455556666:role/CodeDeployDemo to download from anywhere in the Amazon S3 bucket named codedeploydemobucket:
```
{
    "Statement": [
        {
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws-cn:s3:::codedeploydemobucket/*",
            "Principal": {
                "AWS": [
                    "arn:aws-cn:iam::444455556666:role/CodeDeployDemo"
                ]
            }
        }
    ]
}
```
The following Amazon S3 bucket policy allows any on-premises instance with an associated IAM user containing the ARN arn:aws-cn:iam::444455556666:user/CodeDeployUser to download from anywhere in the Amazon S3 bucket named codedeploydemobucket:
```
{
    "Statement": [
        {
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws-cn:s3:::codedeploydemobucket/*",
            "Principal": {
                "AWS": [
                    "arn:aws-cn:iam::444455556666:user/CodeDeployUser"
                ]
            }
        }
    ]
}
```
For information about how to generate and attach an Amazon S3 bucket policy, see Bucket policy examples.
If you are deploying your application revision from an Amazon S3 bucket or GitHub repository, set up an IAM instance profile and attach it to the instance. For information, see Step 4: Create an IAM instance profile for your Amazon EC2 instances, Create an Amazon EC2 instance for CodeDeploy (Amazon CLI or Amazon EC2 console), and Create an Amazon EC2 instance for CodeDeploy (Amazon CloudFormation template).
If you are deploying your content from GitHub, create a GitHub account and a public repository. To create a GitHub account, see Join GitHub. To create a GitHub repository, see Create a repo.

Note
Private repositories are not currently supported. If your content is stored in a private GitHub repository, you can download it to the instance and use the --bundle-location option to specify its local path.
Prepare the content (including an AppSpec file) that you want to deploy to the instance and place it on the local instance, in your Amazon S3 bucket, or in your GitHub repository. For information, see Working with application revisions for CodeDeploy.
If you want to use values other than the defaults for other configuration options, create the configuration file and place it on the instance (/etc/codedeploy-agent/conf/codedeployagent.yml for Amazon Linux, RHEL, or Ubuntu Server instances or C:\ProgramData\Amazon\CodeDeploy\conf.yml for Windows Server instances). For information, see CodeDeploy agent configuration reference.
Note
If you use a configuration file on Amazon Linux, RHEL, or Ubuntu Server instances, you must either:
- Use the :root_dir: and :log_dir: variables to specify locations other than the defaults for the deployment root and log directory folders.
- Use sudo to run CodeDeploy agent commands.

Create a local deployment

On the instance where you want to create the local deployment, open a terminal session (Amazon Linux, RHEL, or Ubuntu Server instances) or a command prompt (Windows Server) to run the tool commands.

Note

The codedeploy-local command is installed in the following locations:

On Amazon Linux, RHEL, or Ubuntu Server: /opt/codedeploy-agent/bin.
On Windows Server: C:\ProgramData\Amazon\CodeDeploy\bin.

Basic Command Syntax


codedeploy-local [options]

Synopsis


codedeploy-local
[--bundle-location <value>]
[--type <value>]
[--file-exists-behavior <value>]
[--deployment-group <value>]
[--events <comma-separated values>]
[--agent-configuration-file <value>]
[--appspec-filename <value>]

Options

-l, --bundle-location

The location of the application revision bundle. If you do not specify a location, the tool uses the directory you are currently working in by default. If you specify a value for --bundle-location, you must also specify a value for --type.

Bundle location format examples:

Local Amazon Linux, RHEL, or Ubuntu Server instance: /path/to/local/bundle.tgz
Local Windows Server instance: C:/path/to/local/bundle
Amazon S3 bucket: s3://mybucket/bundle.tar
GitHub repository: https://github.com/account-name/repository-name/

-t, --type

The format of the application revision bundle. Supported types include tgz, tar, zip, and directory. If you do not specify a type, the tool uses directory by default. If you specify a value for --type, you must also specify a value for --bundle-location.

-b, --file-exists-behavior

Indicates how files are handled that already exist in a deployment target location but weren't part of a previous successful deployment. Options include DISALLOW, OVERWRITE, RETAIN. For more information, see fileExistsBehavior in Amazon CodeDeploy API Reference.

-g, --deployment-group

The path to the folder that is the target location for the content to be deployed. If you do not specify a folder, the tool creates one named default-local-deployment-group inside your deployment root directory. For each local deployment you create, the tool creates a subdirectory inside this folder with names such as d-98761234-local.

-e, --events

A set of override lifecycle event hooks you want to run, in order, instead of the events you listed in the AppSpec file. Multiple hooks can be specified, separated by commas. You can use this option if:

You want to run a different set of events without having to update the AppSpec file.
You want to run a single event hook as an exception to what's in the AppSpec file, such as ApplicationStop.

If you don't specify DownloadBundle and Install events in the override list, they will run before all the event hooks you do specify. If you include DownloadBundle and Install in the list of --events options, they must be preceded only by events that normally run before them in CodeDeploy deployments. For information, see AppSpec 'hooks' section.

-c, --agent-configuration-file

The location of a configuration file to use for the deployment, if you store it in a location other than the default. A configuration file specifies alternatives to other default values and behaviors for a deployment.

By default, configuration files are stored in /etc/codedeploy-agent/conf/codedeployagent.yml (Amazon Linux, RHEL, or Ubuntu Server instances) or C:/ProgramData/Amazon/CodeDeploy/conf.yml (Windows Server). For more information, see CodeDeploy agent configuration reference.

-A, --appspec-filename

The name of the AppSpec file. For local deployments, accepted values are appspec.yml and appspec.yaml. By default, the AppSpec file is called appspec.yml.

-h, --help

Displays a summary of help content.

-v, --version

Displays the tool's version number.

Examples

The following are examples of valid command formats.


codedeploy-local


codedeploy-local --bundle-location /path/to/local/bundle/directory


codedeploy-local --bundle-location C:/path/to/local/bundle.zip --type zip --deployment-group my-deployment-group


codedeploy-local --bundle-location /path/to/local/directory --type directory --deployment-group my-deployment-group

Deploy a bundle from Amazon S3:


codedeploy-local --bundle-location s3://mybucket/bundle.tgz --type tgz


codedeploy-local --bundle-location s3://mybucket/bundle.zip?versionId=1234&etag=47e8 --type zip --deployment-group my-deployment-group

Deploy a bundle from a public GitHub repository:


codedeploy-local --bundle-location https://github.com/awslabs/aws-codedeploy-sample-tomcat --type zip


codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/master --type zip


codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/HEAD --type zip


codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/1a2b3c4d --type zip

Deploy a bundle specifying multiple lifecycle events:


codedeploy-local --bundle-location /path/to/local/bundle.tar --type tar --application-folder my-deployment --events DownloadBundle,Install,ApplicationStart,HealthCheck

Stop a previously deployed application using the ApplicationStop lifecycle event:


codedeploy-local --bundle-location /path/to/local/bundle.tgz --type tgz --deployment-group --events ApplicationStop

Deploy using a specific deployment group ID:


codedeploy-local --bundle-location C:/path/to/local/bundle/directory --deployment-group 1234abcd-5dd1-4774-89c6-30b107ac5dca


codedeploy-local --bundle-location C:/path/to/local/bundle.zip --type zip --deployment-group 1234abcd-5dd1-4774-89c6-30b107ac5dca

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Deploy an application in a different Amazon account

Monitoring deployments