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 AWS account. For the simplest testing, you can run the codedeploy-agent deploy-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 2.0.0 or later of the CodeDeploy agent. The deploy-local subcommand requires version 2.0.0 or later. For version 1.8.x and earlier, use the standalone codedeploy-local command instead. For version information, see Version history of the CodeDeploy agent. For installation 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:iam::444455556666:role/CodeDeployDemo to download from anywhere in the Amazon S3 bucket named amzn-s3-demo-bucket:
```
{
    "Statement": [
        {
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
            "Principal": {
                "AWS": [
                    "arn:aws: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:iam::444455556666:user/CodeDeployUser to download from anywhere in the Amazon S3 bucket named amzn-s3-demo-bucket:
```
{
    "Statement": [
        {
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
            "Principal": {
                "AWS": [
                    "arn:aws: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 (AWS CLI or Amazon EC2 console), and Create an Amazon EC2 instance for CodeDeploy (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-agent deploy-local command uses the codedeploy-agent binary in the following locations:

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

For backward compatibility, the codedeploy-local command is also available in the same locations:

On Amazon Linux, RHEL, or Ubuntu Server, the command is located at /opt/codedeploy-agent/bin/codedeploy-local.
On Windows Server, the command is located at C:\ProgramData\Amazon\CodeDeploy\bin\codedeploy-local.exe.

The codedeploy-local [options] syntax continues to work and accepts the same options as codedeploy-agent deploy-local.

Basic Command Syntax


codedeploy-agent deploy-local [options]

Synopsis


codedeploy-agent deploy-local
[--bundle-location <value>]
[--type <value>]
[--file-exists-behavior <value>]
[--deployment-group <value>]
[--deployment-group-name <value>]
[--application-name <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://amzn-s3-demo-bucket/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 AWS 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 local-1234 (where the number is the process ID).

-d, --deployment-group-name

The deployment group name exposed to lifecycle-hook scripts as the DEPLOYMENT_GROUP_NAME environment variable. Defaults to LocalFleet.

-a, --application-name

The application name exposed to lifecycle-hook scripts as the APPLICATION_NAME environment variable. Defaults to the bundle location.

-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-agent deploy-local


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


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


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

Deploy a bundle from Amazon S3:


codedeploy-agent deploy-local --bundle-location s3://amzn-s3-demo-bucket/bundle.tgz --type tgz


codedeploy-agent deploy-local --bundle-location s3://amzn-s3-demo-bucket/bundle.zip?versionId=1234&etag=47e8 --type zip --deployment-group my-deployment-group

Deploy a bundle from a public GitHub repository:


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


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


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


codedeploy-agent deploy-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-agent deploy-local --bundle-location /path/to/local/bundle.tar --type tar --deployment-group my-deployment-group --events DownloadBundle,Install,ApplicationStart,HealthCheck

Stop a previously deployed application using the ApplicationStop lifecycle event:


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

Deploy using a specific deployment group ID:


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


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

Warning 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.

Document Conventions

Deploy an application in a different AWS account

Monitoring deployments