An implementation of TodoMVC featuring AWS Serverless Application Model (SAM) and Xilution SaaS.
Clone or download
tbrunia Merge pull request #79 from xilution/greenkeeper/monorepo.enzyme-1.6.0
Update enzyme to the latest version 🚀
Latest commit b73e952 Oct 11, 2018

README.md

xilution-react-todomvc

A Serverless Example of TodoMVC

This is a full-stack example of the ubiquitous TodoMVC app using a serverless computing model. Follow the instructions below to stand up an example of the app for yourself. Within about 1/2 hour you will have a fully functional todo management app running in AWS.

Issues Forks Stars License

Travis Codecov Greenkeeper

Tweet

Is it time to reboot our love affair with servers?

Great For

  • This example is ideally suited for...
    • Digital agencies who want to accelerate client project time lines.
    • Hackathon teams who want a complete full-stack example upon which they can base their projects.
    • Frontend developers with backend responsibilities who just want to code awesome web and mobile apps.
    • Technical leaders who are always on the look out for next big productivity accelerator.
    • Backend developers who want to sharpen their technical skill sets.

Features

xilution-react-todomvc components

Prerequisites

This example was developed on macOS High Sierra using WebStorm. Your experience on other development platforms will vary. If you find inconsistencies with these instructions and develop a solution for your development platform, please share your experience through a pull request.

For Windows users, I recommend using Git Bash for command line steps. Git Bash is included in the Git installation mentioned below. For Mac users, the Terminal application is the best way to go for command line steps.

  1. Create an AWS Account

    • AWS offers a 12 month Free trial.
  2. Create a Xilution Subscriber Account

    • Limited access to Xilution's Beta and Test environments is Free for registered users.
    • When prompted for product selections, choose Elements - Data Accessor and Business Basics - Identity.
  3. Install Git

  4. Install AWS CLI

    1. You'll need python 3 to get access to the latest AWS CLI commands.
  5. Install Node Version Manager (nvm)

  6. Install Yarn

  7. Install ./jq

    • This will quickly become one of your favorite command line utilities. 😎

One Time Set Up

  1. Create an AWS IAM User in your AWS Account

    • It's bad practice to use your AWS root account.
    • I recommend following the console instructions.
    • When you get to the "Set permissions" step, attach an existing policy and choose "AdministratorAccess". You can change the access at anytime. AWS will prompt you when you don't have sufficient access to a resource.
  2. Configure the AWS CLI

    • Remember your region for configuration later.
  3. Open a command line app.

    • Mac: Terminal
    • Windows: Git Bash
  4. Download Project Source Code

    • Some of these steps may be superfluous for experienced developers. For those less experienced coders, I recommend following these steps verbatim.
    1. Run cd ~ to navigate to your home directory.
    2. Run mkdir Developer to create a directory to keep development related things.
    3. Run cd Developer to navigate into the Developer directory.
    4. Run mkdir git to create a directory to keep code cloned through git.
    5. Run cd git to navigate into the git directory.
    6. Run git clone https://github.com/xilution/xilution-react-todomvc to download the code for this example.
    7. Run cd xilution-react-todomvc to navigate into the directory where the code for this example has been downloaded.
  5. Install Node.js 8.10.0

    1. From within the 'xilution-react-todomvc' directory, run nvm install to install the version of Node.js used by the example.
  6. Download Project Dependencies

    1. From within the 'xilution-react-todomvc' directory, run yarn to install Node.Js dependencies.
  7. Save your Xilution Subscriber API Key and Organization ID in AWS Secrets Manager

    • Look up your Xilution Subscriber API Key and Organization Id through the Xilution Customer Admin Portal. Use the credentials you used to create your Xilution Subscriber Account.
    1. Run aws secretsmanager create-secret --name XilutionSubscriberApiKey --description "My Xilution Subscriber API Key" --secret-string {REPLACE-WITH-YOUR-API-KEY} to save your Xilution Subscriber API Key to AWS Secrets Manager.
    2. Run aws secretsmanager create-secret --name XilutionSubscriberOrgId --description "My Xilution Subscriber Organization ID" --secret-string {REPLACE-WITH-YOUR-ORG-ID} to save your Xilution Subscriber Organization ID to AWS Secrets Manager.
  8. You can also update your Xilution Subscriber API Key and Organization ID in AWS Secrets Manager

    1. Run aws secretsmanager update-secret --secret-id XilutionSubscriberApiKey --description "My Xilution Subscriber API Key" --secret-string {REPLACE-WITH-YOUR-API-KEY} to save your Xilution Subscriber API Key to AWS Secrets Manager.
    2. Run aws secretsmanager update-secret --secret-id XilutionSubscriberOrgId --description "My Xilution Subscriber Organization ID" --secret-string {REPLACE-WITH-YOUR-ORG-ID} to save your Xilution Subscriber Organization ID to AWS Secrets Manager.

Provision and Deploy

  1. Open a command line app.

    • Mac: Terminal
    • Windows: Git Bash
  2. Provision and Deploy Backend Resources

    1. Change template defaults.
    2. Run make provision-base to provision the base AWS resources.
    3. Run make build-backend to build the backend resources.
    4. Run make deploy-backend to deploy the backend resources to your AWS account.
    5. Run make show-backend-url to see the URL of the backend RESTful web service.
    6. Run make put-types to register JSON schema used by this example with Xilution - Elements - Data Accessor.
      • You will be prompted for credentials. Use the credentials you used to create your Xilution account.
  3. Deploy Frontend Resource

    1. Run make build-frontend to build the frontend resources.
    2. Run make deploy-frontend to deploy the frontend resources.
    3. Run make show-frontend-url to see the URL of the frontend application.
    4. Copy the front end URL and paste it into a browser.
      • You should see the login for for the TodoMVC app.

👏👏👏 The example should now be up and running in AWS. 👏👏👏

To Test

  1. Open a command line app.

    • Mac: Terminal
    • Windows: Git Bash
  2. To Run Linter and Unit Tests

    1. Run yarn test to run the linter and run unit tests.
  3. To Run the App Locally

    1. Run make dev to run the app locally.
      • make is necessary to automatically inject the backend url.
  4. User Acceptance Testing

    1. Run make show-frontend-url to see the URL of the frontend application.
    2. Copy the front end URL and paste it into a browser.
    3. Run through the different use cases
      • Register New User (including email verification)
        • Creates a new user in your Xilution account. You can use the same email across multiple users. User email must be verified. Usernames must be unique for all users. You can manage your Xilution account through the Xilution Customer Admin Portal.
      • Authenticate User
        • Use your Xilution user credentials
      • View Todos
      • Create/Update/Delete Todos

Troubleshooting

  1. Backend

    • CloudWatch Logs
      • Open the AWS CloudWatch console.
        • Lambdas
          • Click Logs in the left hand menu.
          • Search for '/aws/lambda' to see a list of provisioned Lambda functions.
          • Choose the Lambda function associated with the endpoint giving you trouble.
          • Browse through the logs for error messages.
          • I've found it most effective to find error messages by time.
        • API Gateway
          • Finding CloudWatch logs for API Gateway is a little trickier than Lambda.
          • Open the AWS APIGateway console
          • Find the API ID for the xilution-todo-sam API.
          • Go back to the AWS CloudWatch console.
          • Click Logs in the left hand menu.
          • Search for 'API-Gateway-Execution-Logs_{REPLACE-WITH-API-ID}/Prod'
  2. Frontend

    • Google Chrome
      • Open the Chrome Developer Console
      • Errors appear in the Console tab and will have a Error ID.
      • You can get a more detailed description of the error by finding the Error ID in CloudWatch Logs.
      • Also use the Network tab to observe how the app is interacting with the API.
  3. Bugs

Deprovisioning

  1. Open a command line app.

    • Mac: Terminal
    • Windows: Git Bash
  2. Deprovision Resources

    1. Run make deprovision-backend to deprovision backend resources.
    2. Using the AWS Console, delete the S3 buckets
      • xilution-todomvc-website-bucket
      • xilution-todomvc-staging-bucket
    3. Run make deprovision-base to deprovision the base resources.
    4. Run aws secretsmanager delete-secret --secret-id XilutionSubscriberApiKey --recovery-window-in-days 7 to delete your Xilution Subscriber API Key from AWS Secrets Manager.
    5. Run aws secretsmanager delete-secret --secret-id XilutionSubscriberOrgId --recovery-window-in-days 7 to delete your Xilution Subscriber Organization ID from AWS Secrets Manager.

Next Steps

I'm hopeful that this reference implementation inspires you to to use AWS SAM and React for your next web application. I also invite you to learn more about how Xilution SaaS can accelerate your next web or mobile application project.

Need help with your serverless project? Hit me up on Twitter. I would be happy to pitch in where I can.

FAQ

  1. 💰 How much does it cost to run this example?

    • AWS offers a "free" tier which enables you to gain free, hands-on experience with the AWS platform, products and services.
    • You may find the AWS Simple Monthly Calculator to be useful in calculating your monthly AWS expense as well.
    • Pricing for AWS managed services used in this example
    • Pricing for Xilution SaaS Products used in this example
      • This example integrates with Xilution's Beta environment which is Free for evaluation purposes.
      • The Xilution SaaS products highlighted in this example have not yet been released for production consumption.
      • See the Xilution SaaS Products page for the latest product phase and pricing details.
      • For comparision, here is AWS's published pricing for data storage services.
  2. Why React?

  3. Is the backend necessary?

    • The purpose of the backend is two fold. First, it abstracts domain specific functionality from the frontend. For example, some TodoMVC uses cases require the aggregation of a few different Xilution SaaS requests. Second, it protects secrets like the Xilution Subscriber API Key and the Xilution Subscriber Organization ID.
  4. Why Node.js for the backend? Are there alternative programming languages?

  5. Can this example run on other public cloud platforms?

    • In theory, yes. Azure and Google Cloud Platform offer similar types of web hosting and compute services needed to run this example. Eventually, I would like to develop Terraform templates for several different public cloud platforms. If you're passionate about your cloud platform and would like to see it incorporated in this example, I invite you to submit a pull request.
  6. What about the Serverless framework?

    • I personally don't have experience working with the Serverless framework, but I hear good things. The pervasiveness of the framework warrants a mention in this example's FAQ. I applaud the maintainers of the framework for their advancement of serverless computing. I would like to learn more about the framework and how it could be incorporated into this example. If you're passionate about the Serverless framework or other similar frameworks, I invite you to submit a pull request.
  7. Do I have to use Xilution SaaS?

    • Nope. You can use just about any persistance model in your backend implementation including other API Based SaaS providers. AWS RDS and DynamoDB are valid alternatives if you choose to provision and maintain your own persistence infrastructure. However, I think you'll reconsider investing in a relational or noSQL database and choose API Based SaaS when you consider the productivity gains that a serverless architecture model has already afforded you. In a way, API Based SaaS is like the icing on the cake. If you're interested in learning more about API Based SaaS, this blog article Ed Shelley is a good place to start.

Issues

Issues are managed here.

About the Author

Todd Brunia is a Sr. Software Engineer with Source Allies and the founder of Xilution.

Contributions

See something about this example that you think could be improved? Pull requests are encouraged and greatly appreciated!