Deploying AdonisJS Apps to Heroku

Introduction

The question of how to deploy AdonisJS apps keeps popping out within the AdonisJS community. The thing is that most people tend to forget that AdonisJS apps are Node.js applications and can be deployed the same way you would deploy any Node.js application.

In my last post, we built a task list app with AdonisJS. Today, I’ll be showing you how to deploy the task list app to Heroku.

Create a Git Repository

If you follow along from the last tutorial, we need to first set up a git repository since we’ll be using git for deployment. Head over to GitHub/Gitlab/Bitbucket and create a new repository.

Then we initialize git repository in the adonis-tasks directory:

cd adonis-tasks
git init
git remote add origin git@github.com:YOUR_USERNAME/adonis-tasks.git

Create a Heroku App

Login to your Heroku dashboard or signup if you don’t have an account already. Then create a new app.

I named mine adonis-tasks (which might no longer be available for you)

Once the app is created, we’ll be redirected to the Deploy page on the app dashboard where we can see different ways with which we can deploy our app. We’ll be deploying using Heroku Git with the use of the Heroku CLI. So, we need to install the Heroku CLI on our computer. Go through the documentation on how to install the CLI depending on your operating system.

Once the CLI is installed, we need to log in to Heroku with our account details.

heroku login

Next, we add Heroku remote to our task list app repository.

heroku git:remote -a adonis-tasks

Setting Up MySQL Database

The task list app uses MySQL as its database which Heroku does not support out of the box. We, therefore, need a way to use MySQL on Heroku. Luckily for us, there is support for MySQL through what Heroku call add-ons. There are numerous add-ons to add MySQL to our app, but for this tutorial, we’ll be using ClearDB MySQL. So, we need to add ClearDB MySQL to our Heroku app. To do this, go to the Overview page of the Heroku app, we’ll see Installed add-ons section showing the add-ons we have added to the app (it will be empty for now since we haven’t added any).

Click on Configure Add-ons which will take us to a page where we can configure or add a new add-on. Start typing ClearDB and it will show up in the selection option, which we can then click to select.

Upon selecting ClearDB, a modal will appear for us to provision ClearDB to our app. At this point, we can choose a plan we want, but we’ll be going with the free plan for this tutorial.

Clicking on Provision will add ClearDB to our app, and it will also add CLEARDB_DATABASE_URL to our app’s config variables.

Let’s add another config variable DB_CONNECTION which will tell AdonisJS the database connection our app is using. Go to Settings then click on Reveal Config Vars and add DB_CONNECTION as key and mysql as value.

Next, we need to modify our app to use ClearDB when deployed. The CLEARDB_DATABASE_URL is a URL string that contains our database details (host, username, password, and database name), so we need to parse this URL and extract the individual detail. Let’s install an npm package to help us with that:

npm install URL-parse

With that installed, open config/database.js and add the snippet below to the top of it just after where we declare Helpers:

const Url = require('url-parse')
const CLEARDB_DATABASE_URL = new Url(Env.get('CLEARDB_DATABASE_URL'))

Still in config/database.js, replace MySQL’s connection object with:

connection: {
    host: Env.get('DB_HOST', CLEARDB_DATABASE_URL.host),
    port: Env.get('DB_PORT', ''),
    user: Env.get('DB_USER', CLEARDB_DATABASE_URL.username),
    password: Env.get('DB_PASSWORD', CLEARDB_DATABASE_URL.password),
    database: Env.get('DB_DATABASE', CLEARDB_DATABASE_URL.pathname.substr(1))
}

Depending on the environment our app is running, the necessary database settings will be used. It will first look for DB_ variables (which indicate it’s on development) and use them if found else it will fallback to CLEARDB settings (which indicate it’s on production).

Specifying Node.js Version

By default, Heroku will use the current stable version (v6.11.3 as at this tutorial) of Node.js. AdonisJS v4 (which our app is on) requires Node.js v8.0 or greater. So we need to tell Heroku to use a specific Node.js version. We can do this by adding the snippet below to our app package.json:

"engines": {
    "node": "8.5.0"
}

This will force Heroku to use Node.js v8.5.0 (which is the current version as at this tutorial).

Create a Procfile

A Procfile is used to explicitly declare what command should be executed to start your app. We can also add other commands we want to be executed. For instance, release phase enables us to run tasks before a new release of our app is deployed to production. Create a file named Procfile (without an extension) directly in the root of our app (that is adonis-task directory). Note that the P is uppercased. Add the code below into it:

release: ENV_SILENT=true node ace migration:run --force
web: ENV_SILENT=true npm start

Instead of running our app migrations manually with heroku run. We use release phase to run our app migrations before deploying the app to production. This is really helpful compared to running our app migrations manually because we might forget to run migrations after deploying to production sometimes. We are using the --force flag because we are running the migrations on production. The next command simply start the app.

Noticed we prefixed both commands with ENV_SILENT=true. This will prevent us from getting Env provider error because AdonisJS by default expects a .env file from which it pulls some config settings from.

Now let’s commit and push the changes made to the app to remote:

git add --all
git commit -m "initial commit"
git push -u origin master

To deploy our application, we simply push to Heroku:

git push heroku master

This will start the deployment by installing Node.js and other necessary dependencies. Once the deployment is done, we can use the Heroku CLI to open the application.

heroku open

This will open our app in a new browser window.

There you have it, our AdonisJS application is now running:

Conclusion

That’s it guys, you have seen how easy it is to deploy AdonisJS application to Heroku. Kindly drop your questions and comments below. In my next post, I will show you how to deploy AdonisJS application to a VPS.