Tutorial: Creating a project with the Modern three-tier web application blueprint

You can get started more quickly with developing software by creating a project with a blueprint. A project created with a blueprint includes the resources that you need, including a source repository to manage your code, and a workflow to build and deploy the application. In this tutorial, we will walk you through using the Modern three-tier web application blueprint to create a project in CodeCatalyst. The tutorial also includes viewing the deployed sample, inviting other users to work on it, and making changes to the code with pull requests that are automatically built and deployed to resources in the connected AWS account when the pull request is merged. Where CodeCatalyst creates your project with reports, activity feeds, and other tools, your blueprint creates AWS resources in the AWS account associated with your project. Your blueprint files allow you to build and test a sample modern application and deploy it to infrastructure in the cloud.

The following illustration shows how tools in CodeCatalyst are used to create an issue for tracking, merge and automatically build the change, and then start a workflow in the CodeCatalyst project that runs actions to allow AWS CDK and AWS CloudFormation to provision your infrastructure.

The actions generate resources in the associated AWS account and deploy your application to a serverless Lambda platform with an API Gateway endpoint. The AWS Cloud Development Kit (AWS CDK) action converts one or more AWS CDK stacks to AWS CloudFormation templates and deploys stacks to your AWS account. Resources in your stacks include CloudFront resources to distribute dynamic web content, a DynamoDB instance for your application data, and the roles and policies that support the deployed application.

When you create a project with the Modern three-tier web application blueprint, your project is created with the following resources:

In the CodeCatalyst project:

• A source repository with sample code and workflow YAML

• A workflow that builds and deploys the sample code whenever a change is made to the default branch

• An issues board and backlog that you can use to plan and track work

• A test reports suite with automated reports included in the sample code

In the associated AWS account:

• Three AWS CloudFormation stacks that create the resources needed for the application as follows.

  • The CDKToolkit stack defines the deployment AWS Identity and Access Management role and policy for AWS CloudFormation, along with other supporting roles and policies for the AWS CDK action. The stack also defines the Amazon S3 bucket used for staging assets and the AWS KMS key used to encrypt it.

  • The AppStack stack defines the backend infrastructure for the application, including a DynamoDB instance, an AWS Lambda function for serverless compute, and an API Gateway endpoint.

  • The WebStack stack defines the frontend infrastructure for the application, including an Amazon CloudFront distribution and hosting bucket.

For expanded details about the resources that will be created in your account as part of this tutorial, see Reference.

Note

The resources and samples included in a project depend on which blueprint you select. Amazon CodeCatalyst offers several project blueprints that define resources related to their defined language or framework. To learn more about blueprints, see Project blueprint reference.

Prerequisites

To create a modern application project in this tutorial, you must have completed the tasks in Setting up CodeCatalyst as follows:

• Have an AWS Builder ID for signing in to CodeCatalyst.

• Belong to a space and have the Space administrator role assigned to you in that space. For more information, see Creating a space in CodeCatalyst, Viewing members in a space, and Space administrator role.

• Have an AWS account associated with your space and have the IAM role you created during sign-up. For example, during sign-up, you have the option to choose to create a service role with a role policy called the CodeCatalystPreviewDevelopmentAdministrator role policy. The role will have a name CodeCatalystPreviewDevelopmentAdministrator with a unique identifier appended. For more information about the role and role policy, see Understanding the CodeCatalystPreviewDevelopmentAdministrator service role. For the steps to create the role, see Creating the CodeCatalystPreviewDevelopmentAdministrator role for your account and space.

Step 1: Create the Modern three-tier web application project

Once created, your project is where you will create and test code, coordinate development tasks, and view project metrics. Your project also contains your development tools and resources.

In this tutorial, you will use the Modern three-tier web application blueprint to create an interactive application. The workflow that is created and run automatically as part of your project will build and deploy the application. The workflow only runs successfully after all roles and account information is configured for your space. After the workflow has run successfully, you can visit the endpoint URL to see the application.

To create a project with a blueprint

1. In the CodeCatalyst console, navigate to the space where you want to create a project.

2. Choose the Projects tab. Choose Create project.

3. On the Create project page, choose Start with a blueprint.

4. Choose the Modern three-tier web application blueprint, and then choose Next. You can also search on "modern" to find the blueprint more quickly.

5. As you configure your selections, you can preview the project configuration under Generate project preview. Choose View code for a preview of the project repository or repositories and the sample application code that will be generated in the project source. Choose View workflow to preview the definition file for your CI/CD workflow. When you choose the preview, the preview page will dynamically update to show definition files with updates based on your selections.

6. In Name your project, enter the name that you want to assign to your project and its associated resource names. For example, MyExampleProject.

   Note

   The name must be unique in your space. If MyExampleProject is already being used, you can enter a different project name.

7. In Account, choose the account you added during sign-up to associate it with your space. The field for the role displays.

8. In Deployment Role, choose the role that you created and added to your account during sign-up. For example, choose CodeCatalystPreviewDevelopmentAdministrator.

   If there are no roles available to choose, then you must add the IAM role. To add the role, choose Add IAM role to add the role to the account in AWS. For more information about adding IAM roles, see Working with AWS accounts in Amazon CodeCatalyst.

9. In Compute platform, choose Lambda.

10. In Region, choose the AWS Region where you want to create resources for deployments.

11. In Application name, leave the default.

12. Choose Create project.

The project workflow starts as soon as you create the project. It will take a little time to finish building and deploying the code. In the meantime, go ahead and invite someone else to your project.

Step 2: Invite someone to your project

Now that you've set up your project, invite others to work with you.

To invite someone to your project

1. Navigate to the project to which you want to invite users.

2. In the navigation pane, choose Project settings.

3. On the Members tab, choose Invite new member.

4. Type the email addresses of the people you want to invite as users for your project. You can type multiple email addresses separated by a space or a comma. You can also choose from members of your space who are not members of the project.

5. Choose the role for the user.

   When you have finished adding users, choose Send.

Step 3: Create issues to collaborate on and track work

CodeCatalyst helps you track features, tasks, bugs, and any other work involved in your project with issues. You can create issues to track needed work and ideas. By default, when you create an issue it is added to your backlog. You can move issues to a board where you track work in progress. You can also assign an issue to a specific project member.

To create an issue for a project

1. In the navigation pane, choose Issues.

2. Choose Create issue.

3. In Issue title, provide a name for the issue. Optionally, provide a description of the issue. In this example, use make a change in the src/mysfit_data.json file.

4. Choose the priority, estimate, status, and labels. Under assignee, choose +Add me to assign the issue to yourself.

5. Choose Create issue. The issue is now visible on the board. Choose the card to move the issue to the In progress column.

For more information, see Issues in CodeCatalyst.

Step 4: View your source repository

Your project comes with a source repository that contains files to define and support your application or service. The contents of the source repository include the following.

1. The .codecatalyst directory contains the YAML workflow configuration file for each workflow included in the blueprint. Configuration files define the workflows that run when you make a code change and are stored in your source repository.

2. The cdkStacks directory contains the AWS CDK stack files that define the infrastructure in the cloud.

3. The src directory contains the application source code. This includes the CDK assets folder, which contains sample code and other assets for generating the application each time you build.

4. The tests directory contains files for the integ and unit tests that are run as part of the automated CI/CD workflow that runs when you build and test your application.

5. The web directory contains the frontend source code. Other files include project files such as the package.json file that contains important metadata about your project, the index.html page for the website, and the Dockerfile for the container. Other files are used for app generation, such as .eslintrc.fjs and tsconfig.json. This directory also includes the README.md file with configuration information for the project.

To navigate to the source repositories for a project

1. Navigate to your project, and do one of the following:

   • On the summary page for your project, choose the repository you want from the list, and then choose View repository.

   • In the navigation pane, choose Code, and then choose Source repositories to view. In Source repositories, choose the name of the repository from the list. You can filter the list of repositories by typing part of the repository name in the filter bar.

2. On the main page of the repository, view the contents of the repository. By default, the contents for the default branch are shown. You can change the view by choosing a different branch from the drop-down list.

Step 5: Create a Dev Environment with a test branch and make a quick code change

You can quickly work on the code in your source repository by creating a Dev Environment. For this tutorial, we recommend that you create a Dev Environment using AWS Cloud9, and choose the option to create a branch from the main branch when creating the Dev Environment. We use the name test for this branch, but you can enter a different branch name if you prefer. In a later step, you will use the Dev Environment to make a code change and create a pull request.

To create a Dev Environment with a new branch

1. Open the CodeCatalyst console at https://codecatalyst.aws/.

2. Navigate to the project where you want to create a Dev Environment.

3. In the navigation pane, choose Code, choose Source repositories, and choose the repository for which you want to create a Dev Environment.

4. Choose Create Dev Environment.

5. Choose a supported IDE from the drop-down menu. See Supported integrated development environments for Dev Environments for more information.

6. Choose Clone a repository.

7. Choose the repository to clone, choose Work in new branch, enter a branch name into the Branch name field, and choose a branch off of which to create the new branch from the Create branch from drop-down menu.

8. Optionally, add an alias for the Dev Environment.

9. Optionally, choose the Dev Environment configuration edit button to edit the Dev Environment's compute, storage, or timeout configuration.

10. Choose Create. While your Dev Environment is being created, the Dev Environment status column will display Starting, and the status column will display Running once the Dev Environment has been created. A new tab will open with your Dev Environment in the IDE of your choice. You can edit code and commit and push your changes.

In this section, you will work with your generated sample application in CodeCatalyst by making changes to the code with pull requests that are automatically built and deployed to resources in the connected AWS account when the pull request is merged.

To make a change in your src/mysfit_data.json file

1. Navigate to your project Dev Environment. In AWS Cloud9, expand the side navigation menu to browse the files. Expand src and open src/mysfit_data.json.

2. In the file, change the value for the "Age": field from 6 to 12. Your line should look like the following:

       {
           "Age": 12,
           "Description": "Twilight's personality sparkles like the night sky and is looking for a forever home with a Greek hero or God. While on the smaller side at 14 hands, he is quite adept at accepting riders and can fly to 15,000 feet. Twilight needs a large area to run around in and will need to be registered with the FAA if you plan to fly him above 500 feet. His favorite activities include playing with chimeras, going on epic adventures into battle, and playing with a large inflatable ball around the paddock. If you bring him home, he'll quickly become your favorite little Pegasus.",
           "GoodEvil": "Good",
           "LawChaos": "Lawful",
           "Name": "Twilight Glitter",
           "ProfileImageUri": "https://www.mythicalmysfits.com/images/pegasus_hover.png",
           "Species": "Pegasus",
           "ThumbImageUri": "https://www.mythicalmysfits.com/images/pegasus_thumb.png"
       },

3. Save the file and, in the terminal, commit and push your changes with the git commit and git push commands.

   git commit -am "Making an example change"
   git push

Step 6: View the workflow that builds the modern application

After creating the modern application project, CodeCatalyst generates several resources on your behalf, including a workflow. A workflow is an automated procedure defined in a .yaml file that describes how to build, test, and deploy your code.

In this tutorial, CodeCatalyst created a workflow and started it automatically when you created your project. (The workflow might still be running depending on how long ago you created your project.) Use the following procedures to check on the workflow's progress, review the generated logs and test reports, and finally, navigate to the URL of the deployed application.

To check on the workflow progress

1. In the navigation pane, choose CI/CD, and then choose Workflows.

2. Choose ApplicationDeploymentPipeline. This is the workflow that the CodeCatalyst blueprint generated and started when you created your project.

   A workflow diagram appears. The diagram shows several blocks, each one representing a task or action. These blocks are arranged vertically, with the blocks at the top running before the ones below. The blocks are:

   • WorkflowSource – This block represents your source repository. It shows the ID of the commit that automatically started the workflow run. It also shows the source repository (mysfits<unique-ID>) and branch (main) to which the commit was pushed. CodeCatalyst generated this commit when you created your project.

   • Build – This block represents a grouping of two actions: cdk_bootstrap and build_backend. These actions must both complete successfully for the next action to start.

   • cdk_bootstrap – This block represents an action that generates the cloud infrastructure that will host application deployments. The action is able to access AWS using the CodeCatalystPreviewDevelopmentAdministrator role you created earlier.

   • build_backend – This block represents an action that builds the application's backend components into AWS.

   • Deploy_Backend – This block represents an action that deploys the application's backend components.

   • Tests – This block represents a grouping of two test actions, described in the following bullets.

   • integration_tests – This block represents an action that runs tests on the application components.

   • build_and_test_frontend – This block represents an action that builds the application's frontend components into AWS.

   • Deploy_Frontend – This block represents an action that deploys the application's frontend components.

3. Choose YAML to view the workflow definition file. The file has the following noteworthy sections:

   • A Triggers section, at the top. This section indicates that the workflow must start whenever code is pushed to the source repository's main branch.

   • An Actions section, under Triggers. This section defines the actions, such as the cdk_bootstrap action, that you saw in the workflow diagram.

4. Choose Visual and choose any action in the workflow diagram.

5. Choose the Configuration tab to see the configuration settings for the action. Each configuration setting has a matching property in the workflow definition file.

6. Leave the console open and go to the next procedure.

To review the build logs and test reports

1. Choose the Latest state tab.

2. In the workflow diagram, choose the deploy_frontend action.

3. Wait for the action to finish. Watch for the "in-progress" icon ( ) to change to a "success" icon ( ).

   Tip

   The build takes several minutes to complete. While you wait, consider working on another part of this tutorial.

4. Choose your run, and then choose the Visual tab.

5. Choose the build_frontend action. In Logs, expand the cd web && npm install and npm run build-only sections to view the log messages for these steps. You can see messages related to the creation of the frontend application.

6. Choose the deploy_frontend action. In Logs, expand the deploy_frontend section to view the log messages for these steps. You can see messages related to the creation of the frontend stacks.

7. Choose the Reports tab for your workflow, and then choose the AutoDiscovered-coverage.xml report. CodeCatalyst displays the associated report on a separate page. The report shows the code coverage tests that were run, and indicates the proportion of lines of code that were successfully validated by testing, such as 80%.

   For more information about test reports, see Testing using workflows in CodeCatalyst.

   Tip

   You can also view your test reports by choosing Reports in the navigation pane.

8. Leave the CodeCatalyst console open, and go to the next procedure.

To confirm that the modern application was deployed successfully

1. Return to the ApplicationDeploymentPipeline workflow, and choose the Deploy_Frontend action.

2. Choose the Variables tab.

3. Copy the endpointUrl value into another browser tab.

   A website appears with the home page opened to the list of Mysfits you can adopt.

4. To search for the pegasus Mysfit named Twilight Glitter, choose Good and Lawful. Note the value for the age. You will make a code change to update the age.

Step 7: Ask others to review your changes

Now that you have changes in a branch named test, you can ask others to review them by creating a pull request. Perform the following steps to create a pull request to compare the changes in the test branch with the main branch.

To create a pull request

1. Navigate to your project.

2. Do one of the following:

   • In the navigation pane, choose Pull requests, and then choose Create pull request.

   • On the repository home page, choose Actions, and then choose Create pull request.

   • On the project page, choose Create pull request.

3. In Source repository, make sure that the specified source repository is the one that contains the committed code. This option only appears if you did not create the pull request from the repository's main page.

4. In Source branch, choose the branch that contains the committed code.

5. In Destination branch, choose the branch to merge the code into after it is reviewed.

6. In Pull request title, enter a title that helps other users understand what needs to be reviewed and why.

7. (Optional) In Pull request description, provide information such as a link to issues or a description of your changes.

8. (Optional) In Issues, choose Link issues, and then either choose an issue from the list or enter its ID. To unlink an issue, choose the unlink icon.

9. (Optional) In Required reviewers, choose Add required reviewers. Choose from the list of project members to add them. Required reviewers must approve the changes before the pull request can be merged into the destination branch.

   Note

   You cannot add a reviewer as both a required reviewer and an optional reviewer. You cannot add yourself as a reviewer.

10. (Optional) In Optional reviewers, choose Add optional reviewers. Choose from the list of project members to add them. Optional reviewers do not have to approve the changes as a requirement before the pull request can be merged into the destination branch.

11. Review the differences between the branches. The difference displayed in a pull request is the changes between the revision in the source branch and the merge base, which is the head commit of the destination branch at the time the pull request was created. If no changes display, the branches might be identical, or you might have chosen the same branch for both the source and the destination.

12. When you are satisfied that the pull request contains the code and changes you want reviewed, choose Create.

    Note

    After you create the pull request, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resources, such as files, by using the @ sign followed by the name of the file.

When you create the pull request, the OnPullRequest workflow starts. While your reviewers are approving your code change, you can observe the results by choosing the workflow and viewing the test output.

Once you've had the change reviewed, you can merge the code. Merging the code to the default branch will automatically start the workflow that will build and deploy your changes.

To merge a pull request from the CodeCatalyst console

1. Navigate to your modern application project.

2. On the project page, under Open pull requests, choose the pull request you want to merge. If you do not see the pull request, choose View all pull requests and then choose it from the list. Choose Merge.

   Note

   Depending on your screen size and browser, the buttons to approve or merge a pull request might be hidden behind the Additional info information bar. To view these options, collapse the information bar.

3. Choose from the available merge strategies for the pull request. Optionally select or deselect the option to delete the source branch after merging the pull request, and then choose Merge.

   Note

   If the Merge button is not active, or you see the Not mergeable label, either one or more required reviewers have not yet approved the pull request, or the pull request cannot be merged in the CodeCatalyst console. A reviewer who has not approved a pull request is indicated by a clock icon in the Additional info information bar. If all required reviewers have approved the pull request but the Merge button is still not active, you might have a merge conflict. You can resolve merge conflicts for the destination branch in the CodeCatalyst console and then merge the pull request, or you can resolve conflicts and merge locally, and then push the commit that contains the merge to CodeCatalyst. For more information, see Merging a pull request (Git) and your Git documentation.

4. In Merge pull request, review the summary information and the merge strategy that will be used. Choose Merge to merge the pull request.

Once you've merged the changes from the test branch into the main branch, the change automatically starts the ApplicationDeploymentPipeline workflow that builds and deploys your change.

To see the merged commit run through the ApplicationDeploymentPipeline workflow

1. In the navigation pane, choose CI/CD, and then choose Workflows.

2. In Workflows, in ApplicationDeploymentPipeline, expand Show most recent runs. You can see the workflow run started by the merge commit. Optionally choose it to watch the run progress.

   

3. When the run completes, reload the URL you visited earlier. View the pegasus to verify that the age changed.

   

Step 8: Close the issue

When an issue is resolved, it can be closed on the CodeCatalyst console.

To close an issue for a project

1. Navigate to your project.

2. In the navigation pane, choose Issues.

3. Choose the issue that you want to close.

4. Choose Done from the Status drop-down menu.

For more information, see Issues in CodeCatalyst.

Step 9: Clean up resources

Clean up in CodeCatalyst and AWS to remove traces of this tutorial from your environment.

You can choose to keep using the project you used for this tutorial, or you can delete the project and its associated resources.

Note

Deleting this project will delete all repositories, issues, and artifacts in the project for all members.

To delete a project

1. Navigate to your project, and then choose Project settings.

2. Choose the General tab.

3. Under the project name, choose Delete.

To delete resource stacks in AWS CloudFormation

1. Sign in to the AWS Management Console with the same account that you added to your space, and then choose AWS CloudFormation.

2. Choose the stack to delete, and then choose Delete. To confirm, choose Delete stack.

3. Repeat these steps for each stack.

Reference

As a reference, you can learn more about the AWS resources that are created as part of this tutorial.

Resources for this project will be created by the automated resources generated in the stacks created for your project as follows:

• The cdk_bootstrap action generates the CDKToolkit stack in the associated account.

  Deploying stacks with the AWS CDK requires dedicated Amazon S3 buckets and other containers to be available to AWS CloudFormation during deployment. The cdk_bootstrap action provisions these resources for the AWS CDK.

  Note

  Note that the AWS CDK stack is not torn down and recreated for each deployment. This is a stack that is initiated in each account to support the AWS CDK.

  The CDKToolkit stack defines the following resources for the Modern three-tier web application blueprint.

  • An Amazon S3 staging bucket, bucket policy, and the AWS KMS key used to encrypt the bucket.

  • An IAM deployment role for the deploy action.

  • AWS IAM roles and policies in support of the resources in the stack

• The deploy_backend action generates the mysfits<ID>AppStack stack. The mysfits<ID>AppStack stack defines the following resources for the Modern three-tier web application blueprint.

  • An Amazon API Gateway endpoint

  • AWS IAM roles and policies in support of the resources in the stack

  • An AWS Lambda function and layer provides the serverless compute platform for the modern application

  • An IAM policy and role for the bucket deployment and Lambda function

• The deploy_frontend action generates the mysfits<ID>WebStack stack. The mysfits<ID>WebStack stack defines the following resources for the Modern three-tier web application blueprint.

  • AWS IAM roles and policies in support of the resources in the stack

  • an Amazon CloudFront distribution and access identity

  • an AWS CDK custom bucket deployment

See also

See the following for more information about the resources that are created as part of this tutorial.

• Amazon S3 - A resource to host your frontend assets on an object storage service offering industry-leading scalability, data high availability, security, and performance. For more information, see Amazon S3 User Guide.

• Amazon CloudFront - A resource for speeding up distribution of the application's frontend content such as .html, .css, .js, and image files to your users. For more information, see Amazon CloudFront Developer Guide.

• Amazon API Gateway - A resource for creating, publishing, maintaining, monitoring, and securing REST, HTTP, and WebSocket APIs at any scale For more information, see API Gateway Developer Guide.

• AWS Cloud Development Kit (AWS CDK) - The AWS CDK includes the CDK Toolkit, a command line tool for working with your AWS CDK apps and stacks. The Toolkit converts AWS CDK stacks to AWS CloudFormation templates and related assets, and then deploys your stacks to an AWS account. For more information, see AWS Cloud Development Kit (AWS CDK) Developer Guide.

• AWS Lambda - A resource to invoke your code on a high availability compute infrastructure without provisioning or managing servers. For more information, see AWS Lambda Developer Guide.

• AWS IAM - A resource for securely controlled access to AWS and its resources. For more information, see IAM User Guide.