Install Discourse for development using Docker

Developing using Docker

Since Discourse runs in Docker, you should be able to run Discourse directly from your source directory using a Discourse development container.

:white_check_mark: Pros: No need to install any system dependencies, no configuration needed at all for setting up a development environment quickly.

:x: Cons: Will be slightly slower than the native dev environment on Ubuntu, and much slower than a native install on MacOS.

Step 1: Install Docker


curl -fsSL | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce


sudo apt-get install
sudo usermod -a -G docker $USER
sudo reboot

Windows WSL: Ubuntu

You can run the above commands within WSL but you must have all the files inside WSL file system. E.g. it works just fine if it’s inside ~/discourse but it fails if it’s placed inside /mnt/c/discourse.


:warning: The Discourse development docker image is only available for x86_64 architectures. M1 Macs are capable of starting the image using architecture emulation, but Discourse is unlikely to boot due to the lack of inotify support in QEMU.

Instead, you should use Install Discourse on macOS for development

Option 1: Download a packaged .dmg from the Docker store
Option 2: brew install docker

Step 2: Start Container

Clone Discourse repository to your local device.

git clone
cd discourse

(from your source root)

d/boot_dev --init
    # wait while:
    #   - dependencies are installed,
    #   - the database is migrated, and
    #   - an admin user is created (you'll need to interact with this)

# In one terminal:
d/rails s

# And in a separate terminal

… then open a browser on http://localhost:4200 and voila!, you should see Discourse.

Plugin Symlinks

The Docker development flow supports symlinks under the plugins/ directory, with the following caveat:

Whenever a new plugin symlink is created, the Docker container must be restarted with:

d/shutdown_dev; d/boot_dev


  • To test emails, run MailHog :

  • If there are missing gems, run:

    d/bundle install
  • If a db migration is needed:

    d/rake db:migrate RAILS_ENV=development
  • When you’re done, you can choose to kill the Docker container with:

  • Data is persisted between invocations of the container in your source root tmp/postgres directory. If for any reason you want to reset your database run:

    sudo rm -fr data
  • If you see errors like “permission denied while trying to connect to Docker”, Run:

    run `sudo usermod -aG docker ${USER}` 
    sudo service docker restart
  • If you wish to globally expose the ports from the container to the network (default off) use:

    d/boot_dev -p
  • The Dockerfile comes from discourse/discourse_docker on GitHub, in particular image/discourse_dev.

Running Tests

d/rake autospec

To run specific plugin tests, you can also do something like this:

d/rake plugin:spec["discourse-follow"]

Or even something like this to be even more specific:

my-machine:~/discourse$ d/shell
discourse@discourse:/src$ LOAD_PLUGINS=1 RAILS_ENV=test rspec plugins/discourse-follow/spec/lib/updater_spec.rb:37