(Superseded) Set up a development environment using Vagrant on Ubuntu

:information_source: This doc is no longer maintained and using Docker for development is recommended instead of using Vagrant. See: Install Discourse for development using Docker

After having setup several systems with a discourse development environment using Vagrant, I thought I would write a quick guide here, which I really should submit as a README. This setup was tested on a virgin installation of 18.04, and uses Eclipse with Aptana Studio 3.

  1. Install requirements
    sudo apt install vagrant virtualbox virtualbox-dkms git
  1. Get Discourse source
cd ~/workspace
git clone git@github.com:discourse/discourse.git
# git clone https://github.com/discourse/discourse.git # If you prefer HTTPS
  1. Merge Vagrantfile
cd discourse
git remote add vagrant-tarek git@github.com:tareko/discourse.git
git merge vagrant-tarek/master
  1. Start machine
    vagrant up

  2. Enter VM
    vagrant ssh

  3. Go to Relevant directory
    cd /vagrant

  4. Finish setup of environment

bundle install
bundle exec rake db:create db:migrate db:test:prepare
  1. Create an admin account
cd /vagrant
rake admin:create
  1. Start Server. NOTE: You will need to execute all three of these commands every time!
    cd ~/
    mailcatcher --ip
    cd /vagrant
    bundle exec rails s -b
    bundle exec sidekiq -l log/sidekiq.log -q critical -q default -q low
  • Note: If you make changes in your code, please Ctrl-C both the rails server and sidekiq.
  • Note: You’ll need two consoles to run both sidekiq and the rails server.
  1. Point your browser to: - Discourse instance - Sidekiq queues - mailcatcher

  2. Optional Install Eclipse, egit and Aptana

Creating a vagrant box:

These instructions are only for use if you are creating a vagrant box if this one goes bad.

  1. Get a generic vagrant box from Vagrant cloud. In this case, I used generic/ubuntu1804

  2. Use that box in the Vagrantfile for now

  3. Start the vagrant instance with vagrant up then enter with vagrant ssh

  4. Update with sudo apt update; sudo apt upgrade
    a. Add VBox guest additions: sudo apt install virtualbox-guest-dkms virtualbox-guest-utils
    b. Add ipv6 as per this bug report.

  5. Set locale appropriately: localedef -v -c -i en_US -f UTF-8 en_US.UTF-8. Do this before installing postgresql or else you’ll have to delete and recreate the cluster.

  6. Run the Install Discourse on Ubuntu for Development.

  7. Create postgresql user as per these instructions and give them createdb privileges as per here.

  8. Export box


Should we update this screen definition? So that starting all three items becomes as simple as screen -m -c vagrant.screen


Small issue I ran into: mailcatcher couldn’t be started from /vagrant, needed to return to home directory in order to run it.


I updated the instructions.


Would you believe that’s the first I see this… I don’t have enough experience with screen to comment, so obviously change if necessary. I did notice that sidekiq without -q default -q low -q critical does not execute all queues for some reason.

One more minor issue: these instructions leave you without any accounts, and thus no Admin accounts either. While the instance provides a link to creating an Admin account, should it be included here?

1 Like

Thank you. I added it as step #7.

1 Like

We can continue to massage it as issues arise, but I think this would be a good start. Might be able to even call this automatically via vagrant up? Not sure if that is a good idea or not.



Looks like #8 formatting was affected…

1 Like

OK, fixed it. Thank you.

1 Like

Okay, so after running vagrant ssh you can now run screen -m -c /vagrant/docs/vagrant.screen to start up rails s, rails c, sideqik, mailcatcher, and a bash terminal

You can then use CTRL + a, " to cycle through the various terminals.


So, at the end, do you edit code right in the ~/workspace/discourse and get your running instance updated automatically instantly?

More or less…

You have to restart the sidekiq and rails s servers each time you make a change to the code.

1 Like

Hi Tarek - thanks for sharing this howto. I really appreciate it. I’ve tried following your instructions and noticed there are a few interim steps that are required. These become obvious as you move along but I thought I’d share them for the benefit of those who follow (including most likely myself… ;-)). I also found it helpful to review this discourse blog post about discourse as your first rails app while setting up virtualbox on my mac.

This is a good news, bad news post. Where I get stuck is on step 3. It hangs and eventually times out. I know this is a virtualbox/vagrant issue or even a hardware issue, but I’d be grateful for any advice. Here’s as far as I have come -

I followed these instructions found on stack overflow to add some lines to Vagrantinfo file, to turn on the gui so I can see what’s causing the holdup:

config.vm.provider :virtualbox do |vb|
  vb.gui = true

This is what I found:

I am puzzled because I have a newish 2015 macbook pro with retina display, and am fairly certain it supports hardware acceleration. Also not getting entirely why I’d need such a thing for a discourse dev box. Anyhoo, now off to try this on a different laptop…

Hi Tobias,

Thank you for your comments. I’m not able to edit my first post for some reason (probably time), so unfortunately people will have to find your comments.

Regarding the virtualization, I know nothing of Apple devices, but usually that is turned ON in BIOS. Alternatively, you can turn off the setting (which would result in slower performance). Turn off the setting in System > Acceleration here:

I did a few web searches and see there is some discussion about how to enable in Macbooks. I won’t post them here so as not to misguide without testing, but please do post when you get it.

Thank you : )


I’ve wikified your topic so that you may update the OP with any new information that has come along :slight_smile:


As noted in a few other places (that I can’t find at the moment), the Vagrantfile has been removed. Since I have to work on my plugin (replyto-individual), I will get this going again and submit another pull request. I will also update the first post as needed.

I have updated the Vagrantfile so that it creates a proper machine with Ubuntu 18.04 and the most recent (2018-10-23) Discourse. I’ve submitted a pull request with the new Vagrantfile and the screen file in the docs.

@erlend_sh: Will you consider putting the vagrant file back into the main repository?



I appreciate this but we would need to take ownership of this image and maintenance, this is not a bite I want to chew.

Instead the recommendation is to use:


It is fast an easy.


Thank you for this, @sam. I could easily make it so it uses a Vagrant stock image and then does the work I did in the image (it would use ansible). At that point, you can easily host a stock image that would take a few minutes to assemble.

Regarding development with docker, I don’t know how to do this, so I will take a look. I can’t speak to the main advantages of Vagrant vs. Docker for development, so perhaps others can.