localcb

Run AWS CodeBuild pipeline directly on your local machine using Docker containers.

localcb

AWS CodeBuild uses buildspec.yml file as the definition of the stages (named as phases) and shell commands. It uses single Docker image during the runtime. Developers might use official, AWS CodeBuild curated Docker images or create own to meet their demands.

In most of cases one of AWS CodeBuild curated Docker image will be used, that's why you probably will need to clone repository and build them on your local machine. I recommend to navigate to the official repository for more information.

Installation

go get -u -v github.com/piotrkubisa/localcb/cmd/localcb/

Additional requirements:

• Docker client.
• Add $GOPATH/bin to your $PATH (to run localcb without the need to provide absolute path to the statically linked binary).

Usage

For more information it is recommended to inspect localcb --help.

Downloading a Docker container image

$ localcb build aws/codebuild/docker:17.09.0
# Run following commands:

cd /tmp
git clone https://github.com/aws/aws-codebuild-docker-images.git
cd aws-codebuild-docker-images
cd ubuntu/Unsupported\ Images/docker/17.09.0
docker build -t aws/codebuild/docker:17.09.0 .

The short form of the image name is also supported (this command will have exactly the same output as in above example):

$ localcb build docker:17.09.0

Running

The simplest form of localcb command with AWS CodeBuild requires providing --image flag with a name of the Docker image, which are going to be used to run all shell commands inside.

localcb run --image aws/codebuild/docker:17.09.0

localcb will load buildspec.yml file, parse all defined phases and shell commands, create localcb.sh file and then (unless --dry-run flag was provided) it will start docker container (with mounted volume and with bind env-variables) and execute aforementioned localcb.sh file.

If you aware that localcb might do something inappropriate or you just want a command that runs bare docker, then --dry-run comes with a helping hand:

$ localcb run --dry-run  \
    --basedir ./_examples/aws-codebuild/sample/ \
    --file ./_examples/aws-codebuild/sample/buildspec.yml \
    --image aws/codebuild/docker:17.09.0 \
    --env "SOME_VARIABLE=Hello World" \
    --env CODEBUILD_RESOLVED_SOURCE_VERSION=`git rev-list --all --max-count=1`

docker run \
    --privileged \
    --rm \
    --interactive \
    --env 'AWS_DEFAULT_REGION=local' \
    --env 'AWS_REGION=local' \
    --env 'CODEBUILD_BUILD_ARN=arn:aws:codebuild:local:000000000:build/codebuild-localcb-project:00000000-0000-0000-0000-00000' \
    --env 'CODEBUILD_BUILD_ID=codebuild-localcb-project:00000000-0000-0000-0000-00000' \
    --env 'CODEBUILD_BUILD_IMAGE=aws/codebuild/docker:17.09.'0\
    --env 'CODEBUILD_BUILD_SUCCEEDING=1' \
    --env 'CODEBUILD_INITIATOR=codepipeline:localcb-pipeline' \
    --env 'CODEBUILD_KMS_KEY_ID=arn:aws:kms:local:000000000:key/notExistingID' \
    --env 'CODEBUILD_RESOLVED_SOURCE_VERSION=ffffffff' \
    --env 'CODEBUILD_SOURCE_REPO_URL=s3://bucket_name/input_artifact.zip' \
    --env 'CODEBUILD_SOURCE_VERSION=ffffffff' \
    --env 'CODEBUILD_SRC_DIR=/tmp/sr'c\
    --env 'HOME=/root' \
    --env 'BINARY_NAME=localcb-example' \
    --env 'DOCKER_IMAGE_GO=golang:1' \
    --env 'PROJECT_NAME=example' \
    --env 'REPOSITORY_PATH=piotrkubisa/localcb/_examples/aws-codebuild/sample' \
    --env 'SOURCE_CODE=main.go' \
    --env 'SOME_VARIABLE=Hello World' \
    --env 'CODEBUILD_RESOLVED_SOURCE_VERSION=6a11f52d6721ff7afb5a076a34d88e3fafbb37a6' \
    --volume /home/user/path/to/localcb/_examples/aws-codebuild/sample:/tmp/src \
    --workdir /tmp/src \
    --entrypoint dockerd-entrypoint.sh \
        aws/codebuild/docker:17.09.0 \
            sh ./localcb.sh

In above example the command will be printed out, so it can be easily modified (note: backslashes and new lines were added for brevity).

Credits

During creating initial version of localcb I has been inspired by the well-known awslabs/aws-sam-local to resemble its logic and create a sample application which parses a AWS CodeBuild's definition and run it on my local machine.