AdonisJS on Heroku

AdonisJs and Heroku logo
Adonis and Heroku sitting in a tree

My current employer is developing a number of applications using AdonisJS. In an effort to increase my familiarity with the framework I have decided to try and write the Tuxsters video award site using AdonisJS.

At work we push code to Amazon, and I was hoping to look at what I could do for the Tuxsters project.  Where can I push my code so that I can test that the site works?

Previously I have had some limited experience of Heroku, so I decided to set up GitHub, AdonisJs and Heroku.

In this tutorial I will be setting up an AdonisJs App, storing it in a GitHub repository and pushing it to Heroku. I’ll be writing the command lines used – but also showing the same functionality through the web dashboard.

Ready? – Let’s begin.

Create a GitHub repository

Firstly we’ll need to create a GitHub repository.  GitHub already do a pretty good job of documenting the process for creating a repository. My repository is called Yardstick.  Why yardstick? Well the adonis example documentation refers to yardstick – obviously you can call your’s whatever you like.

Create a local yardstick project.

Assuming you’ve already installed AdonisJs then we’ll need to create an app, and then initialise it as a git repository. You might be wondering if you could just clone the empty repo and add AdonisJs to it? Well Adonis attempts to create the folder, so no. The only (and best way) is to create your folder using the adonis command. I keep all my projects in ~/Projects – yours may be different so adjust the following as necessary. Using the instructions from AdonisJs :

cd ~/Projects
adonis new yardstick
Creating an AdonisJs Application
Creating an application

 

 

Initialising Git in the new yardstick application folder
Initialising Git in the new yardstick application folder

Setting the GitHub Remotes and getting your code to GitHub.

At the moment this local git repository has a couple of issues – firstly that there is no remote, and secondly that there are no files. When we created the GitHub repository, there was a page explaining how to set the remote end points – we can run these now.

git remote add origin https://github.com/computamike/yardstick.git

Once we have done this we’ll need to add some files.

git add .

Commit them with a suitable message

git commit -m 'initial commit'

and finally push them to GitHub.

git push -u origin master

So – now you have your project pushed to GitHub – great.

Yardstick Project Uploaded to github.
Yardstick Project Uploaded to GitHub.

Setting up a Heroku application.

If you don’t already have a Heroku account, get one set up. It’s free to sign up. Go ahead… I’ll wait.

Firstly we need to create a Heroku app – to do this through the CLI :

heroku apps:create yardstick
Creating a Heroku Application
Creating a Heroku Application

Creating a Heroku application through the dashboard is a case of clicking on new, selecting App, from the drop down, and giving it a name.

Setting up an application on Heroku
Setting up an application on Heroku

Setting up the Heroku Application.

Now all that remains is to configure the application – both in terms of GitHub integration and the application settings. Currently this application is empty so we’ll configure the integration between GitHub and Heroku. To do this, pop onto your Heroku dashboard and click on the GitHub logo.

Connecting Heroku to GitHub
Connecting Heroku to GitHub

Click on the connect button to link it to your repository.

We can configure automatic builds when a branch is pushed to, and we can ensure that tests pass before that – but for now we’ll manually push. To do that we can press the Deploy Branch button under manual deploy.

Manually deploying a GitHub Branch
Manually deploying a GitHub Branch

We’ll do that now to show how the integration works – but be prepared. It will error at this point.

Clicking on that button will present the following

Deploying a GitHub repository to Heroku successfully - but will it run?
Deploying a GitHub repository to Heroku successfully – but will it run?

Clicking on the view button to show the application presents this :

Heroku Error Message - Something's wrong with the app but what?
Heroku Error Message – Something’s wrong with the app but what?

How do you read the logs of a Heroku app? Through the CLI we can issue the command

heroku logs -a yardstick -t

to tail the logs.

Tailing the logs
Tailing the logs

The process for accessing the logs using the dashboard is to click on More, and then logs.  The Dashboard logs don’t seem as comprehensive as the logs from the CLI – so it’s probably more advisable to use the CLI to pull Heroku logs.

Error logs displayed through the Heroku Dashboard
Error logs displayed through the Heroku Dashboard

The main error here is :

Error: ENOENT: no such file or directory, open '/app/.env'

What is happening is that the AdonisJs installation creates a .env file within the project root, which contains the configuration for the application. This is ignored by the .gitignore file and is therefore missing from the application when it is pushed to Heroku.

.env file content
.env file content

This is not a bad thing – this configuration file typically contains configuration information such as database passwords and connection information. If this were to be pushed to GitHub, and then through to Heroku this would allow anyone to access the database as the application.

Instead the Configuration system in Heroku can be configured with the appropriate values.

We’ll need to replicate most of these settings within the Heroku configuration system with the following exceptions.

ENV_SILENT

Not present in the .env file – this setting will prevent AdonisJs from raising an error if the .env file is missing.  This needs to be set to true.

PORT

Heroku automatically creates a random port, and this is exposed as the PORT environment variable.  We can therefore ignore setting the PORT configuration setting.

HOST

In the AdonisJs .env file this is set to 127.0.0.1 – this needs to be set to 0.0.0.0 in order for Heroku to correctly bind the process.

To set a configuration setting (for example to set the HOST setting) using the CLI use the command :

heroku config:set -a yardstick HOST=0.0.0.0

Setting through the Dashboard is simple enough using the user interface

Setting Application configuration using the dashboard
Setting Application configuration using the dashboard

Now accessing the application presents the following :

 

AdonisJs Working screen
AdonisJs Working screen

Getting that all important GitHub Badge

We can now deploy our code from GitHub to Heroku – but what we really want is that markdown badge. Don’t worry – you’re not alone.  Chris Hendel had exactly the same requirement and wrote a Heroku appication status markdown generator – hosted using Heroku.

Heroku Shields markdown generator
Heroku Shields markdown generator
Heroku status badge - in all its glory
Heroku status badge – in all its glory

So what did we learn

Hopefully we learned that :

  • We can’t add AdonisJs to an existing project – instead we start with AdonisJs and add to it.
  • Getting AdonisJs working on Heroku is mostly a configuration exercise, and that this configuration can be done through the Dashboard or through the CLI.
  • Activating GitHub integration is best done through the Dashboard –  I couldn’t find a method of authorising using the CLI – if anyone knows of one then please let me know and I’ll include it.
  • Logs are best retrieved through the CLI
  • We can use http://heroku-shields.herokuapp.com/ to create a GitHub badge for our repository

Still to cover

Heroku offers a selection of add ons including postgress, redis, mysql – and I’ll be investigating integrating these technologies within an AdonisJs app.

The yardstick GitHub repository can be found here: https://github.com/computamike/yardstick

The yardstick Heroku application can be found here: https://yardstick.herokuapp.com/

Mike is the programmer in the bunker. He writes software for a shaddowy software house in Worcester. He works mainly in .NET and python, but equally has found himself having to support different technologies such as MAXScript and .NET integration. Spending most of his time working on his passion of content packaging, and is currently working on an ebook authoring system for Ubuntu. Although he is the main programmer on the site he doesn’t do much with regard to writitng games