Tuesday, 7 May, 2024 UTC
Summary
Amazon CodeCatalyst is a unified software development and delivery service, enables software development teams to quickly and easily plan, develop, collaborate on, build, and deliver applications on AWS. Amazon CodeCatalyst provides actions, a collection of pre-built building pieces that are simple to integrate. Actions meet the demands to increase developer productivity and optimize development by automating repetitive operations and simplifying complex workflows. A Workflow is made up of Actions that build, test, and deploy your code as part of a continuous integration and continuous delivery system.
Introduction This blog talks about how to host an existing single-page application (SPA) on AWS. If developing a new SPA from start, leverage the Single-page application blueprint. Blueprints contain sample code and create project resources for you, and the SPA blueprint will use React, Vue, or Angular frameworks and deploy it to AWS Amplify Hosting. First, you will import an existing SPA from GitHub. Then, you’ll explore creating a workflow which consists of actions to test, build, and deploy your SPA using AWS Amplify Hosting. In addition to the AWS Amplify action, CodeCatalyst also offers a Deploy to Amazon CloudFront and Amazon Simple Storage Service (Amazon S3) action that can deploy the SPA.
Figure 1 – Architecture diagram for hosting the SPA.
Pre-requisites
- A CodeCatalyst space and associated AWS account.
- A CodeCatalyst environmentconnected to the associated AWS account.
- A forked GitHub repository that will be used as the source code, it contains the contents of a front-end React static site.
Connect GitHub account to CodeCatalyst, then go to your space by clicking your space name in CodeCatalyst console. From your space, click Create Project. You will have three options available: From Blueprint, Bring your Own Code, and Start from Scratch. Upon selecting Bring your own code, you will see the option to link your GitHub repository. For the purpose of the blog, I have already linked my account and gave permissions to the Rent-A-Room repository.
Enter the project name, and click Create Project. As part of this walkthrough, I will name the project “StaticSite”. Name your project as you would like; however, I will be referencing the project as StaticSite in the blog.
Figure 2 – Create Project screen
Create a workflow
A workflow contains sequenced, automated actions that are a component of CI/CD system and is made up of a Name, SchemaVersion, Triggers, and Actions and can be assembled using YAML or a visual editor. Furthermore, there are two kinds of triggers to a workflow that come from monitoring a list of repository branches that the user has chosen: push and pull requests. All actions are essentially code that compile and run on a user specified compute type in an AWS managed environment. Actions which require interaction with AWS resources like creation, modification, or deletion occur in the customer’s AWS account, such as the Amplify Hosting action.
Navigate to the Amazon CodeCatalyst console interface and ensure you are in the correct space and project.
While you are on the project page, “StaticSite” or what you named your project, click the drop-down button next to CI/CD in the navigation plane on the left side of the page. Once the CI/CD section is expanded, click on Workflows.
From the Workflows page, click the Create workflow button. A pop-up form will appear on the same page. Ensure the repository linked to the project and “main” branch are selected, then click the Create button. This configuration is the Source of the workflow and is regarded to as the “WorkflowSource.”
On the newly created workflow page with YAML and Visual editor, ensure YAML is selected and modify line 1 with a workflow name that you prefer. Please note that I will be using the YAML editor throughout this blog; however, you can use the visual editor to accomplish the same outcome through the options. Changes made in one method reflect on the other.
Add actions to the workflow
Actions can be combined together with other actions and customized to create an automated workflow that is suited to the requirements of a particular project. Some actions available today are pushing assets to Amazon S3, rendering an Amazon ECS task, invoking an Amazon Lambda function, deploying applications using AWS CDK. For this project, you will use three actions: Build, Test, and Deploy to AWS Amplify Hosting.
Build Action
The Build action builds artifacts and runs unit tests in a selected compute type. To compose the workflow with Build action, click the +Actions button to view a collection of actions that can be added onto the workflow. Search for the Build action and click the + button
In the YAML editor, you will notice the build action is added under Actions. Rename the action by modifying the selector string for the action. Identifiers for actions are unique identification for the action and are not meant to be changed. Modify the Inputs, Outputs, Configuration, and Compute as it fits your application requirements. If you are doing this for the first time, it is strongly recommended to use the visual editor. Inputs are source repository files of the project or artifacts generated by another action. Outputs contain artifacts, which is the output of a workflow action that consists of a folder or archive of files to share between actions for a connected and automated workflow. Lastly, CodeCatalyst supports two compute types, AWS Lambda and Amazon Elastic Cloud Compute (EC2) to run the corresponding action.
As for the static site project, you should have the following action configuration for the Build action.
Name: OnPushBuildTestDeployWebsite SchemaVersion: "1.0" # Optional - Set automatic triggers. Triggers: - Type: Push Branches: - main # Required - Define action configurations. Actions: Build: # Identifies the action. Do not modify this value. Identifier: aws/[email protected] # Specifies the source and/or artifacts to pass to the action as input. Inputs: # Optional Sources: - WorkflowSource # This specifies that the action requires this Workflow as a source Outputs: Artifacts: - Name: build Files: - build/**/* # Defines the action's properties. Configuration: # Required - Steps are sequential instructions that run shell commands Steps: - Run: npm install #install all dependencies from packagae.json - Run: npm run build #builds the app for production to the build folder Compute: Type: Lambda
If you notice any errors on the screen, click the Validate button to remove the error. Click Commit to update the workflow in your source repository. On the in-page pop-up, enter a commit message and click Commit.
View the run and ensure it runs successfully before moving onto the next step
Figure 3 – Workflow run of source and build actions
Test Action
Use Test action to run integration and system tests against application or artifacts. Click Edit workflow to modify the workflow and add actions, A new page will load with the workflow to edit it. Click the +Actions button to view a collection of actions that can be added onto the workflow.
Search for the Test action and click the + button. Modify the Inputs, Outputs, and Configuration in YAML as it fits your application requirements.
In the Build action, outputs are used to collect the artifacts generated through the build job; however, for the Test action, the reports will be captured that the test job will generate.
When auto-discovery is enabled under Outputs for the Test action, CodeCatalyst searches the inputs and all files generated by the action to look for test, code coverage, software composition analysis (SCA), and static analysis (SA) reports. These reports can be viewed and manipulated in CodeCatalyst Reports.
For this static site project, a simple “npm run test” will do the trick! Use “IncludePaths” to specify the files and file paths you want CodeCatalyst to include when searching for reports.
Test: # Identifies the action. Do not modify this value. Identifier: aws/[email protected] # Specifies the source and/or artifacts to pass to the action as input. Inputs: # Optional Sources: - WorkflowSource # This specifies that the action requires this Workflow as a source Outputs: # Optional; Automatically discover reports for popular test frameworks AutoDiscoverReports: Enabled: true # Use as prefix for the report files ReportNamePrefix: Test IncludePaths: - coverage/** - reports/** # Defines the action's properties. Configuration: # Required - Steps are sequential instructions that run shell commands Steps: # see info link in shell commands section for more details - Run: npm install - Run: npm test --coverage --watchAll=false --testResultsProcessor="jest-junit" Compute: Type: Lambda
Commit the workflow changes with a commit message by clicking the Commit button. View the run and ensure all actions run successfully before moving onto the next step.
I won’t be diving into the reports generated and code quality, learn how to maintain code quality with Amazon CodeCatalyst reports.
View the run and ensure it runs successfully before moving onto the next step.
Figure 4 – Workflow run with added Test action
Deploy to AWS Amplify Hosting Action
The Deploy to AWS Amplify Hosting action deploys an application to AWS Amplify Hosting. After developing a SPA with building and testing configured, you can host your application using AWS Amplify Hosting with continuous deployment. It is worth noting that AWS Amplify leverages CloudFront Global Edge Network to distribute your application globally.
To compose the workflow with the Deploy to AWS Amplify Hosting Action, you must ensure that you have created an Environment, which is a way to organize a collection of your deployment’s targets, alarms, and rule. As part of this blog, I assume that you have a pre-configured environment on Amazon CodeCatalyst.
Lastly, you will add a new action from the actions catalog to host the frontend application on AWS Amplify. In the Amazon CodeCatalyst workflow, click Actions then edit on the “OnPushBuildTestDeployWebsite” workflow, then add Deploy to AWS Amplify Hosting action by clicking the +Action button and searching for it within the Actions catalog.
Modify the YAML with the following:
- Environment name, AWS account connection name, and IAM Role name associated with the connection. This is required for the action.
- Note that the IAM Role should have necessary permissions to interact with AWS Amplify and CloudFormation, consider attaching the AdministratorAccess-Amplify managed policy to the IAM Role. CloudFormation permissions required are CreateStack, DescribeStackResources, and DescribeStacks. A custom trust policy is also required to allow principals of CodeCatalyst to AssumeRole. Please view the documentation of the action by clicking the name of the action in the actions catalog. It includes the exact IAM policies required and more information about the action.
- Artifacts as an input, in this case, the artifact generated by the build action
- Configuration parameters of AppStackName, AppId, AmplifyBranchName, Wait, CreateBranch, Region, and Path. The configuration parameters tell the action what to name your Amazon CloudFormation Stack and how to host your Amplify App. These parameters are optional and not required. If not configured, strings may be generated for certain parameters or defaults chosen.
The AppStackName is a unique stack name for new Amplify app. Either AppStackName or AppId should be entered, not both. AppId is unique ID for an existing Amplify app. AmplifyBranchName is the name for the branch that is part of an Amplify app, and you can use ${WorkflowSource.BranchName} to reference the branch name of the source associated with the workflow. Wait parameter will wait for your Amplify app to finish deploying before continuing to the next action or be marked as complete. Region is the AWS region where you would like to deploy your app. Path is the path to the folder containing the files that should be bundled. If omitted, CodeCatalyst will bundle the entire source.
- DependsOn parameter to ensure that the Amplify app only deploys once artifacts are generated and testing is successfully completed
DeploytoAWSAmplifyHosting: # Identifies the action. Do not modify this value. Identifier: codecatalyst-labs/[email protected] # Required; You can use an environment, AWS account connection, and role to access AWS resources. Environment: Connections: - Role: CodeCatalystWorkflowDevelopmentRole-WebDevTeam Name: DevEnvironment Name: development # Specifies the source and/or artifacts to pass to the action as input. Inputs: Artifacts: - build Compute: Type: EC2 # Required paramters for the action to create Amplify App Configuration: Wait: true AWSRegion: us-east-1 AppStackName: RentARoom CreateBranch: true AmplifyBranchName: ${WorkflowSource.BranchName} Path: build #To only run this action if the build and test stage are successful DependsOn: - Build - Test
Click Commit to update the workflow in your source repository.
You should now have all actions running successfully.
Figure 5 – Workflow run with added Amplify Hosting action
The “DeploytoAWSAmplifyHosting” action, upon a successful run, will have a hyperlink as View app. By clicking this link, you will be redirected to your new SPA hosted by AWS Amplify Hosting.
Figure 6 – SPA publicly routable in a browser
Clean Up If you have been following along with building this workflow, you should delete the resources you deployed so you do not continue to incur charges. First, delete the stack that has been deployed from the AWS CloudFormation console in the AWS account you associated when you launched the blueprint. The stack will have the name RentARoom, unless you named your stack differently in the configurations of the “DeploytoAWSAmplifyHosting” action. Second, delete the project from CodeCatalyst by navigating to Project settings and clicking the Delete project button.
Conclusion In this blog, you created a project and connected your existing GitHub repository of a SPA. Next, you leveraged Workflows, an automated procedure as part of a CI/CD system that contains a series of actions. Finally, you selected actions curated to build, test, and deploy your application to AWS Amplify Hosting. Using these concepts, you can now host your single-page application with Amazon CodeCatalyst. Learn more about Amazon CodeCatalyst and get started today!
Yong Zhang
Yong Zhang is a Senior Technical Account Manager at Amazon Web Services. He helps customers in the Financial Services industry to design, build and operate their workloads in AWS. He is passionate about software architecture design and DevOps. Outside work, he enjoys travel and sports.
Omar Faruk
Omar Faruk is a Partner Solutions Architect at Amazon Web Services. He helps long-tail technology and consulting partners to design, build and operate their and shared customers’ workloads in AWS. He is passionate about serverless and DevOps. Outside work, he enjoys family time and travel.