1_Lab1.md

Lab 1 - Build project on the cloud

AWS Cloud9 IDE - Set up

AWS Cloud9 is a cloud-based integrated development environment (IDE) that lets you write, run, and debug your code with just a browser. It includes a code editor, debugger, and terminal. Cloud9 comes pre-packaged with essential tools for popular programming languages and the AWS Command Line Interface (CLI) pre-installed so you don't need to install files or configure your laptop for this workshop. Your Cloud9 environment will have access to the same AWS resources as the user with which you logged into the AWS Management Console.

Take a moment now and setup your Cloud9 development environment.

✅ Step-by-step Instructions

1. Go to the AWS Management Console, click Services then select Cloud9 under Developer Tools.
2. Click Create environment.
3. Enter MyDevEnvironment into Name and optionally provide a Description.
4. Click Next step.
5. You may leave Environment settings at their defaults of launching a new t2.micro EC2 instance which will be paused after 30 minutes of inactivity.
6. Click Next step.
7. Review the environment settings and click Create environment. It will take several minutes for your environment to be provisioned and prepared.
8. Once ready, your IDE will open to a welcome screen. Below that, you should see a terminal prompt similar to: You can run AWS CLI commands in here just like you would on your local computer. Verify that your user is logged in by running the following command.

user:~/environment $ aws sts get-caller-identity

You'll see output indicating your account and user information:

{
    "Account": "123456789012",
    "UserId": "AKIAI44QH8DHBEXAMPLE",
    "Arn": "arn:aws:iam::123456789012:user/user"
}

Keep your AWS Cloud9 IDE opened in a tab throughout this workshop as we'll use it for activities like cloning, pushing changes to repository and using the AWS CLI.

💡 Tips

Keep an open scratch pad in Cloud9 or a text editor on your local computer for notes. When the step-by-step directions tell you to note something such as an ID or Amazon Resource Name (ARN), copy and paste that into the scratch pad.

---

Stage 1: Create an AWS CodeCommit Repository

To create the AWS CodeCommit repository (console)

1. Open the AWS CodeCommit console at https://console.aws.amazon.com/codecommit.

2. On the Welcome page, choose Get Started Now. (If a Dashboard page appears instead, choose Create repository.)

3. On the Create repository page, in the Repository name box, type WebAppRepo.

4. In the Description box, type My demonstration repository.

5. Choose Create repository to create an empty AWS CodeCommit repository named WebAppRepo.

Note The remaining steps in this tutorial assume you have named your AWS CodeCommit repository WebAppRepo. If you use a name other than WebAppRepo, be sure to use it throughout this tutorial. For more information about creating repositories, including how to create a repository from the terminal or command line, see Create a Repository.

---

Stage 2: Clone the Repo

In this step, you will connect to the source repository created in the previous step. Here, you use Git to clone and initialize a copy of your empty AWS CodeCommit repository. Then you specify the user name and email address used to annotate your commits.

First, let's install the git-remote-codecommit (GRC) utility, which will assist us with authenticating to CodeCommit. Run the following from the Cloud9 terminal prompt:

pip install --user git-remote-codecommit

Now do the following to clone the repository:

1. From CodeCommit Console, go to your repository. Click on the Clone URL dropdown and then choose Clone HTTPS (GRC). The URL will be copied to your clipboard.
2. Go to Cloud9 IDE terminal prompt
3. Run git clone to pull down a copy of the repository into the local repo, using the URL copied above. It should be something like this:

user:~/environment $ git clone codecommit::<YOUR-REGION>://WebAppRepo

You would be seeing the following message if cloning is successful. warning: You appear to have cloned an empty repository.

---

Stage 3: Commit changes to Remote Repo

1. Download the Sample Web App Archive by running the following command from IDE terminal.

user:~/environment $ wget https://d328byk3yyihdi.cloudfront.net/v1/Web-App-Archive.zip

2. Unarchive and copy all the contents of the unarchived folder to your local repo folder.

user:~/environment $ unzip Web-App-Archive.zip
user:~/environment $ mv -v Web-App-Archive/* WebAppRepo/

After moving the files, your local repo should like the one below. 3. Change the directory to your local repo folder. Run git add to stage the change:

user:~/environment $ cd WebAppRepo
user:~/environment/WebAppRepo/ $ git add *

4. Run git commit to commit the change:

user:~/environment/WebAppRepo/ $ git commit -m "Initial Commit"

💡 Tip To see details about the commit you just made, run git log.

5. Run git push to push your commit through the default remote name Git uses for your AWS CodeCommit repository (origin), from the default branch in your local repo (master):

user:~/environment/WebAppRepo/ $ git push -u origin master

💡 Tip After you have pushed files to your AWS CodeCommit repository, you can use the AWS CodeCommit console to view the contents.

For more information, see Browse the Contents of a Repository.

---

Stage 4: Prepare Build Service

1. First, let us create the necessary roles required to finish labs. Run the CloudFormation stack to create service roles. Ensure you are launching it in the same region as your AWS CodeCommit repo.

user:~/environment/WebAppRepo (master) $ aws cloudformation create-stack --stack-name DevopsWorkshop-roles \
--template-body https://d328byk3yyihdi.cloudfront.net/v1/01-aws-devops-workshop-roles.template \
--capabilities CAPABILITY_IAM

Tip To learn more about AWS CloudFormation, please refer to AWS CloudFormation UserGuide.

2. Upon completion take a note on the service roles created. Check describe-stacks to find the output of the stack.

3. For Console, refer to the CloudFormation Outputs tab to see output. A S3 Bucket is also created. Make a note of this bucket. This will be used to store the output from CodeBuild in the next step. Sample Output:

4. Run the following commands to get the value of Build Role ARN and S3 bucket from cloudformation template launched earlier.

user:~/environment/WebAppRepo (master) $ sudo yum -y install jq
user:~/environment/WebAppRepo (master) $ echo YOUR-BuildRole-ARN: $(aws cloudformation describe-stacks --stack-name DevopsWorkshop-roles | jq -r '.Stacks[0].Outputs[]|select(.OutputKey=="CodeBuildRoleArn")|.OutputValue')
user:~/environment/WebAppRepo (master) $ echo YOUR-S3-OUTPUT-BUCKET-NAME: $(aws cloudformation describe-stacks --stack-name DevopsWorkshop-roles | jq -r '.Stacks[0].Outputs[]|select(.OutputKey=="S3BucketName")|.OutputValue')

5. Let us create CodeBuild project from CLI. To create the build project using AWS CLI, we need JSON-formatted input. Create a json file named 'create-project.json' under 'MyDevEnvironment'. Copy the content below to create-project.json. (Replace the placeholders marked with <<>> with values for BuildRole ARN, S3 Output Bucket and region from the previous step.)

{
  "name": "devops-webapp-project",
  "source": {
    "type": "CODECOMMIT",
    "location": "https://git-codecommit.<<REPLACE-YOUR-REGION-ID>>.amazonaws.com/v1/repos/WebAppRepo"
  },
  "artifacts": {
    "type": "S3",
    "location": "<<REPLACE-YOUR-S3-OUTPUT-BUCKET-NAME>>",
    "packaging": "ZIP",
    "name": "WebAppOutputArtifact.zip"
  },
  "environment": {
    "type": "LINUX_CONTAINER",
    "image": "aws/codebuild/java:openjdk-8",
    "computeType": "BUILD_GENERAL1_SMALL"
  },
  "serviceRole": "<<REPLACE-YOUR-BuildRole-ARN>>"
}

To know more about the codebuild project json review the spec.

6. Switch to the directory that contains the file you just saved, and run the create-project command:

user:~/environment $ aws codebuild create-project --cli-input-json file://create-project.json

7. Sample output JSON for your reference

{
  "project": {
    "name": "project-name",
    "description": "description",
    "serviceRole": "serviceRole",
    "tags": [
      {
        "key": "tags-key",
        "value": "tags-value"
      }
    ],
    "artifacts": {
      "namespaceType": "namespaceType",
      "packaging": "packaging",
      "path": "path",
      "type": "artifacts-type",
      "location": "artifacts-location",
      "name": "artifacts-name"
    },
    "lastModified": lastModified,
    "timeoutInMinutes": timeoutInMinutes,
    "created": created,
    "environment": {
      "computeType": "computeType",
      "image": "image",
      "type": "environment-type",
      "environmentVariables": [
        {
          "name": "environmentVariable-name",
          "value": "environmentVariable-value",
          "type": "environmentVariable-type"
        }
      ]
    },
    "source": {
      "type": "source-type",
      "location": "source-location",
      "buildspec": "buildspec",
      "auth": {
        "type": "auth-type",
        "resource": "resource"
      }
    },
    "encryptionKey": "encryptionKey",
    "arn": "arn"
  }
}

8. If successful, output JSON should have values such as:

• The lastModified value represents the time, in Unix time format, when information about the build project was last changed.
• The created value represents the time, in Unix time format, when the build project was created.
• The ARN value represents the ARN of the build project.

Note Except for the build project name, you can change any of the build project's settings later. For more information, see Change a Build Project's Settings (AWS CLI).

---

Stage 5: Let's build the code on cloud

1. A build spec is a collection of build commands and related settings in YAML format, that AWS CodeBuild uses to run a build. Create a file namely, buildspec.yml under WebAppRepo folder. Copy the content below to the file and save it. To know more about how CodeBuild works.

version: 0.1

phases:
  install:
    commands:
      - echo Nothing to do in the install phase...
  pre_build:
    commands:
      - echo Nothing to do in the pre_build phase...
  build:
    commands:
      - echo Build started on `date`
      - mvn install
  post_build:
    commands:
      - echo Build completed on `date`
artifacts:
  files:
    - target/javawebdemo.war
  discard-paths: no

As a sample shown below:

Note Visit this page to know more about build spec and how you can use multiple build specs in the same repo.

2. Commit & push the build specification file to repository

user:~/environment/WebAppRepo/ $ git add buildspec.yml
user:~/environment/WebAppRepo/ $ git commit -m "adding buildspec.yml"
user:~/environment/WebAppRepo/ $ git push -u origin master

3. Run the start-build command:

user:~/environment/WebAppRepo (master) $ aws codebuild start-build --project-name devops-webapp-project

Note: You can start build with more advance configuration setting via JSON. If you are interested to learn more about it, please visit here.

4. If successful, data would appear showing successful submission. Make a note of the build id value. You will need it in the next step.
5. In this step, you will view summarized information about the status of your build.

user:~/environment/WebAppRepo (master) $ aws codebuild batch-get-builds --ids <<ID>>

Note: Replace <> with the id value that appeared in the output of the previous step.

6. You will also be able to view detailed information about your build in CloudWatch Logs. You can complete this step by visiting the AWS CodeBuild console.

7. In this step, you will verify the WebAppOutputArtifact.zip file that AWS CodeBuild built and then uploaded to the output bucket. You can complete this step by visiting the AWS CodeBuild console or the Amazon S3 console.

Note: Troubleshooting CodeBuild - Use the information to help you identify, diagnose, and address issues.

Summary:

This concludes Lab 1. In this lab, we successfully created repository with version control using AWS CodeCommit and built our code on the cloud using AWS CodeBuild service. You can now move to the next Lab,

Lab 2 - Automate deployment for testing