Using Locomotive CMS on Heroku

on heroku

So I was given the popular task of creating a site for my sister. It had to be simple enough for her to make edits, upload images, free to host and most importantly low maintenance -- I don't want to spend time ironing issues.

What skittered to mind was, Heroku for hosting and a Rails CMS for edit content managing. I don't want to do PHP so Wordpress was not an option.

I took a look at these free content management systems:

I have used RefineryCMS in the past and the community was too small. Any problems I had resulted in hours figuring it out myself.

Wagtail looked really awesome, but it's in Python and I rarely touch that language.

Locomotive Is The Winner

I decided on using Locomotive because:

  • Active contributors / maintainers
  • Good documentation
  • Can host multiple sites on a single Heroku instance -- big plus
  • Can deploy sites in seconds using Wagon
  • No need to tinker around with Rails controllers / views

What You'll Need

  • Heroku Account
  • S3 Bucket for hosting assets
  • Domain name

Don't Use Locomotive V2

So the first thing I noticed was there were two versions of Locomotive, v2 and v3. I initially used v2 but it was so old and unsupported, I quickly gave up.

Locomotive v2 only supports mongoid 3 which is too old for mongodb 3. On Heroku only mongodb 3 is given out for free, if you want the older mongodb 2 you'll have to pay for it. So, let's dive into the unreleased v3 Locomotive.

Create Locomotive V3 Instance

The Locomotive team was smart enough to create an instant deploy tutorial. I followed the tutorial, launching the Heroku deploy script and so now the next step is to pull the Locomotive code from Heroku to Github.

posts/using-locomotive-cms-on-heroku/heroku-app.png You should see something like this on Heroku

Pulling Code From Heroku to Github

First make sure you have the latest Heroku Tookkit installed.

mkdir webcms
heroku git:remote -a webcms
git pull heroku master
git remote add origin {github-url-here}
git push -u origin master

Creating A Site

At this point, log onto your Heroku instance, create an account and your first site.

posts/using-locomotive-cms-on-heroku/locomotive-handle.png Add your sites domain like so

posts/using-locomotive-cms-on-heroku/locomotive-dash.png The dashboard should look like this

Now the newly created site can be pulled down from Locomotive.

gem install locomotivecms_wagon --pre
wagon clone kristen_d_angelo_art http://webcms.herokuapp.com -h kristendangelo -e {email} -a {api-key}
cd kristen_d_angelo_art

For some reason the Gemfile had to be uncommented, then I could bundle install.

bundle install
wagon serve
  • wagon serve will run the develop server to let you preview your site.
  • wagon push production will push whatever you have to production.

That's all you really need to know. You can learn more about how all this works here.

Development Workflow

You will be spending your time inside the wagon adding data, fields, layout changes. Surprisingly the only thing you need to push to Heroku directly is only when you want to update the Locomotive version.

Setting Up The Domain

The last step is to make the domain point to the Locomotive site. I use NameCheap, and here is what I did.

posts/using-locomotive-cms-on-heroku/namecheap-setup.png CName www to Heroku app url. Redirect root to www

Creating An Account For The User

The very last step is to create an account for the editor. There are two options in Locomotive author and designer. I honestly don't know what the difference is, I just picked author.