Setting up the solutions devstack

Initial machine provisioning

1. Install Vagrant (brew cask install virtualbox && brew cask install vagrant or sudo apt-get install virtualbox vagrant)

2. Optional: Install a normal edX master devbox - make sure you know how to do this.

3. Create a folder for your solutions devstack. The following structure is recommended:
   devstack/ (optional upstream devstack - contains Vagrantfile, edx-platform, etc.)
   devstack-solutions/ (this will be the new devstack - will contain Vagrantfile, edx-platform, etc.)
   src/ (directory where XBlocks can be installed and shared by both devstacks)

4. Download this Vagrantfile and save it into the devstack-solutions folder.

5. Open a terminal in the devstack-solutions folder and run the command vagrant up. If any error occurs, fix it an then run vagrant provision to resume the setup.

   • For example, if you encounter a long error message containing Permission denied: '/edx/app/edx_ansible/venvs/edx_ansible/lib/python2.7/site-packages/bson/__init__.py, then run vagrant ssh, sudo su, source /edx/app/edx_ansible/venvs/edx_ansible/bin/activate, pip uninstall pymongo, then on your host run vagrant provision.
   • If you encounter error with apt-get update ran by playbook, then run vagrant ssh, sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 69464050, then on your host run vagrant provision.
   • If you use Arch Linux, make sure to enable v3 and UDP support for NFS (as described [here]

(https://wiki.archlinux.org/index.php/Vagrant#Mounting_NFS_shared_folders:_mount.nfs:_requested_NFS_version_or_transport_protocol_is_not_supported)).

When the script completes successfully, you will have a fully functional upstream devstack, running ginkgo.master release. You might want to spin it up and make sure LMS and Studio works as expected (see instructions on running devstack).

Switching to solutions fork

Next, checkout the solutions fork of edx-platform into your edx-platform repo. If you want to support multiple remotes, we recommend making origin point to edx-solutions/edx-platform and having upstream point to edx/edx-platform. To do so, on your host, change the directories to where devstack checked out edx/edx-platform.

If the creation of the new master branch is disrupted because a branch named master already exists, use a different branch name. For example, instead of 'git checkout -b master origin/master', you may use 'git checkout -b solutions_master origin/master'.

cd ~/solutions/edx-platform  # For example, in case your Devstack is built in ~/solutions; otherwise, change this path
git remote add solutions https://github.com/edx-solutions/edx-platform.git
git remote rename origin upstream
git remote rename solutions origin
git fetch origin
git checkout -b master origin/master

We also use a forked version of the cs_comment_client repo. To use that, in your host:

cd ~/solutions/cs_comments_service # For example, in case your Devstack is built in ~/solutions; otherwise, change this path
git remote add solutions https://github.com/edx-solutions/cs_comments_service.git
git remote rename origin upstream
git remote rename solutions origin
git fetch origin
git checkout origin/master -b master

Updating dependencies

Next, vagrant ssh into the Vagrant box, then we have to update the Python dependencies. As the vagrant user, run:

sudo su edxapp	# Make sure prompt reads ~/edx-platform
unset NO_PREREQ_INSTALL
# Clean out all files which aren't tracked by git, like old precompiled python files and some generated CSS.
git clean -fx
paver install_prereqs

You might want to (and most certainly will at some point) install additional packages or different versions of existing packages into virtualenv. However, commands used to run LMS/Studio (paver devstack lms) check dependencies hash first thing and reinstall everything if hash does not match the one generated after last paver install_prereqs. To avoid that, make sure you're running it with NO_PREREQ_INSTALL=1; the easiest way to ensure that is to add it to ~/.bashrc:

export NO_PREREQ_INSTALL=1

Configuring environment

We also have to turn on some features in the /edx/app/edxapp/lms.env.json file before re-generating the database. Add these entries within the FEATURES section of lms.env.json:

    "FEATURES": {
        ...
        "EDX_SOLUTIONS_API": true,
        "MARK_PROGRESS_ON_GRADING_EVENT": true,
        "SIGNAL_ON_SCORE_CHANGED": true,
        "ORGANIZATIONS_APP": true,
        "ENABLE_XBLOCK_VIEW_ENDPOINT": true,
        "ENABLE_NOTIFICATIONS": true
    },

Next, update the MODULESTORE entry in /edx/app/edxapp/lms.auth.json and /edx/app/edxapp/cms.auth.json. It looks like this:

    "MODULESTORE": {
        "default": {
            "ENGINE": "xmodule.modulestore.mixed.MixedModuleStore", 
            "OPTIONS": {
                "mappings": {}, 
                "stores": [
                    {
                        "DOC_STORE_CONFIG": {...settings...}, 
                        "ENGINE": "xmodule.modulestore.split_mongo.split_draft.DraftVersioningModuleStore", 
                        "NAME": "split", 
                        "OPTIONS": {...settings...}
                    },
                    {
                        "DOC_STORE_CONFIG": {...settings...}, 
                        "ENGINE": "xmodule.modulestore.mongo.DraftMongoModuleStore", 
                        "NAME": "draft", 
                        "OPTIONS": {...settings...}
                    }
                ]
            }
        }
    }, 

Just swap the items in the stores list, so that the one with "NAME": "draft" is on top. Please make sure to do that both in lms.auth.json and cms.auth.json - omitting this change for cms.auth.json is a common mistake.

This is required because currently the solutions platform is not tested with Split and is known to have trouble with it.

Database migration

We will now need to update the DB to include these applications and the custom fields we've added to other apps. Unfortunately, the base VM box has some discrepancies in migrations actually applied to the DB and migrations registered with migration engine, so we'll have to fake them:

1. Unapply student migrations ./manage.py lms migrate student zero --settings=devstack - solutions fork added a couple of fields as way back as migration 0001, but base VM box have those migration applied without those fields. (note for the next rebase: updating upstream migration code isn't a good idea).
2. Finally, migrate everything with ./manage.py lms migrate --settings=devstack

Verifying the setup

After all of these steps, you may want to return to the edxapp user and run all unit tests to verify the integrity of the runtime environment:

paver test_python

Try running LMS and/or Studio:

sudo su edxapp
paver devstack lms

Verify it actually works:

1. Open http://localhost:8000/ in your favorite browser. If it crashes right away with process() takes exactly 3 arguments (2 given) there's a problem with django-debug-toolbar version used (at the time of writing 1.3.2). Upgrade to 1.5 with pip install django-debug-toolbar==1.5, then make sure we're still on Django 1.8 (pip freeze | grep Django) and NO_PREREQ_INSTALL is set to 1 when you run LMS/Studio.
2. Log in as staff.
3. Navigate to dashboard. If it crashes with "column auth_userprofile.title not found" - please make sure you've reapplied student app migrations from the beginning, as instructed in "Database migration" section, step 4.