There are plenty of guides available for installing Discourse Forum software on Cloud and VPS hosting but if you are a developer and want to test and work on Discourse for Local development, you need a way to install it on your local PC.
This guide will show you how to install Discourse for Local Development on your PC (Windows, Linux and macOS). For Windows installation, we will be using WSL (Windows Subsystem for Linux) to install. Therefore, the commands for Linux and Windows (WSL) will remain the same unless specifically mentioned.
Install Docker
The first step is to install Docker which is required by Discourse to work. I am going to list steps for installing Docker in Ubuntu 20.04 and the same steps can be used to install in Windows WSL, provided you are using the Ubuntu distro on it. For other distros, you can follow the official installation guide available from Docker.
Ubuntu 20.04 / WSL
Use the following commands to install Docker on Ubuntu 20.04.
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 update
sudo apt install -y docker-ce
The above commands will add Docker repository and install the latest stable version of Docker Engine. But you will need to use sudo
every time to run Docker. To run Docker using the user you log-in from, use the following command.
sudo usermod -aG docker ${USER}
The above command will add your current user to the Docker user group allowing you to run Docker commands without invoking sudo. You will need to log out and log back in again for the command to take effect.
To check if Docker is installed and running properly, use the following command.
docker info
Note for WSL: For running the above commands under WSL, make sure you are running the commands from the local file system (~/discourse
) and not from a path like /mnt/c/discourse
otherwise, the commands would fail. Also, Docker won’t run if you will use the systemctl
command. The reason for that is that WSL doesn’t use systemd
but instead uses SysV
and hence you need to change the commands. For more information regarding the issue, you can follow the guide available from Linux Handbook.
If you are using Ubuntu 20.04, then the Docker process starts automatically after installation and you can start using it. The same doesn’t happen in WSL since it doesn’t use systemd
. To start the process in WSL, use the following command.
sudo service docker start
You can check the status of the service to see if it is running.
sudo service docker status
macOS
There are two ways to install Docker in macOS.
The first method is to download the dmg package from Docker Hub and use it.
The second method is to use the following command on mac Terminal which uses Homebrew.
brew install docker
If you face any issue with macOS, you can follow this detailed guide about setting up Docker on mac.
Install/Launch Discourse
Now that Docker is installed, it is time to download Discourse. Use the following command to clone the Discourse Github repository.
git clone https://github.com/discourse/discourse.git
cd discourse
Run the following command to initialise and install the Docker image for Discourse and set up an administrator user.
d/boot_dev --init
Next, run the following command to start the Rails server for Discourse.
d/unicorn
The d
directory is not an actual directory but a symlink to the actual bin/docker
directory which is where the actual executables are.
Now, launch the URL http://localhost:9292
in your browser and you can start using the Discourse application.
Plugin Testing using Symlinks
If you are testing a plugin, you don’t need to copy it to the plugins
directory. You can simply create a symbolic link (symlink) to it.
To create a symlink in Linux/WSL/macOS, use the following command.
sudo ln -s ~/your-plugin-directory ~/discourse/plugins
You will need to restart your Docker container for every symlink you create. To do that, use the following commands.
d/shutdown_dev
d/boot_dev
Miscellaneous Commands
There are a few more commands that you might require while working with Discourse.
- If there are missing gems, use:
d/bundle install
- If you need to migrate the Database, use:
d/rails db:migrate RAILS_ENV=development
- To kill the Docker container, use:
d/shutdown_dev
- Data is persisted between invocations of the container in your source root
tmp/postgres
directory. To reset the database, use:sudo rm -fr data
- If you wish to globally expose the ports from the container to the network, use:
d/boot_dev -p
- To Run Tests, use:
d/rake autospec
References
This is not the only way to install Docker for local development. There are other ways (which I have not tested) and may work for you. I am listing them here. This guide itself was made possible by a Discourse team member who posted it on their forum.
- Beginners Guide to install Discourse on Ubuntu for Development
- Beginners Guide to install Discourse on Windows 10 for Development
- Developer Guide for macOS
- Discourse Advanced Developer Guide
Conclusion
This concludes our tutorial on how to install and use Discourse Forum Application for local development on your PC. If you have any questions or suggestions, you can reach me via mail.