Announcing Local Build Support for AWS CodeBuild

Today, we’re excited to announce local build support in AWS CodeBuild.

AWS CodeBuild is a fully managed build service. There are no servers to provision and scale, or software to install, configure, and operate. You just specify the location of your source code, choose your build settings, and CodeBuild runs build scripts for compiling, testing, and packaging your code.

In this blog post, I’ll show you how to set up CodeBuild locally to build and test a sample Java application.

By building an application on a local machine you can:

Test the integrity and contents of a buildspec file locally.
Test and build an application locally before committing.
Identify and fix errors quickly from your local development environment.

Prerequisites

In this post, I am using AWS Cloud9 IDE as my development environment.

If you would like to use AWS Cloud9 as your IDE, follow the express setup steps in the AWS Cloud9 User Guide.

The AWS Cloud9 IDE comes with Docker and Git already installed. If you are going to use your laptop or desktop machine as your development environment, install Docker and Git before you start.

Steps to build CodeBuild image locally

Run git clone https://github.com/aws/aws-codebuild-docker-images.git to download this repository to your local machine.

$ git clone https://github.com/aws/aws-codebuild-docker-images.git

Lets build a local CodeBuild Standard 3.0 image. The Dockerfile for Standard 3.0 is present in /aws-codebuild-docker-images/ubuntu/standard/3.0.

Edit the Dockerfile to remove the last line ENTRYPOINT [“dockerd-entrypoint.sh”] and save the file.

Run cd ubuntu/standard/3.0. to change the directory in your local workspace.

Run docker build -t aws/codebuild/standard:3.0 . to build the Docker image locally. This command will take few minutes to complete.

$ cd aws-codebuild-docker-images
$ cd ubuntu/standard/3.0
$ docker build -t aws/codebuild/standard:3.0 .

Steps to setup CodeBuild local agent

Run the following Docker pull command to download the local CodeBuild agent.

$ docker pull amazon/aws-codebuild-local:latest --disable-content-trust=false

Run the following to download codebuild_build.sh script to run your local builds.

$ wget https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh
$ chmod +x codebuild_build.sh

Now you have the local agent image and codebuild script on your machine to run a local build.

Run the following git command to download a sample Java project.

$ git clone https://github.com/karthiksambandam/sample-web-app.git

Steps to use the local agent to build a sample project

Let’s build the sample Java project using the local agent.

Execute the following command to run the local agent and build the sample web app repository you cloned earlier.

$ ./codebuild_build.sh -i aws/codebuild/standard:3.0 -a /home/ec2-user/environment/artifacts -s /home/ec2-user/environment/sample-web-app

Note: Usage instruction for codebuild_build.sh script.

$ codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options]

Required:

-i Used to specify the customer build container image.
-a Used to specify an artifact output directory.

Optional:
-s Used to specify a source directory. Defaults to the current working directory.
-c Use the AWS configuration and credentials from your local host. This includes ~/.aws and any AWS_* environment variables.
-b Used to specify a buildspec override file. Defaults to buildspec.yml in the source directory.
-e Used to specify a file containing environment variables.

Environment variable file format:

Expects each line to be in VAR=VAL format
Lines beginning with # are processed as comments and ignored
Blank lines are ignored
File can be of type .env or .txt
There is no special handling of quotation marks, meaning they will be part of the VAL

For more information on how to use these variables, see local build script.

Note: If running on a different operating system, your absolute path may vary:

Linux: /home/user/…
MacOS: /Users/user/…

When you run the sample project, you get a runtime error that says the YAML file does not exist. This is because a buildspec.yml file is not included in the sample web project. AWS CodeBuild requires a buildspec.yml to run a build. For more information about buildspec.yml, see Build Spec Example in the AWS CodeBuild User Guide.

Let’s add a buildspec.yml file with the following content to the sample-web-app folder and then rebuild the project.

version: 0.2

phases:
  build:
    commands:
      - echo Build started on `date`
      - mvn install

artifacts:
  files:
    - target/javawebdemo.war

$ ./codebuild_build.sh -i aws/codebuild/standard:3.0 -a /home/ec2-user/environment/artifacts -s /home/ec2-user/environment/sample-web-app

This time your build should be successful. Upon successful execution, look in the /artifacts folder for the final built artifacts.zip file to validate.

If you face any issue in running the local agent, then report it here.

Conclusion:

In this blog post, I showed you how to quickly set up the CodeBuild local agent to build projects right from your local desktop machine or laptop. As you see, local builds can improve developer productivity by helping you identify and fix errors quickly.

I hope you found this post useful. Feel free to leave your feedback or suggestions in the comments.

AWS DevOps & Developer Productivity Blog