The HarperDB Management Studio is a graphical user interface that enables users to install, design, cluster, and manage databases without having to write a line of code. The Studio’s backend is a serverless application that utilizes AWS Lambda and Amazon API Gateway. To build, test, debug and deploy this application we use the AWS Serverless Application Model(SAM), not to be confused with the ace HarperDB engineer named Sam!
SAM is an open-source framework that is used to build serverless applications on AWS. It is an extension of AWS CloudFormation. With just a few lines per resource, you can define the application you want and model it using YAML (a human-readable data-serialization language). During deployment, SAM transforms and expands the SAM syntax into AWS CloudFormation syntax and provisions all the AWS resources we need for the HarperDB Studio.
We decided to go serverless to shift more of our operational responsibilities to AWS. It allows for quick development, seamless scalability and reduced overhead. Our shift to serverless became a lot easier with SAM. SAM offers a single deployment configuration which makes it easy to organize related components and resources, and operate on a single stack. Our application has 30+ Lambdas, all integrated with API Gateway, along with multiple Lambda layers, Step Functions and SNS topics. We can build and deploy our complete application in around ten minutes overall.
The SAM CLI is an essential tool when working with SAM, it provides an easy way to test and debug your application locally. We use the CLI in conjunction with the AWS toolkit for JetBrains WebStorm, the IDE we predominantly use. It provides a Lambda-like execution environment locally, which helps us test the functions before we deploy them. It also allows us to step through and debug our code to understand what the code is doing, as you would with any other type of project.
I’ll run through a few points that we used to get our SAM project setup with our environment (not all of the following steps are essential).
- Install and setup the SAM CLI
- Install Docker for local testing
- Pull the lambci lambda image for Docker
- Install and setup the WebStorm AWS toolkit
- Install the AWS CloudFormation plugin
- Install a YAML parser, I’m using this one
- If you haven’t already, download and run the the sample application
Local Testing With WebStorm
- Edit the Run/Debug Configurations and click on the Templates tab. With the AWS toolkit install you should see an AWS Lambda template tab. Click on that and then select Local.
- In the template make sure it is pointing to your YAML file, by default it is called template.yaml. To the right of the template path, select the Function Name you are testing. If the function name doesn’t come up something is likely wrong with your template. Sometimes I need to save this setup, close and reopen for it to appear in the dropdown. The input is what is passed to the Lambda when it is invoked, you must have a value here.
- If everything has been setup correctly (which it often isn’t, this process can be convoluted) you should be able to run your Lambda as you would any other project in WebStorm. Have it selected in the Run/Debug Configuration and press run or debug.
Deploying the Application
While there are multiple ways to build and deploy the application, this is how we do it at HarperDB. Find out more here – https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html
- Build the application
- Package the application. It creates a ZIP file of your code and dependencies, and uploads it to Amazon S3.
sam package --s3-bucket my-s3-bucket --output-template-file packaged.yaml
- Deploy the application. I suggest adding option -g for guided the first time your deploy your new application.
sam deploy --template-file packaged.yaml --region us-east-2
Working with SAM can be a little confusing initially, it took me a while to get my head around adding resources to the template file (I found this document helpful). However if you stick at it I’m sure you’ll find great value. If you’re curious to learn more about other aspects of HarperDB, feel free to check out our architectural overview, learn more about the product, or spin up a free instance!