Skip to content

Latest commit

 

History

History
138 lines (99 loc) · 4.88 KB

README.md

File metadata and controls

138 lines (99 loc) · 4.88 KB
Raw

logo

Sesame - Creator garage door opener controller

Keywords:

  • HATEOAS
  • Heroku
  • mLab

Architecture

Architecture

Jump Start

There are two ways to use the Webapp:

  1. Cloud Deployment
  2. Locally

Cloud Deployment

This guide explains the process of cloud deploying the Webapp to Heroku and mLab, using their free tiers. However the performance can be improved using a payed service, or if you prefer different hosting services: AWS, Google Cloud, etc.

1. Get the project

  1. Clone the project from git repository
  2. Rename file config.js.sample into config.js located in project root directory

2. Developer Console - Create Account

  1. Create a Developer Console account
  2. Generate a set of API Keys
  3. Insert the API Keys into the config.js file

3. IFTTT - configure alerts via email/sms (optional)

You can receive email and/or sms notifications about door issues. For that you need create applets on IFTTT service.

  1. Create an account on IFTTT service.
  2. Connect your account with "Maker channel" service. Select the service from list, click "connect" button and follow instructions.
  3. Once connected you can create your applet. From top menu select "my applets" and click "new applet".
  4. As a trigger select Maker Channel applet.
  5. As a event use one of two provided by sesame web app:
    • doorstuck is used to notify you when door couldn't reach end position
    • maintenance is used to notify you when door needs maintenance
  6. As a action service choose anything you want. Eg you can use email service to get notifications via email or sms service to get them on your phone.
  7. Create as many applets you want.
  8. Go back to web app source code. Edit config.js file end enable ifttt module by setting flag enabled to true.
  9. Also provide your ifttt key in config.js file. Key can be found under your ifttt acount in your profile -> services -> maker -> settings

4. mLab - Create the DB (Manual Setup)

  1. Sign up for an mlab free account
  2. Create a new database (select Single Node, Sandbox for the free tier)
  3. Add a user
  4. Get the database URI (connection string) visible on the dashboard: mongodb://<dbuser>:<dbpassword>@<dbuser>.mlab.com:<port>/<db_name>
  5. Complete the connection string with your account details. Save the connection string as mongo db configuration: $ heroku config:set MONGOLAB_URI=your_db_uri

5. Heroku - Push The Webapp Source Code

  1. Create an Heroku account
  2. Install Heroku Command Line Interface (CLI)
  3. Enter your Heroku credentials: $ heroku login
  4. Create the application on Heroku: $ heroku create
  5. Edit config.js file and set HOST to an url to Your heroku app instance.
  6. Deploy the application on Heroku: $ git push heroku master
  7. Test the live application: $ heroku open

Start The Web App (Locally)

  1. Get the project, by ZIP download or git clone
  2. Install Node.js LTS
  3. Install the Webapp's dependencies. On projects root directory, execute: $ npm install
  4. Insert the API Keys into the config.js file, located in your projects root folder.
  5. Insert your hostname in config.js file. Remember that you need a proxy in order to get notifications from Device Server.
  6. Install MongoDB
  7. Use a proxy (e.g. Ngrok) to expose the local application on an https server
  8. Start the application: $ npm start

Summary:

  • $ npm install
  • $ npm start

POSTMAN Collection

POSTMAN is a REST client useful to test the Webapp.The following button opens the REST API on POSTMAN, designated by POSTMAN Collection.

NOTE: It can be necessary to adjust some variables on POSTMAN environment to run the collection.

Run in Postman

REST Endpoints

Documentation of REST API can be generated right from source code. From root directory of the project call

npm install apidoc
apidoc -i ./api_v1

Generated documentation can be found in doc directory.

Authentication

Web app uses Json Web Token to authorize incoming request. Each request sent to webapp needs an authorization header. This is

x-access-token : token

Token is based on your app secret from config.js file and can be generated either on above website or using script from inside this project.

Just call:

node ./generateJsonToken.js

and use generated token to sign Your requests.