AWS CodeBuild
User Guide (API Version 2016-10-06)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

AWS Elastic Beanstalk Sample for AWS CodeBuild

This sample instructs AWS CodeBuild to use Maven to produce as build output a single WAR file named my-web-app.war. This sample then deploys the WAR file to the instances in an Elastic Beanstalk environment.

Important

Running this sample might result in charges to your AWS account. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon EC2. For more information, see CodeBuild Pricing, Amazon S3 Pricing, AWS Key Management Service Pricing, Amazon CloudWatch Pricing, and Amazon EC2 Pricing.

Create the Source Code

In this section, you use Maven to produce the source code. Later on, you use AWS CodeBuild to build a WAR file based on this source code.

  1. Download and install Maven. For information, see Downloading Apache Maven and Installing Apache Maven on the Apache Maven website.

  2. Switch to an empty directory on your local computer or instance, and then run this Maven command.

    mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-web-app -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

    If successful, this directory structure and files are created.

    (root directory name) `-- my-web-app |-- pom.xml `-- src `-- main |-- resources `-- webapp |-- WEB-INF | `-- web.xml `-- index.jsp
  3. Create a subdirectory named .ebextensions in the (root directory name)/my-web-app directory. In the .ebextensions subdirectory, create a file named fix-path.config with this content.

    container_commands: fix_path: command: "unzip my-web-app.war 2>&1 > /var/log/my_last_deploy.log"

After you run Maven, continue with one of the following scenarios:

Scenario A: Run AWS CodeBuild Manually and Deploy to Elastic Beanstalk Manually

In this scenario, you create and upload the source code. You then use the AWS CodeBuild and Elastic Beanstalk consoles to build the source code, create an Elastic Beanstalk application and environment, and deploy the build output to the environment.

Step A1: Add Files to the Source Code

In this step, you add an Elastic Beanstalk configuration file and a build spec file to the code in Create the Source Code. You then upload the source code to an Amazon S3 input bucket or an AWS CodeCommit or GitHub repository .

  1. Create a file named buildspec.yml with the following contents. Store the file in the (root directory name)/my-web-app directory.

    version: 0.2 phases: install: runtime-versions: java: corretto11 post_build: commands: - mvn package - mv target/my-web-app.war my-web-app.war artifacts: files: - my-web-app.war - .ebextensions/**/*
  2. Your file structure should now look like this.

    (root directory name) `-- my-web-app |-- .ebextensions | `-- fix-path.config |-- src | `-- main | |-- resources | `-- webapp | |-- WEB-INF | | `-- web.xml | `-- index.jsp |-- buildpsec.yml `-- pom.xml
  3. Upload the contents of the my-web-app directory to an Amazon S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository.

    Important

    Do not upload (root directory name) or (root directory name)/my-web-app, just the directories and files in (root directory name)/my-web-app.

    If you are using an Amazon S3 input bucket, it must be versioned. Be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket. Do not add (root directory name) or (root directory name)/my-web-app to the ZIP file, just the directories and files in (root directory name)/my-web-app. For more information, see How to Configure Versioning on a Bucket.

Step A2: Create the Build Project and Run the Build

In this step, you use the AWS CodeBuild console to create a build project and then run a build.

  1. Create or identify an Amazon S3 output bucket to store the build output. If you're storing the source code in an Amazon S3 input bucket, the output bucket must be in the same AWS region as the input bucket.

  2. Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

    Use the AWS region selector to choose a region that supports CodeBuild and matches the region where your Amazon S3 output bucket is stored.

  3. Create a build project and then run a build. For more information, see Create a Build Project (Console) and Run a Build (Console). Leave all settings at their default values, except for these settings.

    • For Environment:

      • For Environment image, choose Managed image.

      • For Operating system, choose Amazon Linux 2.

      • For Runtime(s), choose Standard.

      • For Image, choose aws/codebuild/amazonlinux2-x86_64-standard:1.0.

    • For Artifacts:

      • For Type, choose Amazon S3.

      • For Bucket name, enter the name of an Amazon S3 bucket.

      • For Name, enter a build output file name that's easy for you to remember. Include the .zip extension.

      • For Artifacts packaging, choose Zip.

Step A3: Create the Application and Environment and Deploy

In this step, you use the Elastic Beanstalk console to create an application and environment. As part of creating the environment, you deploy the build output from the previous step to the environment.

  1. Open the Elastic Beanstalk console at https://console.aws.amazon.com/elasticbeanstalk.

    Use the AWS region selector to choose the region where your Amazon S3 output bucket is stored.

  2. Create an Elastic Beanstalk application. For more information, see Managing and Configuring AWS Elastic Beanstalk Applications.

  3. Create an Elastic Beanstalk environment for this application. For more information, see The Create New Environment Wizard. Leave all settings at their default values, except for these settings.

    • For Platform, choose Tomcat.

    • For Application code, choose Upload your code, and then choose Upload. For Source code origin, choose Public S3 URL, and then enter the full URL to the build output ZIP file in the output bucket. Choose Upload.

  4. After Elastic Beanstalk deploys the build output to the environment, you can see the results in a web browser. Go to the environment URL for the instance (for example, http://my-environment-name.random-string.region-ID.elasticbeanstalk.com). The web browser should display the text Hello World!.

Scenario B: Use CodePipeline to Run AWS CodeBuild and Deploy to Elastic Beanstalk

In this scenario, you complete the steps to prepare and upload the source code. You create a build project with CodeBuild and an AWS Elastic Beanstalk application and environment with the AWS Elastic Beanstalk console. You then use the AWS CodePipeline console to create a pipeline. After you create the pipeline, CodePipeline builds the source code and deploys the build output to the environment.

Step B1: Add a Build Spec File to the Source Code

In this step, you create and add a build spec file to the code you created in Create the Source Code. You then upload the source code to an Amazon S3 input bucket or a CodeCommit or GitHub repository.

  1. Create a file named buildspec.yml with the following contents. Store the file in the (root directory name)/my-web-app directory.

    version: 0.2 phases: install: runtime-versions: java: corretto11 post_build: commands: - mvn package - mv target/my-web-app.war my-web-app.war artifacts: files: - my-web-app.war - .ebextensions/**/* base-directory: 'target/my-web-app'
  2. Your file structure should now look like this.

    (root directory name) `-- my-web-app |-- .ebextensions | `-- fix-path.config |-- src | `-- main | |-- resources | `-- webapp | |-- WEB-INF | | `-- web.xml | `-- index.jsp |-- buildpsec.yml `-- pom.xml
  3. Upload this contents of the my-web-app directory to an Amazon S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository.

    Important

    Do not upload (root directory name) or (root directory name)/my-web-app, just the directories and files in (root directory name)/my-web-app.

    If you are using an Amazon S3 input bucket, it must be versioned. Be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket. Do not add (root directory name) or (root directory name)/my-web-app to the ZIP file, just the directories and files in (root directory name)/my-web-app. For more information, see How to Configure Versioning on a Bucket.

Step B2: Create a build project

In this step, you create an AWS CodeBuild build project to use with your pipeline.

  1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

  2. Create a build project. For more information, see Create a Build Project (Console) and Run a Build (Console). Leave all settings at their default values, except for these settings.

    • For Environment:

      • For Environment image, choose Managed image.

      • For Operating system, choose Amazon Linux 2.

      • For Runtime(s), choose Standard.

      • For Image, choose aws/codebuild/amazonlinux2-x86_64-standard:1.0.

    • For Artifacts:

      • For Type, choose Amazon S3.

      • For Bucket name, enter the name of an Amazon S3 bucket.

      • For Name, enter a build output file name that's easy for you to remember. Include the .zip extension.

      • For Artifacts packaging, choose Zip.

Step B3: Create an AWS Elastic Beanstalk application and environment

In this step, you create an AWS Elastic Beanstalk application and environment to use with CodePipeline.

  1. Open the Elastic Beanstalk console at https://console.aws.amazon.com/elasticbeanstalk/.

  2. Use the Elastic Beanstalk console to create an application. For more information, see Managing and Configuring AWS Elastic Beanstalk Applications.

  3. Use the Elastic Beanstalk console to create an environment. For more information, see The Create New Environment Wizard. Except for Platform, leave all settings at their default values. For Platform, choose Tomcat.

Step B4: Create the Pipeline and Deploy

In this step, you use the CodePipeline console to create a pipeline. After you create and run the pipeline, CodePipeline uses AWS CodeBuild to build the source code. CodePipeline then uses Elastic Beanstalk to deploy the build output to the environment.

  1. Create or identify a service role that CodePipeline, CodeBuild, and Elastic Beanstalk can use to do their work on your behalf. For more information, see Prerequisites.

  2. Open the CodePipeline console at https://console.aws.amazon.com/codesuite/codepipeline/home.

    Use the AWS region selector to choose a region that supports CodeBuild and, if you're storing the source code in an Amazon S3 input bucket, choose the region where your input bucket is stored.

  3. Create a pipeline. For information, see Create a Pipeline That Uses CodeBuild (CodePipeline Console). Leave all settings at their default values, except for these settings.

    • On Add build stage, for Build provider, choose AWS CodeBuild. For Project name, choose the build project you just created.

    • On Add deploy stage, for Deploy provider, choose AWS Elastic Beanstalk.

      • For Application name, choose the Elastic Beanstalk application you just created.

      • For Environment name, choose the environment you just created.

  4. After the pipeline has run successfully, you can see the results in a web browser. Go to the environment URL for the instance (for example, http://my-environment-name.random-string.region-ID.elasticbeanstalk.com). The web browser should display the text Hello World!.

Now, whenever you make changes to the source code and upload those changes to the original Amazon S3 input bucket or to the CodeCommit, GitHub, or Bitbucket repository, CodePipeline detects the change and runs the pipeline again. This causes CodeBuild to rebuild the code and then causes Elastic Beanstalk to deploy the rebuilt output to the environment.

Scenario C: Use the Elastic Beanstalk CLI to Run AWS CodeBuild and Deploy to an Elastic Beanstalk Environment

In this scenario, you complete the steps to prepare and upload the source code. You then run the Elastic Beanstalk CLI to create an Elastic Beanstalk application and environment, use CodeBuild to build the source code, and then deploy the build output to the environment. For more information, see Using the EB CLI with CodeBuild in the AWS Elastic Beanstalk Developer Guide.

Step C1: Add Files to the Source Code

In this step, you add an Elastic Beanstalk configuration file and a build spec file to the code you created in Create the Source Code. You also create or identify a service role for the build spec file.

  1. Create or identify a service role that Elastic Beanstalk and the CLI can use on your behalf. For information, see Create a CodeBuild Service Role.

  2. Create a file named buildspec.yml with the following contents. Store the file in the (root directory name)/my-web-app directory.

    version: 0.2 phases: install: runtime-versions: java: corretto11 post_build: commands: - mvn package - mv target/my-web-app.war my-web-app.war artifacts: files: - my-web-app.war - .ebextensions/**/* eb_codebuild_settings: CodeBuildServiceRole: my-service-role-name ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:2.0 Timeout: 60

    In the preceding code, replace my-service-role-name with the name of the service role you created or identified earlier.

  3. Your file structure should now look like this.

    (root directory name) `-- my-web-app |-- .ebextensions | `-- fix-path.config |-- src | `-- main | |-- resources | `-- webapp | |-- WEB-INF | | `-- web.xml | `-- index.jsp |-- buildpsec.yml `-- pom.xml

Step C2: Install and Run the EB CLI

  1. If you have not already done so, install and configure the EB CLI on the same computer or instance where you created the source code. For information, see Install the Elastic Beanstalk Command Line Interface (EB CLI) and Configure the EB CLI in the AWS Elastic Beanstalk Developer Guide.

  2. From your computer's or instance's command line or terminal, run the cd command or similar to switch to your (root directory name)/my-web-app directory. Run the eb init command to configure the EB CLI.

    eb init

    When prompted:

    • Choose an AWS Region where AWS CodeBuild is supported and where you want to create your Elastic Beanstalk application and environment.

    • Create an Elastic Beanstalk application, and enter a name for the application.

    • Choose the Tomcat platform.

    • Choose the Tomcat 8 Java 8 version.

    • Choose whether you want to use SSH to set up access to your environment's instances.

  3. From the same directory, run the eb create command to create an Elastic Beanstalk environment.

    eb create

    When prompted:

    • Enter the name for the environment or accept the suggested name.

    • Enter the DNS CNAME prefix for the environment or accept the suggested value.

    • For this sample, accept the Classic load balancer type.

  4. After you run the eb create command, the EB CLI does the following:

    1. Creates a ZIP file from the source code and then uploads the ZIP file to an Amazon S3 bucket in your account.

    2. Creates an Elastic Beanstalk application and application version.

    3. Creates a AWS CodeBuild project.

    4. Runs a build based on the new project.

    5. Deletes the project after the build is complete.

    6. Creates an Elastic Beanstalk environment.

    7. Deploys the build output to the environment.

  5. After the EB CLI deploys the build output to the environment, you can see the results in a web browser. Go to the environment URL for the instance (for example, http://my-environment-name.random-string.region-ID.elasticbeanstalk.com). The web browser should display the text Hello World!.

If you want, you can make changes to the source code and then run the eb deploy command from the same directory. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment.

Related Resources