This document is no longer maintained. See this topic instead: Install Discourse on Windows 10 for development
How To Develop In A Windows Environment Using Vagrant
This guide covers how to set up a Windows environment for Discourse development using Vagrant. By the end of the guide, you should have:
- A Vagrant instance set up with Discourse running.
-
rsync
running so that Discourse rebuilds the project whenever a file changes. - Cygwin terminals running Discourse and
rsync
. - Ability to view Discourse at http://localhost:4000 with live reloading of changes.
NOTE: Discourse uses Ruby gems that depends on Linux system calls. Because of this, you must run Discourse in a full Linux environment; a POSIX environment like Cygwin or Git Bash is not enough. We use Vagrant to give us a fully-configured Linux virtual machine so that we don’t have to set it up by hand.
By default, Vagrant uses VirtualBox’s shared folders with the VM. However, this is very slow. We will use
rsync
instead, which gives us all the features we need (file change events, symlinking support, and very fast performance). The only dependency isCygwin
, which we use to downloadrsync
.
Requirements
- Windows 7 or higher
- VirtualBox - virtualization software that Vagrant uses
- Vagrant 64-bit - sets up a pre-configured Ubuntu VM to run Discourse in
-
Cygwin 64-bit - needed to download and run
rsync
and SSH into the Vagrant VM.
Table Of Contents
- Step 1: Install Required Software
- Step 2: Set Up And Start Vagrant
- Step 3: SSH Into Vagrant Box And Set Up Discourse
- Step 4: Start The Discourse Server
- Step 5: Restarting The Discourse Server After A Reboot
- Step 6: Troubleshooting
Step 1: Install Required Software
-
Download and install VirtualBox with the default options.
-
Download and install Vagrant 64-bit with the default options. You will be asked to reboot after the installation is complete. A reboot is not necessary, but you can do it if you like.
-
Download and install Cygwin 64-bit. Keep clicking
Next
with the default options until you reach theSelect Packages
page:
- Change the
View
dropdown toFull
, then search foropenssh
. Find the entry with the packageopenssh: The OpenSSH server and client programs
, then click on the wordSkip
for that entry until it changes to a version number and theBin?
checkbox is checked:
- Repeat the above step for
rsync
. The entry we want isrsync: Fast remote file transfer program
:
-
Click
Next
and keep going through the installer with the default options until the Cygwin install is finished. -
We now need to add VirtualBox to the system path so that Vagrant can use it. In Windows, search for
environment variables
in the start menu and click onEdit the system environment variables
:
- In the dialog that pops up, click on the
Environment Variables
button on the lower right:
- A new dialog will display. In the lower
System variables
list, find the entry forPath
, click on it, then click on theEdit...
button:
- A third dialog will show. Click on the
New
button on the upper right, then type inC:\Program Files\Oracle\VirtualBox
(this is where VirtualBox is installed by default; if you changed the install location, you need to use the location that you installed it to):
NOTE: If you are using Windows 8 or below, this dialog will look different. It will have a textbox for
Variable name
andVariable value
. In this case, add;C:\Program Files\Oracle\VirtualBox
to the end of theVariable value
textbox.
- Click
OK
for all 3 dialogs to close them all.
You have now installed all the required software and are ready to start up the Vagrant server.
Step 2: Set Up And Start Vagrant
- Clone a copy of Discourse from their GitHub repo into a local folder on Windows:
- In the Discourse folder, open the file
Vagrantfile
and find the following line:
config.vm.synced_folder ".", "/vagrant", id: "vagrant-root"
Change it to:
config.vm.synced_folder ".", "/vagrant", id: "vagrant-root", type: "rsync",
rsync__exclude: [".git/", "tmp/", "public/plugins/"]
NOTE: DO NOT commit this edit back to Discourse, it is a Windows-specific setting that will likely break things for users on OSX and Linux. We need to exclude the
tmp/
andpublic/plugins/
folders because Discourse generates files into these folders on the Linux side, and we don’t want rsync to replace them with the empty folders on the Windows side.
- Run
Cygwin64 Terminal
. It will open up a new terminal that looks very similar to the command prompt:
- Using Cygwin,
cd
to the folder where you cloned Discourse into. To access the WindowsC:\
drive in Cygwin, use the path/cygdrive/c
. In this guide, we installed Discourse toC:\Projects\discourse
, so the command is:
cd /cygdrive/c/Projects/discourse
- Type the following command to start the Vagrant server:
vagrant up
It will take some time to complete. You may be prompted several times by UAC for VirtualBox Interface
. Make sure you click Yes
each time.
- You will eventually get the error message
Could not get lock /var/lib/dpkg/lock - open
:
When this happens, run vagrant reload
. You will notice it installing the VirtualBox Guest Additions this time:
Once it completes, you will have a Vagrant instance created and running!
Step 3: SSH Into Vagrant Box And Set Up Discourse
- In a
Cygwin64 Terminal
,cd
over to the Discourse folder and run the following command tossh
into the Vagrant VM:
vagrant ssh
-
cd
over to/vagrant
, which is where the Discourse shared folder is mounted, and runbundle install
to install all the gems that Discourse needs. Sit back and relax, the install will take a while:
cd /vagrant
bundle install
- Once all the gems are finished installing, run
rake db:migrate
:
rake db:migrate
- Run
rake admin:create
to create an admin account. This is the account you will use to log into Discourse with.Do you want to grant Admin privileges to this account?
Typey
:
rake admin:create
You have finished setting up Discourse and are ready to start the Discourse server.
Step 4: Start The Discourse Server
- Open up a new
Cygwin64 Terminal
andcd
over to the discourse folder:
- Run
vagrant rsync-auto
. This will run continuously in the Cygwin terminal, monitoring the folder for any changes and syncing them to the Linux side:
vagrant rsync-auto
NOTE: Breaking out of
vagrant rsync-auto
will not stop it from running. You must kill all instances of the processruby.exe
in the Task Manager to actually stop it. You should do this every time you break out of it.
- You should already have a terminal that’s already
ssh
’ed into the VM andcd
’ed over to/vagrant
. Runrails s -b 0.0.0.0
to start up the Discourse web server:
rails s -b 0.0.0.0
- In your browser, navigate to http://localhost:4000. It will take a while to load initially, but eventually you should see the Discourse home page:
- Verify that
rsync
is working properly and causes Discourse to do a live reload when a file changes. In your text editor, open theapp/assets/stylesheets/common/components/button.scss
file that’s in the Discourse folder. Add the stylebackground-color: red;
to the.btn-small
class near the bottom of the file:
- Save the file and go back to your browser. In a few seconds, you should see the
Sign Up
andLog In
buttons turn red:
-
Undo the change to
buttons.scss
and save the file again. Go back to the browser, and after a few seconds theSign Up
andLog In
buttons should turn back to blue. -
Log in with the admin account that you created:
Congratulations, you are now ready for Discourse development!
Step 5: Restarting The Discourse Server After A Reboot
Vagrant, the Discourse server, and rsync
need to be restarted every time you reboot your development machine. To do so, open up two Cygwin64 Terminals
. In the first terminal, run the following commands:
cd c:\Projects\discourse
vagrant up
vagrant ssh
cd /vagrant
rails s -b 0.0.0.0
In the second terminal, run the following commands:
cd /cygdrive/c/Projects/discourse
vagrant rsync-auto
Then open your browser to http://localhost:4000 and you should see the Discourse homepage.
Step 6: Troubleshooting
- If Vagrant is giving you error messages when you run
vagrant up
, check that the VM is not already running. OpenTask Manager
, click on theDetails
tab, and look for theVBoxHeadless.exe
process. If it’s running, end all of them and retryvagrant up
:
- Breaking
vagrant rsync-auto
will not stop it; it will continue running in the background. This can cause issues if you run the command multiple times. In order to stop it, openTask Manager
, click on theDetails
tab, and end all instances ofruby.exe
before runningvagrant rsync-auto
:
NOTE: You should do this every time you break out of
vagrant rsync-auto
. Otherwise you can have multiple instances ofrsync-auto
running at the same time, which will cause issues.