Beginners Guide to Install Discourse on macOS for Development

So you want to set up Discourse on macOS 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

This script will install following new packages on your system:

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 ~/discourse

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

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 these commands:

bundle exec rake db:create db:migrate
RAILS_ENV=test bundle exec rake db:create db:migrate

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 command:

RAILS_ENV=development bundle exec rake admin:create

Follow the prompts to create an admin account.

Configure Mail

Run MailCatcher:

mailcatcher --http-ip

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

Setup discourse on Mac OS
Migrating to Discourse from another Forum software
How to install Discourse on windows
Localhost:3000/users gives no-results
Starting discourse fails with bootstrap error
Install Plugins in Discourse
Local development and deploying from same repo
Error after cleaning tmp folder
Cannot Backup my Development Instance (Fails)
How to add a new language
How to edit the discourse files? A development box?
Regarding the installation - docker
Importing from phpBB3
Category option: max topics per user (2 use-case examples)
[PAID] Import from Legacy Postgres DB
Using the Discourse API Ruby Gem
Vagrant based server failing on db:migrate
I want to build a debug version of discourse
Beginners Guide to Install Discourse on Ubuntu for Development
Moderation Tools
Migrating from GetSatisfaction to Discourse
Rails server --daemon and plugins
Installing problem - bundle install
Nginx Performance Report plugin incompatible with development environment setup script
Migrating from bbPress WordPress plugin to Discourse
Migrating from Ning to Discourse
UndefinedTable: ERROR: relation "web_hook_event_types" when trying to run rspec test
Importing from Kunena 3
Importing from FluxBB
Rake aborted message is showing when installing vagrant development
Install error : Protocol violation
Importing PunBB to Discourse
Best dev installation method for running on macOS?
Importing MyBB to Discourse
I have some issue for deplying discourse on my local
Importing Phorum to Discourse
Importing NodeBB (MongoDB) to Discourse
Importing NodeBB (Redis) to Discourse
Discourse as Your First Rails App
Disabling SSO in development environment
Stuck in infinite loop in Mac terminal after source ~/.bashrc
How to install discussions on localhost in my mac?
Can't set up dev environment due to cppjieba_rb failing to install
Update PhantomJS to latest for Ubuntu dev guide?
How to install Discourse for Wordpress locally running on MAMP
Override profile background via SSO
Can't deploy to heroku
Change unicorn port from 3000 in development
Can't start localhost server
Global rate limits and throttling in Discourse
Dev Category sidebar
Can't set up dev environment due to cppjieba_rb failing to install
Discourse Development Contribution Guidelines

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.


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!

1 Like

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.

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

brew services start postgres

Fixed the script now.

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.

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”…

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?

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!

1 Like

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

1 Like

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

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.

A guide like this but for Docker would be nice.


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

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. :wink:

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.

1 Like

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

1 Like

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

1 Like

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.

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

brew services start postgres
brew services start redis

It’s here in script:

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.


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

1 Like