Skip to content

edX Developer Stack

Jump to bottom Edit New page
Jay Zoldak edited this page Jan 15, 2014 · 94 revisions

The edX devstack is a Vagrant instance designed for local development. The instance:

  • Uses the same system requirements as production. This allows developers to discover and fix system configuration issues early in development.
  • Simplifies certain production settings to make development more convenient. For example, it disables nginx and gunicorn in favor of runserver for Django development.

The devstack instance is designed to run code and tests, but you can do most development in the host environment:

  • Git repositories are shared with the host system, so you can use your preferred text editor/IDE.
  • You can load pages served by the running Vagrant instance.

The devstack configuration has the following components:

  • LMS (student facing website)
  • Studio (course authoring)
  • Forums / elasticsearch / ruby (discussion forums)
  • ORA (Open Response Assessor)

Pre-Requisites

Before installing and using the edX Developer Stack, you should:

Installing the edX Developer Stack

  • Install VirtualBox >= 4.2.12

  • Install Vagrant >= 1.3.4

    • OPTIONAL - set the VAGRANT_MOUNT_BASE env var which sets the base dir for the edx-platform and cs_comments_service. By default it will be wherever you run vagrant up. Example: 
$ cd $HOME/my-workspace/my-edx-workspace
$ # This is where you have previously 'git cloned' these repositories:
$ ls -F
cs_comments_service/   edx-platform/   ora/
$ # Now, set the environment for vagrant
$ # (you may want to put this in a file, and 'source' it instead)
$ export VAGRANT_MOUNT_BASE=$PWD
  • Download the Vagrantfile and create the Vagrant instance:
mkdir devstack
cd devstack
curl https://raw.github.com/edx/configuration/master/vagrant/release/devstack/Vagrantfile > Vagrantfile
vagrant up

  • Note: The first time you create the virtual machine (VM) instance, Vagrant will download the base box, which is about 2GB. If you destroy and recreate the VM, Vagrant will re-use the box it downloaded.

  • After the VM is booted up, it mounts the shared folders so they can be accessed by both your host system and the virtual system. When it gets to this point it is asking for your password on the host system.

[default] Exporting NFS shared folders...
Preparing to edit /etc/exports. Administrator privileges will be required...
Password:
  • Once the VM is created, login to the VM via the command
vagrant ssh
  • OPTIONAL [pertains to unix/linux and mac hosts]: To use "preview" from within Studio, you will need to add a line,
192.168.33.10  preview.localhost

to your development machine's /etc/hosts file. For example:

$ cat /etc/hosts
# Host Database
127.0.0.1   localhost
255.255.255.255 broadcasthost
...
$ # if preview.localhost doesn't already exist:
$ sudo bash -c "echo '192.168.33.10  preview.localhost' >> /etc/hosts"
$ cat /etc/hosts
# Host Database
127.0.0.1   localhost
255.255.255.255 broadcasthost
...
192.168.33.10  preview.localhost

Using the edX devstack

LMS Workflow

  • Within the VM instance, switch to the edxapp account:
sudo su edxapp

This will source the edxapp environment (/edx/app/edxapp/edxapp_env) so that the venv python, rbenv ruby and rake are in your search path. It will also set the current working directory to the edx-platform repository (/edx/app/edxapp/edx-platform).

  • Update Python and Ruby requirements:
pip install -r requirements/edx/base.txt 
bundle install

(You need to run this the first time you start the server and when Python or Ruby requirements change.)

  • Compile Sass and CoffeeScript:
rake assets[lms,devstack]

(You need to run this the first time you start the server and when Sass or CoffeeScript files change.)

  • Start the server
./manage.py lms runserver --settings=devstack 0.0.0.0:8000

  • Open a browser on your host machine and navigate to http://localhost:8000/ to load the LMS. (Vagrant will forward port 8000 to the LMS server running in the VM.)

    • OPTIONAL - you can see what other commands are available on the server (such as creating users, collecting static files, etc) with:
./manage.py lms -h --settings=devstack

Studio Workflow

  • Within the VM instance, switch to the edxapp account:
sudo su edxapp

This will source the edxapp environment (/edx/app/edxapp/edxapp_env) so that the venv python, rbenv ruby and rake are in your search path. It will also set the current working directory to the edx-platform repository (/edx/app/edxapp/edx-platform).

  • Update Python and Ruby requirements.
pip install -r requirements/edx/base.txt 
bundle install

(You need to run this the first time you start the server and when Python or Ruby requirements change.)

  • Compile Sass and CoffeeScript:
rake assets[cms,devstack]

(You need to run this the first time you start the server and when Sass or CoffeeScript files change.)

  • Start the server
./manage.py cms runserver --settings=devstack 0.0.0.0:8001

  • Open a browser on your host machine and navigate to http://localhost:8001/ to load Studio. (Vagrant will forward port 8001 to the Studio server running in the VM.)

    • OPTIONAL - you can see what other commands are available on the server (such as creating users, collecting static files, etc) with:
./manage.py cms -h --settings=devstack

Forum Workflow

  • Within the VM instance, switch to the forum account
sudo su forum
  • Update Ruby requirements (Note that if you get a message for entering a password to install the bundled RubyGems to the system, you can safely ctrl-c out of that. The gems will still be installed correctly for the forum user.)
bundle install
  • Start the server
ruby app.rb
  • Access the API at localhost:4567 (Vagrant will forward port 4567 to the Forum server running in the VM.)

Running LMS/Studio Tests

  • Within the VM instance, switch to the edxapp account
sudo su edxapp
  • Run the Python unit tests
rake test:python
  • Run the JavaScript unit tests
rake test:js
  • Run the LMS and Studio acceptance tests
rake test:acceptance

See the docs on testing edx-platform for detailed information about writing and running tests.

Updating Application Versions

Use vagrant provision to update the configuration and all repositories to the master branch. NOTE: this will perform a git clean on your repositories, so make sure you have committed any changes you want to save.

Issues / Workarounds

  • If you are using empanada and get a message like this when running vagrant up for the first time, then run vagrant provision. This will reprovision the virtual machine with the latest configuration repo contents, instead of what was on the virtual server when the empanada image was cut.
TASK: [local_dev | create login scripts] ************************************** 
fatal: [localhost] => input file not found at /edx/app/edx_ansible/edx_ansible/playbooks/roles/local_dev/templates/edxapp_bashrc.j2 or /edx/app/edx_ansible/edx_ansible/playbooks/edxapp_bashrc.j2

FATAL: all hosts have already failed -- aborting

PLAY RECAP ******************************************************************** 
           to retry, use: --limit @/root/vagrant-devstack.retry

localhost                  : ok=172  changed=64   unreachable=1    failed=0

  • If the /edx/app/edx/edx-platform directory in the Vagrant image is empty, it means the provisioning scripts did not complete successfully. Try re-running the provisioning scripts using vagrant provision.

  • If vagrant up shows directories not existing, such as:

/tmp/vagrant-shell: line 1: /edx/app/edx_ansible/venvs/edx_ansible/bin/activate: No such file or directory

then there is possibly something not quite up to date with the base vagrant box (which is assumed to be properly configured, and is provided for you). You can always try to build a current box yourself from the configuration/vagrant/base/devstack directory. This will take longer, and require more setup on your part (such as checking out all the appropriate repositories in advance).

  • If you see this message:
    !! ERROR !!

    The last command did not complete successfully,
    For more details or trying running the
    script again with the -v flag.

check that you are running Vagrant commands in the directory containing the devstack Vagrantfile, NOT from the edx-platform directory. There is an older Vagrantfile in edx-platform that will eventually be deprecated in favor of devstack.

  • If you see this error when running a manage.py command:
[Errno 2] No such file or directory: u'/edx/app/edxapp/log/edx.log'

you need to add --settings=devstack to the command. (The default settings assume a legacy directory structure. Eventually, we may change the default settings to devstack.)

  • If you see this error when attempting to run the server:
pymongo.errors.ConnectionFailure: could not connect to localhost:27017: [Errno 111] Connection refused

Then, from a vagrant user shell, you should sudo rm /edx/var/mongo/mongodb/mongod.lock, and then sudo start mongodb. (You get this error if you shut down an instance of lms/studio/etc without letting Mongo delete its lock; this lets you forcibly delete the lock so you can run the server again.)

  • Ubuntu: if you see this message:
* 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. If the problem persists, please
contact Vagrant support.

you need to install nfs using this command:

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

  • If you get an error such as NS_ERROR_FAILURE, try upgrading VirtualBox (4.3.2 seems to solve this on OS/X Mavericks).

  • If you are working on an Ubuntu workstation and your home directory is encrypted you will likely run into NFS problems. To work around the issue set VAGRANT_MOUNT_BASE to a dir outside the encrypted volume.

  • Mac OS X: Sometimes, NFS fails the first time you start Vagrant on Mac OS X. If you see this message:

[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,udp' 192.168.33.1:'/path/to/devstack/edx-platform' /edx/app/edxapp/edx-platform
Stdout from the command:
Stderr from the command:
stdin: is not a tty
mount.nfs: requested NFS version or transport protocol is not supported

then reload and re-provision the instance using these commands:

vagrant reload
vagrant provision
Add a custom footer
Add a custom sidebar
Clone this wiki locally