'Bob's Used Books' Sample Application

Overview

Bob's Used Books is a sample application built on ASP.NET Core 6.0 that aims to represent a simple, real-world application. It is a monolithic n-tier application with an ASP.NET Core MVC front end and a MySQL database backend.

The MVC application contains a customer portal and an administration portal. The customer portal enables customers to search for books, select and add them to a shopping cart, and work through a simulated check-out process. Customers can also offer their own books for resale through the website.

The administration portal is used by site administrators to maintain inventory, process customer orders, and perform other administrative tasks.

In its current state the application illustrates an in-progress "lift and shift" from on-premises to AWS, with partial modernization to use some AWS services. As the sample application progresses over time we have plans to add further modernization examples including (but not limited to) database modernization and refactoring to microservices.

Prerequisites

To run and debug the application locally you need the following:

• A Windows-based development environment
• An IDE that supports .NET 6.0: Visual Studio 2022 or JetBrains Rider

To deploy the application to AWS you need the following:

• An AWS IAM User with an attached AdministratorAccess policy
• The AWS Cloud Development Kit (CDK)

Getting started

Clone the repository or download the source code and open the solution in your preferred IDE. Set Bookstore.Web as the startup project.

Make sure the Local profile is selected, then press F5 to debug the application.

When running under the local profile the application will use a MySQL instance for database support with the connection string defined in appSettings.Development.json. User authentication is simulated. Clicking the Log in option results in a transition to an authenticated state, without prompting for username or password, or user sign-up. This enables you to test the work processes in the admin portal, and customer features such as shopping cart, without needing to provision any cloud resources. Facades within the application abstract away potential use of AWS services such as Amazon S3 to the local file system.

Launch profiles, contained in the application's launchSettings.json file, are used to determine whether you are running the application fully local (no AWS resources) or local with AWS resources. The launch profile that represents a fully local run, without using any AWS services, is called the Local profile. The second profile, in which the application can be run locally but also make use of some AWS services, is called the Integrated profile. See the Deployment section for details on launching the application with the Integrated profile.

Deployment

You can run and debug the web application from the repository codebase without needing to create any AWS resources or deploy the application. Optionally, you can also run the web application locally, in a state representing the in-progress lift and shift operation, where a small number of AWS services are used to provide application features such as:

• An object store holding cover images for the store's books, using a private Amazon S3 bucket.
• An Amazon CloudFront distribution, through which the objects (images) in the bucket are accessed, enabling the bucket to remain private.
• User authentication, for both bookstore staff and customers, using Amazon Cognito user pools.
• Secrets management for the database credentials using Amazon Secrets Manager.
• Application configuration parameters retrieved at runtime from AWS Systems Manager Parameter Store.

To run the application using the Integrated profile a minimal set of AWS resources need to be provisioned. This is achieved using Infrastructure as Code (IaC) with an AWS Cloud Development Kit (CDK) application contained in the Bookstore.Cdk project. The Bookstore application can be deployed to AWS via the CDK's command-line tooling.

Running and debugging with the Integrated launch profile

NOTE: Ensure your development environment meets the Prerequisites before attempting to deploy the application

1. Open a command-line shell and navigate to the application solution folder (the folder that contains BobsBookstore.sln).

2. Bootstrap your AWS environment for the AWS CDK by running the command cdk bootstrap

3. In the command-line shell run the command cdk deploy BobsBookstoreCore --require-approval "never". This will take about 5 minutes to complete.

   NOTE: the sample CDK command above assumes that your AWS credential profile is named default. If you do not have a credential profile with that name, or wish to use an alternate credential profile, add the --profile parameter followed by the name of the credential profile. For example, cdk deploy BobsBookstoreCore --profile my-profile. Note that the selected profile should be configured to set the target region. See Configuration and credential file settings for more details. An example of a credential profile containing region configuration is shown below.

   [my-profile]
   aws_access_key_id=AKIAIOSFODNN7EXAMPLE
   aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   region=us-west-2
   

   

4. Once the CDK deployment has completed open the appsettings.Test.json file in the Bookstore.Web project and set a credential profile and region. An example of the required settings is shown below.

   

   NOTE: These settings are needed as the application will be calling AWS service APIs to access the resources you just provisioned using the CDK. The Region property should match the region you told the CDK to deploy to, or us-west-2 if you accepted the default built into the CDK application. The Profile property value should point to credentials that belong to the same account used with the CDK deployment.

5. In your preferred IDE select the Integrated launch profile and press F5.

   

You are now debugging the Bookstore application locally, however the application is interacting with the following AWS services:

• An object store holding cover images for the store's books, using a private Amazon S3 bucket.
• An Amazon CloudFront distribution, through which the objects (images) in the bucket are accessed, enabling the bucket to remain private.
• User authentication, for both bookstore staff and customers, using Amazon Cognito user pools.
• Secrets management for the database credentials using Amazon Secrets Manager.
• Application configuration parameters retrieved at runtime from AWS Systems Manager Parameter Store.

NOTE: The first time you launch the application with the Integrated profile or via a full deployment (see below for a full deployment) you will be prompted to sign in and update the admin user password. See the User Authentication section for details.

Perform a full deployment

In addition to the AWS resources that are created and used by the Integrated launch, a full deployment deploys the application to an Amazon EC2 instance and provisions an Amazon RDS for MySQL database.

NOTE: Ensure your development environment meets the Prerequisites before attempting to deploy the application

1. Open a command-line shell and navigate to the application solution folder (the folder that contains BobsBookstore.sln).

2. If you haven't done so already, Bootstrap your AWS environment for the AWS CDK by running the command cdk bootstrap

3. In the command-line shell run the command dotnet publish app/Bookstore.Web/Bookstore.Web.csproj -p:PublishProfile=FolderProfile -c Release

4. In the command-line shell run the command cdk deploy BobsBookstoreEC2 --require-approval "never". This will take about 25 minutes to complete.

5. To run your deployed application, copy the _BobsBookstoreEC2.EC2Url output and paste it into a browser.

NOTE: The application uses a self-signed certificate when deployed to EC2. The first time you navigate to the application your browser will warn you about a potential security risk. This is expected behavior and is due to the self-signed certificate not being recognized by your browser.

NOTE: The first time you launch the application with the Integrated profile or via a full deployment (see below for a full deployment) you will be prompted to sign in and update the admin user password. See the User Authentication section for details.

User authentication

When the application is launched with the Integrated profile or as a full deployment it uses Amazon Cognito user pools for user authentication and Amazon Cognito user groups for role-based authorization. The first time you login to the application you will be asked to update the admin password.

1. In the application, select Log in from the application toolbar.

   

2. Sign in using admin for the username and P@ssword1 for the password.

   

3. Because you signed in with a temporary password you are prompted to create a new password and to provide some additional details.

   

You are then signed into the application and placed at the customer portal home page. The admin user belongs to the Administrators group which means you can navigate between the admin portal and the customer portal by following the Admin Portal and Customer Portal links in the top-right corner of the page.

NOTE: The application supports self sign up. When users sign up to Bob's Used Books they are granted access to the customer portal, but not to the administrator portal. Administrators cannot be added via self sign up, they must be added directly in the application's Cognito user pool.

Amazon Cloud Development Kit (CDK)

The application uses the AWS Cloud Development Kit (CDK) to provision resources in AWS. The CDK project can create and configure either the minimal cloud resources needed to support the Integrated launch profile of the web application, or a full set of resources that simulate a "production deployment" that includes a Virtual Private Cloud (VPC), a MySQL database in Amazon RDS, application roles, and more.

The CDK project uses Infrastructure as Code (IaC) to define and configure the application's resources. It is a .NET console project, which you can examine by opening the Bookstore.Cdk project. During deployment, the CDK creates AWS CloudFormation Stacks containing the resources defined using C# in the Bookstore.Cdk application. The stacks in the sample application are modular and take advantage of cross-stack references to minimize code duplication and maximize reuse. The following stacks have been defined:

• BobsBookstoreCore - Deploys the minimal resources needed to support the Integrated launch profile
• BobsBookstoreNetwork - Deploys a VPC that is used by the application in a "production" deployment
• BobsBookstoreDatabase - Deploys an RDS for MySQL database that is used by the application in a "production" deployment. This stack depends on resources created in the BobsBookstoreNetwork stack
• BobsBookstoreEC2 - Deploys the application to an EC2 Linux instance. This stack depends on resources created in the BobsBookstoreCore, BobsBookstoreNetwork, and BobsBookstoreDatabase stacks

The BobsBookstoreCore stack is used to deploy the minimal resources needed to support the Integrated launch profile. Use the BobsBookstoreEC2 stack to deploy the resources required to simulate a full "production" deployment to EC2.

NOTE: some of the resources created by the BobsBookstoreCore and BobsBookstoreEC2 stacks will incur charges to your AWS account if you are not able to take advantage of the AWS Free Tier. These resources should be deleted when they are no longer required. See the Deleting the resources section for details.

Deleting the resources

When you have completed working with the sample applications we recommend deleting the resources to avoid possible charges. To do this, either:

• Navigate to the CloudFormation dashboard in the AWS Management Console and delete all BobsBookstore stacks (see list above).

• Or, in a command-line shell, navigate to the solution folder and run the command cdk destroy BobsBookstore*.

NOTE: If you supplied --profile parameter to the CDK when instantiating the stack, be sure to provide the same ones on deletion, otherwise the CDK command will error out complaining that the stack cannot be found.