Beginners Guide to Install Discourse on macOS for Development

[techAPJ]

So you want to set up Discourse on Mac OS X to hack on and develop with?

We’ll assume that you don’t have Ruby/Rails/Postgre/Redis installed on your Mac. Let’s begin!

(If you want to install Discourse for production use, see our install guide)

Install Discourse Dependencies

Run this script in terminal, to setup Rails development environment:

bash <(curl -s https://raw.githubusercontent.com/techAPJ/install-rails/master/mac)

This script will install following new packages on your system:

• Git
• rbenv
• ruby-build
• Ruby (latest stable)
• Rails
• PostgreSQL
• Redis
• Bundler
• ImageMagick

In case you have any of this package pre-installed and don’t want to run entire script, see the script and pick the packages you don’t have currently installed. The script is fine-tuned for Discourse, and includes all the packages required for Discourse installation.

Now that we have installed Discourse dependencies, let’s move on to install Discourse itself.

Clone Discourse

Clone the Discourse repository in ~/discourse folder:

git clone https://github.com/discourse/discourse.git ~/discourse

~ indicates home folder, so Discourse source code will be available in your home folder.

Setup Database

Open psql prompt:

psql postgres

Create discourse_development, discourse_test and discourse_test_multisite database with your account short name specified as role:

CREATE DATABASE discourse_development WITH OWNER techapj ENCODING 'UTF8' TEMPLATE template0;
CREATE DATABASE discourse_test WITH OWNER techapj ENCODING 'UTF8' TEMPLATE template0;
CREATE DATABASE discourse_test_multisite WITH OWNER techapj ENCODING 'UTF8' TEMPLATE template0;

Note that in above commands I specified the role as techapj, this means that my short name is techapj, replace this with your own short name.

Exit psql prompt by pressing controld

Now access psql prompt in discourse_development database as your short name user:

psql -d discourse_development -U techapj -h localhost

Run following commands, separately:

CREATE EXTENSION pg_trgm;
CREATE EXTENSION hstore;

Exit psql prompt by pressing controld

Now access psql prompt in discourse_test database as your short name user:

psql -d discourse_test -U techapj -h localhost

Run following commands, separately:

CREATE EXTENSION pg_trgm;
CREATE EXTENSION hstore;

Exit psql prompt by pressing controld

You have set-up the database successfully!

Bootstrap Discourse

Switch to your Discourse folder:

cd ~/discourse

Install the needed gems

source ~/.bashrc
bundle install

Now that you have successfully installed gems, run this command:

bundle exec rake db:migrate db:test:prepare db:seed_fu

Try running the specs:

bundle exec rake autospec

All the tests should pass.

Start rails server:

bundle exec rails server

You should now be able to connect with your Discourse app on http://localhost:3000 - try it out!

Create New Admin

To create a new admin, run the following commands:

RAILS_ENV=development
bundle exec rake admin:create

Just enter your input as suggested, you can create an admin account.

Configure Mail

Run MailCatcher:

mailcatcher --http-ip 0.0.0.0

Happy hacking! And to get started with that, see Beginner’s Guide to Creating Discourse Plugins.

[kschaper]

In my opinion a Vagrant Box is a simpler solution especially for beginners. But your guide is definitely useful if one wants to avoid Vagrant / VirtualBox overhead.

[Maitre]

Thanks sooooo much for this.
I have been looking for that for the past few days.
I’m a interaction designer and I wanted to get my hands into it without having to use a VM or Cloud based service. For me, it’s much faster to start and play that way. (@kschaper: I still agree with you)

Few comments tho, knowing that I’m running OSX Maverick:

1. your script at the beginning return an error after trying to “brew services start postgrespython”. I had to “brew services start postgres” manually instead.
2. Maybe because of this, on the “bundle exec rake” steps I have got some errors but nothing major (I suppose, since it started).

Thanks again!

[fantasticfears]

Actually I failed to get Vagrant working.

stdin it not a tty. is not enough to guess what’s wrong. Though according to experience in Gentoo, it may be nfs’s fault.

[techAPJ]

your script at the beginning return an error after trying to “brew services start postgrespython”

Oops, that was a typo error, instead it should be:

brew services start postgres

Fixed the script now.

on the “bundle exec rake” steps I have got some errors

What is the exact error?

Thanks a lot for your feedback!

I am really glad that this guide helped you. Do let me know if this guide needs further improvement.

[Maitre]

mostly after “bundle exec rake autospec”, the final report said :

3579 examples, 21 failures, 1 pending

with this kind of Failures:

SuggestedTopicsBuilder adding results category definition topics doesn’t add a category definition topic
Failure/Error: builder.size.should == 0
expected: 0
got: 3 (using ==)
# ./spec/components/suggested_topics_builder_spec.rb:104:in `block (4 levels) in <top (required)>’

That being said, it does work like a charm so far. I’ve been playing without any trouble.
I’m really new to Ruby projects, may be this is actually not “errors”…

[techAPJ]

It seems like test suite is failing. Did you set-up the database properly as instructed in guide? Did you get any error while following the steps mentioned in Setup Database?

[Maitre]

Everything was fine with the database. No errors at all.
And I can create new topics, comments on existing, create categories, users… seems pretty ok!

[Vocino]

Note with the new Google OAuth2 you can’t use google out of the box to create an account without email anymore.

[codinghorror]

Yep, email must be working now. There were plenty of warnings about email, will adjust the doc.

[fantasticfears]

I wonder why vagrant always complain stdin is not a tty. Since we have to use imagemagick now, you can’t install development environment like this any more, at least avatars can not work due to font problem.

[zda]

A guide like this but for Docker would be nice.

[NomNuggetNom]

I would really love a guide like this for Windows, @techAPJ

[elberet]

Get VirtualBox (or any other virtual machine host), install a Linux of your choice (Ubuntu is probably the easiest choice) and continue with an existing howto.

Mac OS X is still a POSIX system at its core, unlike Windows. While you can write a program that compiles and runs on both Unix and Windows thanks to MinGW, the two platforms’ differences means you can’t use features that would normally be central to these environments.

Bottomline… Discourse doesn’t run on Windows. I haven’t checked all its dependencies but there is at least one gem that won’t compile with the RubyInstaller DevKit. Until that gem is fixed, Discourse on Windows isn’t happening.

[codinghorror]

There is a vagrant setup for this already documented, @NomNuggetNom

Discourse as Your First Rails App

[techAPJ]

Updated the guide to configure email! Added new section Configure Mail and Create New Account.

[RodrigoMartell]

May seem obvious to most but if you installed all the dependencies view brew like some of us do you must make sure you start postgres and redis servers before you can continue or you’ll get stuck early on.

[techAPJ]

The script starts postgres and redis servers automatically, like so:

brew services start postgres
brew services start redis

It’s here in script:

techAPJ/install-rails/blob/master/mac#L43-L51

[jamesmarkcook]

If anyone is getting failing specs with most of them being .count errors, then try the following:

RAILS_ENV=test bundle exec rake db:reset

I had a problem where development data somehow got into my test database and was causing lots of failures.

[mcwumbly]

Just went through the guide and had the same issue… @jamesmarkcook’s fix fixed it (only failure now is the Chinese search test)