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
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.
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 through the dashboard is a case of clicking on new, selecting App, from the drop down, and giving it a name.
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.
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.
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
Clicking on the view button to show the application presents this :
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.
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.
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.
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
Now accessing the application presents the following :
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.
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/
