Documentation

Deploying to Heroku

Requirements

Deploying Project Mulla is fast and easy but there are a few requirements you’ll need to make sure have done to carry on with the deployment.

  1. You have a free Heroku account
  2. You have Node.js and npm installed locally.
  3. You have installed the Heroku Toolbelt

A key part of the toolbelt is the heroku local command, which can help in running your applications locally.

Testing locally with Heroku

To be able to run the application locally you also need to create an app.yaml file with the basic custom configurations variables specific to you.

env_variables:
  PAYBILL_NUMBER: '898998'
  PASSKEY: 'a8eac82d7ac1461ba0348b0cb24d3f8140d3afb9be864e56a10d7e8026eaed66'
  MERCHANT_ENDPOINT: 'http://merchant-endpoint.com/mpesa/payment/complete'

NOTE: YAML files use 2 spaces strictly as indentation

Once you’re done checking or creating the app.yaml file, just run:

$ heroku local
[WARN] No ENV file found # Ignore this, the YAML config file takes care of this
6:31:02 PM web.1 |  Your secret session key is: a19e4cdb-a83a-4fa7-9efe-6fd3462af607
6:31:02 PM web.1 |  Express server listening on 5000, in development mode

Everything is good, push to Heroku

If your local testing went well, we can now move on to deploying to Heroku.

Start by creating an application instance in heroku:

$ heroku create [project-mulla-companyname]

PLEASE NOTE: The app.yaml is only used locally since you can not use the heroku config command to set local environment variables.

If Project Mulla fails to find it’s required configurations in your app’s Heroku global config vars it will crash. Project Mulla requires you to set this in Heroku since it treats Heroku’s environment as a production one thus an app.yaml file is not visible.

Modify where required in the command below, then copy, paste and run the following command in your terminal to set the required environment variables in your Heroku server instance.

# set required env config vars
$ heroku config:set \
PAYBILL_NUMBER='898998' \
PASSKEY='a8eac82d7ac1461ba0348b0cb24d3f8140d3afb9be864e56a10d7e8026eaed66' \
MERCHANT_ENDPOINT='http://merchant-endpoint.com/mpesa/payment/complete'

# check if your config vars have been
$ heroku config

Now the moment of truth, push the app Heroku.

$ git push heroku master

For the app to work smoothly, ensure you scale to at least one dyno (processor)

$ heroku ps:scale web=1

Up and running

If all went well, your application should be up and running smoothly now. You can confirm this by checking the log trail consoled by your app in Heroku.

$ heroku logs --tail

Or by running and expecting back a JSON response consoled in the terminal:

$ curl -i -X POST \
--url http://project-mulla-companyname.herokuapp.com/api/v1/payment/request \
--data 'phoneNumber=254723001575' \
--data 'totalAmount=10.00' \
--data 'clientName="Eugene Mutai"' \
--data 'clientLocation=Kilimani' \

Monitoring your Heroku deployment

You can add Papertrail, an application log management service to easily monitor the performance and health of the mediator. The FREE tier offered by Papertrail does the job.

# add logging to keep track of your application performance
$ heroku addons:create papertrail

Open Papertrail from the command line/terminal any time using the command:

$ heroku addons:open papertrail