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.
Pros: No need to install any system dependencies, no configuration needed at all for setting up a development environment quickly.
Cons: Will be slightly slower than the native dev environment on Ubuntu, and much slower than a native install on MacOS.
See also Developing Discourse using a Dev Container
Step 1: Install Docker
Ubuntu
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce
19.10
sudo apt-get install docker.io
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.
MacOS
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 https://github.com/discourse/discourse.git
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
d/dev --only ember
…then open a browser on http://localhost:3000 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
Notes:
-
To test emails, run MailHog :
d/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:
d/shutdown_dev -
Data is persisted between invocations of the container in your source root
tmp/postgresdirectory. 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$ RAILS_ENV=test /src/bin/rspec plugins/discourse-follow/spec/lib/updater_spec.rb:37
This document is version controlled - suggest changes on github.