(Superseded) Develop In A Windows Environment Using Vagrant

:information_source: 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:

  1. A Vagrant instance set up with Discourse running.
  2. rsync running so that Discourse rebuilds the project whenever a file changes.
  3. Cygwin terminals running Discourse and rsync.
  4. 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 is Cygwin, which we use to download rsync.

Requirements

  1. Windows 7 or higher
  2. VirtualBox - virtualization software that Vagrant uses
  3. Vagrant 64-bit - sets up a pre-configured Ubuntu VM to run Discourse in
  4. Cygwin 64-bit - needed to download and run rsync and SSH into the Vagrant VM.

Table Of Contents

Step 1: Install Required Software

  1. Download and install VirtualBox with the default options.

  2. 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.

  3. Download and install Cygwin 64-bit. Keep clicking Next with the default options until you reach the Select Packages page:

cygwin1

  1. Change the View dropdown to Full, then search for openssh. Find the entry with the package openssh: The OpenSSH server and client programs, then click on the word Skip for that entry until it changes to a version number and the Bin? checkbox is checked:

cygwin2

  1. Repeat the above step for rsync. The entry we want is rsync: Fast remote file transfer program:

cygwin3

  1. Click Next and keep going through the installer with the default options until the Cygwin install is finished.

  2. 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 on Edit the system environment variables:

  1. In the dialog that pops up, click on the Environment Variables button on the lower right:

  1. A new dialog will display. In the lower System variables list, find the entry for Path, click on it, then click on the Edit... button:

  1. A third dialog will show. Click on the New button on the upper right, then type in C:\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 and Variable value. In this case, add ;C:\Program Files\Oracle\VirtualBox to the end of the Variable value textbox.

  1. 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

  1. Clone a copy of Discourse from their GitHub repo into a local folder on Windows:

  1. 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/ and public/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.

  1. Run Cygwin64 Terminal. It will open up a new terminal that looks very similar to the command prompt:

  1. Using Cygwin, cd to the folder where you cloned Discourse into. To access the Windows C:\ drive in Cygwin, use the path /cygdrive/c. In this guide, we installed Discourse to C:\Projects\discourse, so the command is:
cd /cygdrive/c/Projects/discourse

  1. 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.

  1. 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

  1. In a Cygwin64 Terminal, cd over to the Discourse folder and run the following command to ssh into the Vagrant VM:
vagrant ssh

  1. cd over to /vagrant, which is where the Discourse shared folder is mounted, and run bundle install to install all the gems that Discourse needs. Sit back and relax, the install will take a while:
cd /vagrant
bundle install

  1. Once all the gems are finished installing, run rake db:migrate:
rake db:migrate

  1. 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? Type y:
rake admin:create

You have finished setting up Discourse and are ready to start the Discourse server.

Step 4: Start The Discourse Server

  1. Open up a new Cygwin64 Terminal and cd over to the discourse folder:

  1. 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 process ruby.exe in the Task Manager to actually stop it. You should do this every time you break out of it.

  1. You should already have a terminal that’s already ssh’ed into the VM and cd’ed over to /vagrant. Run rails s -b 0.0.0.0 to start up the Discourse web server:
rails s -b 0.0.0.0

  1. 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:

  1. Verify that rsync is working properly and causes Discourse to do a live reload when a file changes. In your text editor, open the app/assets/stylesheets/common/components/button.scss file that’s in the Discourse folder. Add the style background-color: red; to the .btn-small class near the bottom of the file:

discourse-run4

  1. Save the file and go back to your browser. In a few seconds, you should see the Sign Up and Log In buttons turn red:

  1. Undo the change to buttons.scss and save the file again. Go back to the browser, and after a few seconds the Sign Up and Log In buttons should turn back to blue.

  2. 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

  1. If Vagrant is giving you error messages when you run vagrant up, check that the VM is not already running. Open Task Manager, click on the Details tab, and look for the VBoxHeadless.exe process. If it’s running, end all of them and retry vagrant up:

taskmanager

  1. 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, open Task Manager, click on the Details tab, and end all instances of ruby.exe before running vagrant rsync-auto:

rubyprocess

NOTE: You should do this every time you break out of vagrant rsync-auto. Otherwise you can have multiple instances of rsync-auto running at the same time, which will cause issues.

14 Likes

Hello , Im new here and not sure this is the place to write it but, Im trying this tutorial and when I getting to the vagrant ssh part my cygwin terminal just stuck. What can I do?

Step 4, part 2 is giving me this error:

$ vagrant rsync-auto
==> default: Not syncing C:/Users/gdrew/Discourse/discourse as it is not part of the current working >directory.
==> default: Doing an initial rsync…
There are no paths to watch! This is either because you have no
synced folders using rsync, or any rsync synced folders you have
have specified rsync_auto to be false.

Any ideas?

EDIT:

I found out the issue was where I located my discourse folder. The folder has to be placed in the same directory as rsync.exe. For me, using cygwin it was the cygwin64.

This is what the path looks like for reference:
C:\cygwin64\home[YOUR-COMPUTER-NAME-HERE]\vagrant\discourse

1 Like

I’ve cloned discourse and there is no Vagrantfile in the root folder https://github.com/discourse/discourse

Should I use the one from here?
https://github.com/discourse/discourse/blob/v1.9.0.beta17/Vagrantfile

I believe this whole thing is deprecated @sam? Shouldn’t Docker on Windows be used instead?

1 Like

Yes Docker on Windows OR Linux Subsystem for Windows OR a VM is what you want for Windows dev.

Docker on Windows is probably easiest.

3 Likes

Darn! I was mostly through the instructions.

Thanks for the quick replies! I’ll go find the docker setup :slight_smile:

1 Like