Build a Serverless IoT Application using AWS Amplify and Vue

screenshot of DegreeSee dashboards view

Initial State & The App We’re Building Here

The Initial State platform is a powerful, IoT based data visualization and analytics tool that allows users to stream time series data into a beautifully built dashboard to view and analyze in a web browser.

The application we are building today will allow users of the Initial State platform to create their own white label version of the platform with their own separately managed users. An Initial State user can create their own fully self-managed application on the Amazon Web Services (AWS) platform with their own set of users (not of the Initial State platform) to share their dashboard views with.

Initial State single dashboard view within DegreeSee application

The back end of this application is entirely serverless, built on the AWS platform using services: AWS Amplify, Cognito, Lambda, API Gateway, and DynamoDB. The front end is Vue.js utilizing Vuetify for styling and pre-built components.

Building the App — An Overview

This article will serve as a high-level overview of the entire open source application. You can access all of the source code for the live demo of the DegreeSee application here.

AWS Amplify makes setup remarkably fast and easy. We will clone the project from GitHub, initialize it with Amplify, push it to the AWS Cloud, and wrap up with a few additional steps in the AWS Console. I’ll also include steps on how to host the app on your own domain, which is entirely optional.

I will walk you through the core pieces of the application and show you where to make customizations.

Getting Started

For this project you will need:

• an Amazon Web Services (AWS) account
• a GitHub account
• Node.js v10.x or later
• npm v5.x or later
• git v2.14.1 or later

If you don’t have an Amazon Web Services (AWS) account, you can create one and gain access to the Free Tier here:

AWS Console — Signup

Install and Configure the AWS Amplify CLI

Install Amplify CLI

npm install -g @aws-amplify/cli

Configure Amplify CLI and create AWS IAM User

In order to configure the CLI, we’ll need to create an AWS IAM user, which we’ll do during the configuration process. If you don’t have an AWS account yet, create one before running configure.

For a visual walkthrough of how to configure the CLI, check out this video.

amplify configure

This will open up the AWS Console in your browser.

After signing in, return to the CLI to select your region and name your IAM user.

I chose us-east-1 as that’s the region in closest proximity.

After naming your IAM user, return to the AWS Console.

• Programmatic access is preselected, keep that and hit Next.
• AdministratorAccess is preselected, as well as Create user without a permissions boundary; keep both selections and hit Next.
• Review and Create user.

Be sure to save your secret access key as you won’t have access to it again.

• Return to the command line and enter your accessKeyId and secretAccessKey when prompted.
• Name the AWS Profile on your local machine or keep it as default.

Naming the AWS Profile is not necessary for this tutorial, but for additional guidance on naming and configuring your AWS Profile for the CLI, go here.

Clone the App and Customize It

Now is when the fun begins… let’s setup your app!

Create and cd into a local directory for your application.

mkdir degreesee-app
cd degreesee-app

Run this magical command.

amplify init --app git@github.com:initialstate/degreesee-app.git

During this initialization process, Amplify will clone the repo into your directory, create a backend environment, and set your default editor.

You will have the opportunity to run amplify configure project later on to change some of the default settings (not yet).

The CLI will ask you to select the authentication method you want to use.

• Select AWS access keys and paste in the values for accessKeyId and secretAccessKey from the AWS IAM user we previously created.
• Set your region.

Your backend resources will now be created and pushed to the cloud.

Connect Your Own Repo

When you run git remote -v you will see that the app is still connected to its source repo. Let’s change that.

• Navigate to GitHub and create your repository.
• Copy the origin URL
• Run the following command, pasting in your repo URL

git remote set-url origin <your_new_repository>

Configure Project (optional)

If you want to change any of the default project settings, like the default editor, for instance, run amplify configure project .

Under Project information, you can see what is available to change.

Note: I haven’t personally attempted to change any of these settings after cloning an app. Do so at your own risk.

Customizing Email Verification

When a new user creates an account, we verify them by sending a code to the email address provided.

Let’s customize the email verification subject and message in amplify/backend/auth/appName/parameters.json

On lines ~15 & 16 you should see emailVerificationSubject and emailVerificationMessage .

Customize those to your liking, but be sure to include {####} in the message as placement for the verification code.

"emailVerificationSubject": "Welcome to DegreeSee! Please verify your account.",
"emailVerificationMessage": "Your verification code is {####}.",

If you made any changes to the subject or message, you’ll need to push those changes to the cloud.

Run amplify status in the CLI and you will see that the Auth resource has been updated.

To push your backend to the cloud, run amplify push.

Adding the Cognito Post Confirmation Lambda Trigger

We are using Cognito for authentication, but need our users in DynamoDB in order to have multiple dashboards.

To accomplish this, we have a custom Lambda function that will be triggered once a user confirms their account. This Lambda will create a user in Dynamo thereby enabling us to add and delete dashboards.

Navigate to the Cognito console by running the following command:

amplify auth console
? Which console: User Pool

• In the navigation bar on the left side of the User Pool console, you should see a General settings section. Beneath that, select Triggers.
• Find the Post confirmation trigger and select addUserLambda-env with env being the name of your backend environment.

If you’re not sure what environment you’re in, run amplify env list in the CLI. The environment with a * next to it is the environment you’re working in.

post confirmation Lambda trigger in Cognito console

Be sure to save the changes!

Now that we have the backend all setup, let’s test it locally.

Run npm run serve and you should see your app!

App Styling, Theming, and Auth UI Customization

Authenticator UI Customization

For our authentication flow, we are using Amplify’s Authenticator UI component. This component encapsulates the entire authentication flow and is easy to customize.

Amplify Authenticator UI Component

As you can see, the Sign Up component is customized to our specific DegreeSee app and use case, with the header text and additional form field for the Invitation Code.

You can alter some of these customizations to your liking in the Auth component.

Authenticator UI Sign-Up Template

Navigate to src/components/users/Auth.vue

Authenticator Template

To change the header of the sign-up component, modify line 11’s header-text value.

You can also change the button text with line 12’s submit-button-text.

Authenticator Form Fields

Authenticator Form Fields

If you add or remove any form fields (without making additional changes to the backend), it will have negative impacts on the app functionality itself.

However, you can customize the formFields label and placeholder text.

Keep the type and required values as they are.

The Invitation Code form field is a custom attribute I added to Cognito upon resource creation. It cannot be changed.

To read more about the Authenticator component, check out the docs.

Amplify Theme & CSS Customization

Amplify supports theming of the UI components with CSS custom properties.

Within src/App.vue you’ll see the following:

/* amplify theme */
:root {
  --amplify-primary-color: #275ba7;
  --amplify-primary-tint: #e05800;
  --amplify-primary-shade: #fd9653;
}

The above code sets the colors at the root level for the Amplify components we are using. There are various other properties you can set as well. To learn more about theming and CSS custom properties, check out the docs.

We can also control components directly by specifying properties inside of their selectors.

For instance, we can make adjustments to the amplify-authenticator component directly within src/components/users/Auth.vue

For more information on CSS styling at the component level, go here.

amplify-authenticator {
  --container-align: flex-start;
  --container-height: 0;
  padding: 2em;
}

Vuetify Theme

Vuetify allows us to change the colors of our Vue application easily through themes. They even provide a theme generating tool that gives us an idea of how the colors will be displayed, then easily export.t

To read more about Vuetify themes, go here.
To try out the theme generator tool, go here.

You can find the theme for this app in src/plugins/vuetify.js

Connect & Deploy Front-End

Navigate to the Amplify console and select your app.

• Under the Frontend environments tab, you should see a box with the header: Host a web app
• Select GitHub, then Connect branch.

add GitHub repository branch to Amplify application

• Under Add repository branch, select your repo from the dropdown list.
  Select the branch you want to connect.

application build settings

• Under Configure build settings, you should see Select a backend environment to use with this branch. The App name should already be preselected.
• Choose the environment you want to connect from the dropdown list.
• Enable full-stack continuous deployments (CI/CD) should be preselected — keep it checked.
• Under Select an existing service role or create a new one so Amplify Console may access your resources, click the button titled Create new role.
• Keep the default settlings and click next all the way through.
• Create role.
• Now, you should see the role you just created from the dropdown list.
  Select it and click Next.

• Review your settings and click Save and deploy.

Note: At the time of writing this article, AWS was throwing a BadRequestExceptionerror with the message, “You should at least provide one valid token”.

To fix this, I had to sign out of the console, sign back in, and repeat the steps above. *sigh*

After your repo and branch are successfully connected, the app will automatically build and deploy.

You now have continuous deployments setup! Anytime you push to the branch you selected, your app will automatically build and deploy.

Reminder: anytime you make changes to the backend, you’ll need to run amplify push as well.

After the application has been deployed and verified, you’ll be able to access it via the AWS URL provided. This can be found in the Frontend environments section of the app within the Amplify console and will look similar to:

https://master.wr6nfxsgnksfh.amplifyapp.com/

Potential Access Denied Error Fix

After deploying the front end, it’s common to receive an Access Denied 403 error when accessing the app via AWS’s provided URL. There’s a fix for that.

Access Denied 403 Error

• Navigate to the Amplify console.
• Under App settings, select Rewrites and redirects.
• Click the button that says Add rewrites and redirects.

• For Source address, write /<*> .
• For Target address, write /index.html .
• For Type, select 404 (Rewrite).
• Hit Save.

Refresh and the Access Denied 403 error should be fixed!

Invitation Code ~ Creating User Accounts

The invitation code that you will provide to your users upon account creation lives in your Initial State account.

• To find the invitation code to share with your users, log into your Initial State account and open the settings panel for the dashboard (bucket) you want to share.

• Under the Data tab, find the Bucket Key. This Bucket Key is your invitation code.
• Copy that and have your users paste it into the Invitation Code slot on the create account screen exactly as it is.

• Under the Sharing tab, check the box that says Share Publicly.

You’re now ready to share your dashboards / buckets with your users!

Domain Hookup (if you have one)

• Navigate to Route 53 in the AWS Console.
• Under DNS management, click Create hosted zone.

• Enter your domain name (as is, without the www) and click Create hosted zone.

• Route 53 should have provided you with 4 name servers. Copy those.

• In your hosting account (Google Domains, GoDaddy, Route 53, etc.), navigate to the DNS settings for the domain you’re using and paste in these custom name servers.
• Next, in the Amplify console, click Domain Management from the left side navigation under App settings.
• Click Add Domain.

• Enter your domain and click Configure domain.
• Ensure the proper branch is selected and hit Save.

If you want to deploy your app to a subdomain, check out these docs.

Your app should now be deploying to your domain (this can take 5–20 minutes).

Our last step is to ensure the redirect is setup properly.

• From the left side menu, select Rewrites and redirects.
• Confirm that the redirect for your domain looks like this:

rewrites and redirects in amplify console

(i.e. redirect the https://domainname to https://www.domainname)

Once the DNS propagates, you should see your application live at your domain!

Conclusion

You now have your very own IoT application and can share your Initial State dashboards with your own, self-managed users!