Getting started with Discourse development

Being new to Rails and Ember.js, my first experiences developing a plugin for Discourse were a little traumatic. With a couple of tips I hope to make your life a little bit easier.

First a little introduction. Having had no previous experience with Rails or Ember.js (Discourse is built on both) I decided to head dive and try to create a Discourse plugin. I found a couple of guides and it seemed easy enough. How hard can it be, right?

Well, turns out if you don’t know what you are doing, it can be a little off putting. Most of my problems were related to the development workflow: issues with the development environment and difficulties with debugging.

I will give you a couple of tips and tricks while pointing you to existing guides.

Setup a development environment

The first thing to do is setup a development environment. Following the guide will put you on your way, but I found that without a couple of changes the virtual machine can become unusable.

Increase virtual machine RAM

One thing you can do is increase the RAM available to the virtual machine. For that you need to edit the file Vagrantfile on your local Discourse repository.

That file controls the settings for the virtual machine. Open it up and search for this line:

v.customize ["modifyvm", :id, "--memory", [ENV['DISCOURSE_VM_MEM'].to_i, 1024].max]

Now increase the 1024 number, which represents the MB of RAM for the virtual machine, to whatever you like. I set mine to 8192.

Create a local folder in the virtual machine

You will find this tip mentioned by Régis Hanol in the comments of the guide above. The virtual machine is using a shared folder between its host which gives really poor performance.

By creating a local folder in the VM it runs much faster.

# create an alias to synchronize the code from the shared folder to a local folder
alias sin="rsync -a --delete /vagrant ~"
# actually synchronize (can take a minute for the first run)
sin
# switch to the local folder
cd ~/vagrant
# standard procedure to update, migrate and launch the application
bundle install
bundle exec rake db:migrate
bundle exec rails s

This means that when you make any changes to the code on your host machine you have to synchronize the local folder.

Login to the virtual machine

I had to go around searching for this. If you want to login to the VM directly use account vagrant and password vagrant.

I usually start the VM through a Git shell and the command vagrant up like explained in the setup guide, but then I use VirtualBox to connect to the machine and type the commands there, which works best for me.

Login to Discourse as admin

I think this should be way more clear in the available guides. After you setup the development environment and you have your own Discourse installation, what do you want to do? You want to login to Discourse and start checking the administration!

The easiest way is to login as the existing admin eviltrout by following the URL http://localhost:4000/session/eviltrout/become.

Your first Discourse plugin

Go through the Beginner’s Guide to Creating Discourse Plugins. It will give you the basis for developing plugins.

Clear cache and restart server

You will soon notice that you have to restart the server and clear the cache each time you make a change. Couple that with having to sync the local development folder and it soon becomes cumbersome.

To facilitate that, here is a script that will sync the local folder, clear the cache and start the Rails server.

#!/bin/bash
cd ~/vagrant
rsync -a --delete /vagrant ~
rm -rf tmp
bundle exec rails s

To exit the server just press Ctrl + C.

Send Ruby errors to the browser

You can redirect errors from Ruby to the browser.

Add this line to your controler:

rescue_from 'StandardError' do |e| render_json_error e.message end

Where to go from here

If you are new to Ruby I suggest you read a couple of starter guides (e.g. A Beginner’s Guide To Ruby). Likewise, if you are new to Ember.js read some Ember.js starter guides.

From there I recommend you look at some of the existing Discourse plugins. Go through the source code and see how things are done.

You can also have a look at the plugins I developed:

discourse-slack: displays information from Slack in Discourse
discourse-mumble: displays information from a Mumble server in Discourse