Skip to content
This repository has been archived by the owner on Nov 29, 2019. It is now read-only.

Latest commit

 

History

History
87 lines (63 loc) · 6.17 KB

installation.md

File metadata and controls

87 lines (63 loc) · 6.17 KB
Raw

Installation

Requirements

  • NodeJs (>= 6.0)
  • MongoDB (>= 3.4)

Download and Config

It is assumed you have MongoDB installed already. If not, install MongoDB. Note that MongoDB must be publicly accessible via an IP or domain if you are using Google Cloud HTTP function to handle your webhooks (see Webhook Setup). If you can, I recommend you host MongoDB on a separate server.

  • Create directory locally or on your server
  • Run git clone https://github.com/suetco/suet in the directory or just download and unzip right in
  • Run npm install

Next, you will need to update the environment variables. There is a .env.example file that contains the needed variables. These variables also include settings for third party tools and services Suet uses. These are:

  • Bugsnag for error reporting
  • Elasticsearch for search
  • Mailgun for sending password recovery mails. In coming versions, provision will also be made to use SES
  • Slack for complaints and failure deliveries

Open the file, edit the variables and rename the file to .env. They variables are:

  • HOST - The IP or web address your application will be located at, without the trailing slash. Must include the protocol (http or https) even if it is an IP e.g. http://suet.some.paas
  • SESSION_KEY - Random string to encrypt session cookies
  • AES_KEY - Random string used for API key encryption in the database. It is important you don’t change this key once set as already encrypted keys will not be decryptable
  • DB_NAME - Name of your MongoDB database e.g suet
  • DB_URL - URL of your MongoDB database e.g mongodb://localhost/suet
  • ES_HOST - Elasticsearch IP or web address
  • ES_AUTH - httpAuth value for your Elasticsearch
  • BS_KEY - Bugsnag key for error reporting. Signup for a free account at bugsnag.com and get a key
  • EMAIL_FROM - The sender identification for the email. Format “Name <email>” e.g. Suet <[email protected]>
  • EMAIL_DOMAIN - The Mailgun domain you want to send emails from
  • EMAIL_KEY - The API key of the domain above. Login to your Mailgun account and click the domain to get the domain API key
  • WEBHOOK - Your Mailgun webhook URL. See Webhook Setup.
  • SLACK_CLIENT_ID - Your Slack app’s client ID. See Connecting Slack
  • SLACK_CLIENT_SECRET - Your Slack app’s client secret. See Connecting Slack)
  • SES_CONFSET - Configuration set name for SES. You don’t need to change this.
  • SES_TOPIC - A name to create the notification topic. You also don’t need to change this.
  • SES_WEBHOOK - Your SES webhook. See Webhook Setup.

Once set (and file renamed to .env), you can start Suet with node app.js or in your favourite way.

Upgrading from v1 directly to v3

One important change to version 2 is that API keys are encrypted (AES, 256, CTR) in the DB. If you are upgrading from v1, you need to run node upgrades/v2.js to encrypt existing keys in your database. Don’t forget that once this is done, you shouldn’t change your AES_KEY any longer as already encrypted keys will not be decryptable.

Webhook Setup

You need to setup webhooks that Mailgun and SES will send events to. (Here is a post on working with Mailgun webhooks). The recommended option for the Mailgun webhook is to use Google Cloud HTTP function. It is highly scalable especially if you send lots of mails.

Q: Why not AWS API gateway + Lambda?

A: Mailgun uses the content-type multipart/form-data to send some event data and this content-type is not supported by AWS API gateway (yet).

If microservices is not your thing or just can't go through the stress, the webhook endpoints are available at [host]/mailgun/webhook and [host]/ses/webhook. This is discussed further below.

Using Google Cloud HTTP function

  • Go to your Google Cloud Console (if you don't have an account yet, create one).
  • Enable Cloud functions in the dashboard.
  • Click on Create Function.
  • You will repeat these steps twice to create the SES and Mailgun webhooks. Enter your preferred name for the webhook (e.g ses-webhook or mg-webhook).
  • In the trigger section, select HTTP trigger. Note the URL, that will be your webhook URL.
  • Edit workers/hooks/index.js and enter your MongoDB URL. (No environment variable in Google cloud or I wasn’t looking well enough).
  • Also enter the HOST variable (as defined in your environment variable above). This is used to create mail links sent to Slack.
  • Copy the content of the file and paste in the index.js section of the Cloud function.
  • Copy the content of workers/hooks/package.json and paste in the package.json section.
  • Select or create a Stage bucket. The stage bucket is simply where the code is staged. You can use anything here.
  • In Function to execute, enter handler.
  • Save.

Using app's webhook endpoint

Edit your the WEBHOOK and SES_WEBHOOK variables to point to [host]/mailgun/webhook and [host]/ses/webhook respectively. Remember, the host [host] value should include the protocol (http or https) even if it is an IP.

Connecting Slack

You can connect Slack to Suet to be able to receive complaint, bounce and fail notifications. To do this you need to create a Slack app and add the details to Suet. Once added, domains can be connected to Slack in the domain settings page of the Suet dashboard.

  • Visit api.slack.com/apps and click on the Create New App button.
  • Enter the required details and proceed.
  • Under the Add features and functionality section, click on Incoming Webhooks.
  • Activate Incoming Webhooks in the next page (toggle the switch to On) then go back to previous page.
  • Scroll down to App Credentials and copy your Client ID and Client Secret.
  • Use the credentials as your Slack environment variables.