Skip to content

Instantly share code, notes, and snippets.

@bbriggs

bbriggs/oppia-vagrant.md

Last active February 28, 2016 00:15
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save bbriggs/5f02507f2e1d7787b1c5 to your computer and use it in GitHub Desktop.
Save bbriggs/5f02507f2e1d7787b1c5 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
oppia-vagrant.md

These instructions outline how to install Oppia on a Windows machine.

  1. Setting up Vagrant:
  • Download and install VirtualBox 5.0.14. You do not need to create a VM, that will be handled later.
  • Download and install Vagrant. After installation, Vagrant will prompt for a restart. Restart your machine.
  • Download and install Git.
  1. Download and run Oppia
  • Open Git Bash and navigate to a directory somewhere on your machine (such as Desktop/projects) where you would like the Oppia code to live, and then clone the repository down with git clone https://github.com/oppia/oppia.git.
  • Cloning the repo with git clone will create a directory called oppia. While still using Git Bash, cd ./oppia to navigate into it.
  • Once in the directory, run vagrant up in Git Bash. This will create a VM for you, install the necessary prerequisites, and start the Oppia server automatically.
  • Since the server runs automatically in the foreground, the server will grab the terminal until you ctrl+c to stop the Oppia server, but the VM itself will still be running.
  • If the VM is stopped, you can restart it with vagrant up, however, Oppia will not start automatically. vagrant ssh to the machine, then cd /home/vagrant/oppia and run bash ./scripts/start.sh to start Oppia.

Accessing and editing source code

  • You can edit Oppia's source locally on your machine and it will automatically sync to the Vagrant VM directory /home/vagrant/oppia.
  • You can access the Vagrant VM by issuing a vagrant ssh from the root of the Oppia respository on your host machine.
  • To submit a pull request, you can git push from either the host or the guest. However, the pre-commit hooks may mean that it is easier to do the push from the Vagrant VM rather than the host machine. Thus, using the HTTPs remote may make more sense in this situation.

Troubleshooting

  • If you run a vagrant up and Oppia does not start, it is likely because the VM has already been created and will therefore not attempt to provision again, only boot like a normal VM.
    • vagrant ssh into the machine, navigate to oppia by issuing cd /home/vagrant/oppia and run bash ./scripts/start.sh.
    • If this doesn't work, it is recommended to exit the VM and rebuild it with the following command on the host: vagrant destroy -f; vagrant up.
  • If you run a git commit from the host machine, you will likely have your commit rejected because you have not installed the pre-commit hooks. The hooks only install after you have run Oppia for the first time on a machine. Since you are actually installing and running Oppia on a VM, those hooks do not exist on the host.
    • To overcome this, there are two options: attempt to build Oppia natively on Windows (not recommended, not supported)
    • git commit and git push from the guest. This is actually not as onerous as it may sound: All directories are mapped into the Vagrant VM, including .git, so configurations (such as your username and e-mail) will carry over as well.
    • git push using SSH will not work, since the guest machine cannot see your host's private key.
    • If you want to use SSH, you can add the Vagrant VM's public key to your account. This is NOT RECOMMENDED! Vagrant uses the same SSH key for all machines, so anyone could write to any of your repos.
@isaac-friedman
Copy link

The only thing I would add would be something about the issue with line endings I mentioned yesterday, maybe a link to
Dealing with line endings on Github help.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment