@amazon-codecatalyst/blueprints.serverless-tinyurl

About this blueprint:

This blueprint builds a functional tiny URL single-page application with a serverless backend and deploys it into a given AWS account. The repository generated by this blueprint will contain both projects and the CDK stacks that are used to deploy both the frontend and backend.

Architecture overview:

The application architecture uses Amazon CloudFront, AWS Lambda, Amazon API Gateway, Amazon DynamoDB, and Amazon S3.

• AWS API Gateway to provide the REST interface to the user
• Amazon DynamoDB for URL persistence
• AWS Lambda process the API gateway requests for create and retrieve the data from DynamoDB table
• Amazon CloudFront to provide a unified endpoint with origins for both frontend and backend
• Amazon S3 to store the frontend resources and served through CloudFront

The frontend application framework uses ReactJS with TypeScript and uses CloudScape for the user interface.

The build pipeline runs unit and integration tests on the frontend and backend, and produces testing reports. Failed tests will stop the artifacts from publishing. The frontend code is compiled and optimized for production deployment.

The Amazon CloudFront CDN is used to pull both the frontend and backend together under a single logical internet-accessible domain under the AWS account that is connected. Cloudfront provides HTTPS support for the domain as well as forward caching for the front-end.

Configuring the account connection

An AWS account connection is required before deploying this project. An IAM role with below policy statement is required for the blueprint to deploy successfully.

In order to deploy the application successfully, the account should be CDK bootstrapped. Please refer AWS doc on CDK bootstrap for bootstrapping the account. The account should be bootstrapped in the region where the application needs to be deployed.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole",
                "iam:DeleteRole",
                "iam:GetRole",
                "iam:TagRole",
                "iam:CreateRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:PutRolePolicy",
                "s3:*",
                "cloudformation:*",
                "lambda:*",
                "apigateway:*",
                "ssm:*",
                "ecr:SetRepositoryPolicy",
                "ecr:GetLifecyclePolicy",
                "ecr:PutImageScanningConfiguration",
                "ecr:DescribeRepositories",
                "ecr:PutImageTagMutability",
                "ecr:ListTagsForResource",
                "ecr:CreateRepository",
                "ecr:DeleteRepository"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::*:role/cdk-*"
            ]
        }
    ]
}

Note: If you add more resources, you will need to update the policy

IAM role also requires below trust policy.

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Sid": "CodeCatalyst",
          "Effect": "Allow",
          "Principal": {
              "Service": [
                  "codecatalyst-runner.amazonaws.com",
                  "codecatalyst.amazonaws.com"
              ]
          },
          "Action": "sts:AssumeRole"
      }
  ]
}

Project resources

This blueprint will create the Amazon CodeCatalyst Resources and along with a source code Repository for the project. The project contains below modules / files

• .codecatalyst/workflows/build-and-release.yaml: The template that defines the project's workflow

• backend

  • cdk: Java maven module for creating the Application.

  • lambda: Java maven module for the Lambda function used by the Application to create tiny URL and retrieve long URL.

  • pom.xml: Maven configuration for dependency management, plugin management, build and packaging

  • cdk.json: To execute the CDK code

• frontend

  • canary: Canary test script

  • cdk : Typescript package to code the frontend infrastructure

  • src: React components using to power the frontend

  • public: static html resources

Additional resources

See the Amazon CodeCatalyst user guide for additional information on using the features and resources of Amazon CodeCatalyst