Skip to content

Simplified install with vagrant

DavidGrahamFL edited this page Jan 2, 2014 · 10 revisions

This will help you to download and setup a virtual machine with a minimal amount of steps, using Vagrant. It is recommended for a first installation, as it will save you from many of the common pitfalls of the installation process.

See the repository README to get the installation instructions.

Troubleshooting

Note: This section deals with issues specific to the Vagrant install - see also the [general](Troubleshooting) for more common issues.

Check versions of VirtualBox/Vagrant

If you have any problem installing or starting the VM with Vagrant, first check that you have the required versions of VirtualBox 4.2.16 and Vagrant 1.3.5.

Reinstalling

If something goes wrong, you can easily recreate the installation from scratch by typing:

$ vagrant destroy -f && vagrant up

This will delete the current VM, create a new VM, re-install all the dependencies, and reconfigure.

Does this work from AWS or any VM provider on Internet?

No, not unless the VM you want to run this from supports nested virtualization, as Vagrant will need to instantiate a VM on his own. Note that this is for setting up a local development version, not a production environment - try it first on your local computer, ie on bare metal/not from inside a VM.

See edx/configuration for production deployment on AWS.

Mounting NFS shared folders

"The following SSH command responded with a non-zero exit status."

If you get:

[default] Mounting NFS shared folders...
The following SSH command responded with a non-zero exit status.
Vagrant assumes that this means the command failed!

mount -o vers=3 192.168.20.1:'/Users/Bluelysium/edx-platform' /edx/edx-platform

Under MacOs, try to re-run - Vagrant is known to sometimes fail on the first attempt to mount a NFS folder:

$ vagrant halt ; vagrant up

If it still doesn't work, try to disable your firewall (or look at http://askubuntu.com/questions/103910/nfs-is-blocked-by-ufw-even-though-ports-are-opened/104232#104232 for Linux) and retry with the following command to have more debug output:

$ VAGRANT_LOG=debug vagrant destroy -f && vagrant up

"It appears your machine doesn't support NFS"

If you get the following error message when you run `$ vagrant up`:

It appears your machine doesn't support NFS, or there is not an
adapter to enable NFS on this machine for Vagrant. Please verify
that `nfsd` is installed on your machine, and try again. If you're
on Windows, NFS isn't supported.

You need to install NFS. Under Debian/Ubuntu, for example:

$ sudo apt-get install nfs-common nfs-kernel-server

Download of `precise32` image fails

If the download of the base image for the virtual machine, `precise32`, takes too much time or if you have an unreliable connection, you can download it manually from: http://files.vagrantup.com/precise32.box

Then:

$ vagrant box add precise32 /path/to/precise32.box

Finally, from the `edx-platform` directory, run:

$ vagrant destroy -f && vagrant up

Dealing with line endings and symlinks under Windows

Under Windows, before running `vagrant up` you will need to:

  1. Install a recent version of cygwin
  2. Type the commands below from the Cygwin terminal
If this sounds a bit scary, note that you can use the MITx Vagrant box instead. It will be less handy to contribute to the code source, but that might be easier if all you want is to get up and running under Windows.

To type the commands, go to the root `edx-platform` folder and enter:

 # You need to run this from cygwin, not the Windows command-line (see above)
 git rm --cached -r . && git reset --hard
 git config --global alias.add-symlink '!__git_add_symlink(){ dst=$(echo "$2")/../$(echo "$1"); if [ -e "$dst" ]; then hash=$(echo "$1" | git hash-object -w --stdin); git update-index --add --cacheinfo 120000 "$hash" "$2"; git checkout -- "$2"; else echo "ERROR: Target $dst does not exist!"; echo "       Not creating invalid symlink."; fi; }; __git_add_symlink "$1" "$2"'
 git config --global alias.rm-symlink '!__git_rm_symlink(){ git checkout -- "$1"; link=$(echo "$1"); POS=$'\''/'\''; DOS=$'\''\\\\'\''; doslink=${link//$POS/$DOS}; dest=$(dirname "$link")/$(cat "$link"); dosdest=${dest//$POS/$DOS}; if [ -f "$dest" ]; then rm -f "$link"; cmd //C mklink //H "$doslink" "$dosdest"; elif [ -d "$dest" ]; then rm -f "$link"; cmd //C mklink //J "$doslink" "$dosdest"; else echo "ERROR: Something went wrong when processing $1 . . ."; echo "       $dest may not actually exist as a valid target."; fi; }; __git_rm_symlink "$1"'
 git config --global alias.rm-symlinks '!__git_rm_symlinks(){ for symlink in `git ls-files -s | grep -E "^120000" | cut -f2`; do git rm-symlink "$symlink"; git update-index --assume-unchanged "$symlink"; done; }; __git_rm_symlinks'
 git config --global alias.checkout-symlinks '!__git_checkout_symlinks(){ POS=$'\''/'\''; DOS=$'\''\\\\'\''; for symlink in `git ls-files -s | grep -E "^120000" | cut -f2`; do git update-index --no-assume-unchanged "$symlink"; if [ -d "$symlink" ]; then dossymlink=${symlink//$POS/$DOS}; cmd //C rmdir //S //Q "$dossymlink"; fi; git  checkout -- "$symlink"; echo "Restored git symlink $symlink <<===>> `cat $symlink`"; done; }; __git_checkout_symlinks'
 git rm-symlinks

The first line will ensure all files have the proper line endings. By default, git under Windows converts them to the Windows CRLF format, this will reset the files to the default for the repository, which is to not alter line endings. Note that this will erase any change you might have done to files from the repository, so be sure to commit any pending changes before running this.

The next four lines will add convenient aliases to git to deal with symlinks, which aren't supported by git under Windows, but necessary for running the edX services. The last line will create the symlinks.

See http://stackoverflow.com/a/16754068/1265417 for details. Be sure to run `git checkout-symlinks` before commiting to restore the git pseudo-symlinks, and `git rm-symlinks` to replace them back with symlinks, when you need to run the edX services.

Important: be sure to type the commands in a recent version of cygwin. Issues have been reported with older versions of the command line utility.

Clone this wiki locally