ContextQMD
Back to Aws Doc Sdk Examples

Track work items in a sample application using Aurora Serverless and Amazon SES built with the SDK for Ruby

ruby/cross_service_examples/item_tracker/README.md

latest6.2 KB
Original Source

Track work items in a sample application using Aurora Serverless and Amazon SES built with the SDK for Ruby

Overview

This example code comprises a "real-world" reference application showcasing an Amazon Aurora Serverless database using the AWS SDK for Ruby.

This code is written to be browsed in an exploratory manner. For a more hands-on experience, you can run the application by invoking this example code using the following instructions.

⚠️ Important

  • Running this code (including tests) might result in charges to your AWS account.
  • We strongly recommend that you grant your code least privilege.
  • This code is not tested in every AWS Region.

About this example code

The code comprises an application designed to manage fictitious work items using three key components.

1. Backend

The centerpiece of this example is an API written exclusively in Ruby. It features the following gems:

  • AWS SDK for Ruby (for communicating with Amazon Aurora)
  • Sinatra (for a lightweight API implementation)
  • Sequel (for Ruby-native modeling of SQL queries)

This Ruby API consists of the following API routes:

methodrouteactionclientfunction
GET/api/itemsList itemsRDSDataServiceexecute_statement(SQL)
POST/api/itemsAdd itemRDSDataServiceexecute_statement(SQL)
PUT/api/items:archiveArchive itemRDSDataServiceexecute_statement(SQL)
GET/api/items/{item_id}Get itemRDSDataServiceexecute_statement(SQL)
POST/api/items:reportCreate reportRDSDataServiceexecute_statement(SQL)

2. Frontend

The frontend code is written in JavaScript and implemented using the React framework. For more information, see the React Elwing Client README.

3. Database

This example relies on a MySQL 5.7 database implemented using Amazon Aurora, a serverless relational database management system (RDBMS). The Aurora DB cluster is deployed using the AWS Cloud Development Kit (AWS CDK). For more information, see the Aurora Serverless App CDK script README.md.

Prerequisites

To explore this example, you must first do the following:

  1. Create an account and configure credentials using instructions in the top-level README.md.
  2. Install Ruby and resolve dependencies using instructions in the Ruby README.md.

Create the resources

Set up the AWS resources needed to run this example as follows:

  1. Create AWS infrastructure using instructions in the Aurora Serverless App README.md.
    • NOTE: Store the following output values in the env/config.yml file: CLUSTER_ARN, SECRET_ARN, and DATABASE.
  2. Populate your database with a table and data using the following commands:
    bash
    cd ruby/cross_service_examples/item-tracker/helpers
ruby create_table.rb # Checks for database and creates a new table.
ruby populate_data.rb # Creates a table with 10 records.
  3. Register your email address with Amazon Simple Email Service (SES) using the instructions in Creating and verifying identities in Amazon SES.
    • NOTE: Use this email for the sender_email and recipient_email fields in your env/config.yml file.

Build the code

To view this example in its entirety, you must do the following:

  1. Start the frontend React application using the following commands:
    bash
     cd resources/clients/elwing # Located within Resources sub-directory.
 npm install # First time only.
 npm start # Launches a browser session on localhost:3000.
  2. Open a second tab in your terminal and run the following command:
    bash
    cd ruby/cross_service_examples/item-tracker
ruby app.rb # Starts REST API listening on port 8080.

Now, visit http://localhost:3000/item_tracker to view your working application.

Test the code

Test this application manually via the frontend or automatically via the RSpec tests.

Manual validation (via frontend React app)

After the app starts, manually validate the following behaviors on the frontend:

  • Filter items by All, Archived, and Active (not archived).
  • Archive an item by choosing the Archive button.
  • Add an item by choosing the Add Item button and submitting the form.
  • Send a report of items by entering a verified email address and choosing Submit.

As you interact with the React app, logs will appear in the command line tab where you started the REST API.

Automated validation (via RSpec tests)

Validate the internal logic within this example by running the following commands:

bash
cd spec
rspec db_wrapper_spec.rb

Delete the resources

To avoid charges, delete all the resources that you created for this tutorial. Follow the instructions in the Destroying resources section of the README for the Aurora Serverless sample application.

Additional resources