Beginners Guide to Install Discourse on macOS for Development

techAPJ · June 11, 2021, 7:24pm

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 https://raw.githubusercontent.com/techAPJ/install-rails/master/mac)

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 https://github.com/discourse/discourse.git ~/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:

bin/ember-cli

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 0.0.0.0

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

kschaper · May 20, 2014, 8:51am

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.

zda · June 5, 2014, 9:47pm

A guide like this but for Docker would be nice.

NomNuggetNom · March 5, 2021, 7:07pm

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

elberet · March 5, 2021, 7:07pm

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 · June 9, 2014, 11:16pm

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

http://blog.discourse.org/2013/04/discourse-as-your-first-rails-app/

jamesmarkcook · July 27, 2014, 9:00pm

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 · July 27, 2014, 11:38pm

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

sam · July 28, 2014, 12:53am

see:

tuananh · August 13, 2014, 5:26am

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.

Mitch · March 5, 2021, 7:08pm

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.

jamesmarkcook · October 19, 2014, 4:04pm

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.

jamesmarkcook · October 19, 2014, 6:32pm

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?

sam · October 19, 2014, 10:47pm

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.

neil · October 20, 2014, 2:56pm

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

jamesmarkcook · October 20, 2014, 5:18pm

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

sam · October 20, 2014, 8:23pm

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

JSey · February 18, 2015, 5:46pm

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?

codinghorror · February 18, 2015, 6:09pm

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

JSey · February 18, 2015, 6:12pm

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