ParticipationSystems/Discourse/Development

Setting up the development environment

The quickest and easiest way to get up and running with hacking on Discourse is using Vagrant, the following steps will download, provision and setup a development virtual machine for you.

Ensure you have Git, VirtualBox and Vagrant installed.

Open a terminal, and clone the Discourse repository with:

[host]$ git clone https://github.com/discourse/discourse.git -b tests-passed

Then enter the project directory:

[host]$ cd discourse

To start downloading, provisioning and booting the VM, run:

[host]$ vagrant up

This will take quite a while, so go grab a hot chocolate.

Once the VM has booted up, you can shell into it with:

[host]$ vagrant ssh

Then enter the project directory, within the VM:

[vagrant]$ cd /vagrant

Install the required gems:

[vagrant]$ bundle install

Run the database migrations:

[vagrant]$ bundle exec rake db:migrate

Create an admin user:

[vagrant]$ bundle exec rake admin:create

And start the rails server:

bundle exec rails s -b 0.0.0.0

After a few seconds rails will start serving pages, and you should be able to access your Discourse instance at: http://localhost:4000

To log in as the admin user, navigate to:

http://localhost:4000/session/<username>/become

(replacing <username> with the admin username)

Stopping the development environment

To stop the server, kill it with ^C

Exit the VM and stop it:

[vagrant]$ exit
[host]$ vagrant halt

Updating the development environment

You should regularly pull in changes from upstream, do this with:

[host]$ git pull origin tests-passed

After every update, you'll need to update the installed gems and run the db migrations:

[host]$ vagrant up
[host]$ vagrant ssh
[vagrant]$ cd /vagrant
[vagrant]$ bundle install
[vagrant]$ bundle exec rake db:migrate

Using the development environment

Discourse can now be worked on in your favourite editor, outside of the VM, and the changes will reflect themselves inside:

[host]$ cd discourse
[host]$ atom .

Modifying the Rails app (changing .rb files) will require you to kill and restart the server:

[vagrant]$ ^C
[vagrant]$ bundle exec rails s -b 0.0.0.0

Modifying the Ember app (changing .js, .hbs or .css) files only requires a page refresh. Occasionally the temporary files folder needs to be wiped, so if something isn't working as expected try:

[vagrant]$ ^C
[vagrant]$ rm -rf tmp
[vagrant]$ bundle exec rails s -b 0.0.0.0

Most of development work within Mozilla is done on plugins. To keep your code clean we suggest cloning plugins into separate directories, and then linking to them in the discourse/plugins directory.

A method which works for one developer is:

[host]$ git clone https://github.com/LeoMcA/discourse-mozillians.git
[host]$ mkdir discourse/plugins/discourse-mozillians
[host]$ sudo mount -o bind ~/Projects/discourse-mozillians ~/Projects/discourse/plugins/discourse-mozillians

Edits can then be made in the discourse-mozillians directory, which are reflected in the discourse/plugins/discourse-mozillians directory, and then in the VM.

Running tests

Discourse has an extensive series of tests to run your code against. If you just want to run one test (if you're writing it, for instance):

[vagrant]$ RAILS_ENV=test bundle exec rake db:migrate
[vagrant]$ bundle exec rspec spec/jobs/pull_hotlinked_images_spec.rb