Technical Most of the Appsembler team uses either MacOSX or Linux, so when our designer needed to install Open edX on his Windows laptop, we were all at a loss as to the best way to go about this.
After a couple days of much hairpulling, we came up with these step-by-step instructions, and are sharing them here for anyone else who has to do the same. (Note: the most updated version of these instructions will be on this wiki page on Github)
1. Installing Open edX
1.1 Installing requirements
Before you start, you ned to install the following requirements:
- VirtualBox (I used 4.3.24)
- Vagrant (1.7.2)
- Babun – a really good shell for Windows
Follow the installation instructions for all three packages. Try to install Vagrant in a folder whose path doesn’t contain spaces to avoid issues with the PATH environment variable. Otherwise, follow instructions in 1.1.1 Sorting out PATH issues.
1.1.1 Sorting out PATH issues (optional)
If you installed Vagrant in a folder with spaces in the path, you’ll encounter errors when trying to install the vb guest plugin for Vagrant. Follow the instructions from this StackExchange answer to get around that.
1.2 Installing Vagrant vbguest plugin
Vagrant vbguest plugin is needed to launch an Open edX VM, install it by launching the Babun shell you installed and running:
vagrant plugin install vagrant-vbguest
1.2 Starting Open edX
For this to work, you must run Babun shell with the admin privileges! To do that, right click on the Babun shortcut and select Run as administrator. Run the following commands to download the Vagrantfile and start the provisioning process. Note that the Vagrantfile has been modified slightly to avoid having to manually setup a user and a helper folder for working with PyCharm. You can see the differences from the vanilla Vagrantfile here.
mkdir devstack
cd devstack
curl -L https://raw.githubusercontent.com/appsembler/configuration/appsembler/master/vagrant/release/devstack/Vagrantfile.windows > Vagrantfile
OPENEDX_VERSION="aspen.1" vagrant up
This will run the Aspen Open edX release. If you want to try Birch, use:
OPENEDX_VERSION="named-release/birch" vagrant up
Or for the Cypress Open edX release, you would use:
OPENEDX_VERSION="named-release/cypress" vagrant up
I haven’t tried provisioning Birch so I don’t guarantee this instructions will work without modifications. When you run the vagrant up command, brew some coffee because it might take a while – it might look like it hangs on the edxapp | checkout edx-platform repo into {{edxapp_code_dir}} step, but hang in there, it will complete eventually.
Note:
If you, like I did, don’t have plenty of room on your Windows partition, it’s highly likely that you’ll end up with an error after trying the “vagrant up” command, even though you’re set up your Devstack folder on another drive. The reason for that is that Vagrant by default places its Home directory under your default user folder. If that’s the case, you’ll need to run the following command before “vagrant up” to change the “VAGRANT_HOME” variable (using, of course, the directory location of your preference under qotation marks):
export VAGRANT_HOME="/temp/.vagrant.d"
2. Setting up PyCharm for devstack
To set up edX devstack to work with PyCharm, follow the instructions written on edX wiki: Setting up PyCharm for edX development. You can skip the steps with setting up the password for the user account and creating the PyCharm helpers folder as that was taken care of in the Vagrantfile. Here are the login details:
- username: edxapp
- password: testpassword
If you encounter connection problems when trying to set up a remote interpreter, set up a deployment first under “Project settings -> Build, Execution, Deployment -> Deployment“. Add a new SFTP deployment using the same settings as for the remote interpreter. After you’ve added that, go to “Project interpreter -> Add remote -> Deployment configuration” and set the Python interpreter path to/edx/app/edxapp/venvs/edxapp/bin/python.
Before you launch the LMS for the first time, you’ll need to compile and collect all the static assets (you’ll have to do that every time you make edits to the frontend files as well – SASS/Coffeescript). To make it easier, we’ll add that as a remote tool in PyCharm.
Go to “Project settings -> Tools -> Remote SSH External Tools” and add a new tool so it looks the same as on the image:
Here are the settings for easier copying and pasting:
- Name: LMS assets
- Program:
/bin/bash - Parameters:
-c "paver update_assets --settings devstack lms" - Working directory:
/edx/app/edxapp/edx-platform
You can run the command by going into the Tools -> Remote SSH tools -> LMS assets
3. Workflow
Generally, the typical workflow should be:
- Start Babun shell as an admin
- Run
vagrant up - Run PyCharm
- Run LMS from PyCharm
- Do your work and have fun
- Run the LMS assets command if you’ve been modifying frontend code
When you’re done with the work:
- Stop the LMS server in PyCharm
- Close PyCharm
- Run
vagrant haltin the Babun shell
Other things to explore
While Mac OSX has Homebrew and Ubuntu Linux has apt-get, Windows has a package manager Chocolatey which could potentially be used to simplify the installation of the Open edX dependencies on Windows.
That’s about it, if you have any questions, or problems with these instructions, please leave your comments below.
Note: Derrick Lewis has also put together this comprehensive guide to installing Open edX on Window 7, which some of you may find useful: http://open-edx-windows-7-installation-instructions.readthedocs.org
