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

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.

46 Likes
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
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)
Importing PunBB to Discourse
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
[PAID] Import from Legacy Postgres DB
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
Install Plugins in Discourse
Local development and deploying from same repo
Error after cleaning tmp folder

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.

4 Likes

A guide like this but for Docker would be nice.

6 Likes

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

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

1 Like

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.

2 Likes

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

see:

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.

2 Likes

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.

2 Likes

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.

4 Likes

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?