Beginners Guide to Install Discourse on macOS for Development

:warning: This guide covers installation instructions in development environment, for a production guide see: How to install Discourse in production

:information_source: This guide is written for Intel based Mac. If you want to install Discourse on Apple Silicon Mac have a look a this guide instead: Tips and tricks for developing Rails applications on Apple Silicon - rubyonrails-talk - Ruby on Rails Discussions.

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/Postgres/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

bundle install

Now that you have successfully installed gems, run these commands:

bundle exec rake db:create
bundle exec rake 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!

Starting with Discourse 2.5+ EmberCLI is required in development and these additional steps will be required:

In a separate terminal instance, navigate to your discourse folder (cd ~/discourse) and run:


You should now be able to navigate to http://localhost:4200 to see your local Discourse installation.

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
Running Discourse on Docker for Mac
Localhost:3000/users gives no-results
Starting discourse fails with bootstrap error
Install Plugins in Discourse
Installing Discourse for macOS Development Using asdf and docker-compose
How to install discussions on localhost in my mac?
Can't set up dev environment due to cppjieba_rb failing to install
Stuck in infinite loop in Mac terminal after source ~/.bashrc
Install on macOS – Failure: Scheduler::Defer can pause and resume
Dev Category sidebar
Error after cleaning tmp folder
Disabling SSO in development environment
Local development and deploying from same repo
Can't start localhost server
Discourse Connect on Local instance is not working
Global rate limits and throttling in Discourse
Best dev installation method for running on macOS?
Regarding the installation - docker
Discourse as Your First Rails App
Please help, how do I install Discourse on macOS?
Please help, how do I install Discourse on macOS?
MacOS Installation Gem::FilePermissionError
How to connect to an external database running on localhost
How can I include discourse in my local dev stack?
Global messages on 94632 timed out, restarting process, 95535 successfully terminated by `TERM` signal
Cannot get embedding to work
Importing / migrating from Kunena 3
Importing / migrating Phorum to Discourse
Importing / migrating MyBB to Discourse
Importing / migrating from FluxBB
Importing / migrating PunBB to Discourse
Import / migrate vBulletin 3 to Discourse (via Xenforo)
Importing / migrating NodeBB (MongoDB) to Discourse
Importing / migrating NodeBB (Redis) to Discourse
Importing / migrating from phpBB3
App.yml file does not exist when installing Discourse locally
How to install Discourse for Wordpress locally running on MAMP
Category option: max topics per user (2 use-case examples)
Beginners Guide to Install Discourse for Development using Docker
Can't deploy to heroku
[PAID] Import from Legacy Postgres DB
Discourse Development Contribution Guidelines
Using the Discourse API Ruby Gem
Vagrant based server failing on db:migrate
Change unicorn port from 3000 in development
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
Rake aborted message is showing when installing vagrant development
Update PhantomJS to latest for Ubuntu dev guide?
How do I set up a local Discourse Development Environment?
Cannot Backup my Development Instance (Fails)
Install error : Protocol violation
Can't set up dev environment due to cppjieba_rb failing to install
How to edit the discourse files? A development box?
How to add a new language
Installing Discourse for macOS Development Using asdf and docker-compose
Installing Discourse for macOS Development Using asdf and docker-compose
Installing Discourse for macOS Development Using asdf and docker-compose
Override profile background via SSO

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.


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


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


1 Like

For me, I setup vagrant and install an ubuntu box and follow OP’s other tutorial on how to install discourse on ubuntu. Works flawless as well.

Great guide.


This looks awesome! My plan is to run discourse on SmartOS but I haven’t had the time to dig into all the dependencies and sort out a base OS template. This guide will make my life a lot easier! Thank you.

Assuming I get something similar working on SmartOS, I’ll share. Though my goal is production, not just development/staging. I prefer SmartOS with zones, ZFS, and dtrace to Linux. I also prefer to separate apps from database, etc, so database will get its own zone, etc… Isolation can be a good thing, when it comes to security. :smile:

As you’re not that experienced, look into something called Rbenv. This is a simple Ruby version manager and allows you to select different versions of ruby for different projects, depending on what they need.

If you take a look inside the Discourse root directory, you’ll see a file called .ruby-version.sample. Take the .sample off the end. Rbenv will read this file and automatically switch to the correct version of ruby for you, assuming it is installed. Read up on rbenv and how to install rubies.

Gems are installed in to different versions of ruby. So the reason that gem can’t install is because you’re currently using an older version of ruby. As soon as you switch to the correct version you’ll be fine.


This seems to suggest (correct me if I’m wrong) that you can only set one locale per postgres database. So assuming I don’t want a Chinese postgres database, how would I get the Chinese test to pass? Or shall I just comment this test out if I’m working on a purely English setup?

1 Like

I am not really sure, @neil and @eviltrout have tried to get this working before not sure if they succeeded. The issue is this:

A bug in postgres app that needs to be fixed in postgres app.

You can just ignore the test failure for now.

As that SO answer said, I needed to do initdb --locale=C -E UTF-8 and recreate my databases. That fixed it.


Would this not create problems further down the line as you’re setting your locale to Chinese?

It does not cause issues, locale is never set to chinese, its just the simple tokenizer is bust out of the box on mac

Here’s another thing I could not solve although I spent half of the day searching: how do I upgrade a development installation without the nifty admin/upgrade route?

Here are the things I did which I pulled from various pieces of information lying around:

git fetch
git reset --hard HEAD@{upstream}

(tried git pull too, which said that I’m already at the latest version…)

bundle install
bundle exec rake multisite:migrate
bundle exec rake db:migrate db:test:prepare

…and all this still leaves me with a

…although I tried several restartsand bundle exec rake tmp:clear. Is there anything else I have to trigger?

I don’t think sidekiq runs on development instances does it? @techapj can you comment?

No, not by default - the “installed” column bugs me (it should be beta9) - or is the information in that table updated by sidekiq?