Setting up the solutions devstack

Initial machine provisioning

Follow the instructions about prerequisites at the Installing Open edX Devstack Readthedocs page, except:

• If your OS uses systemd sudo nfsd status should be sudo service nfs-server status (at least on Ubuntu).
• When instructed to set $OPENEDX_RELEASE variable, set it to open-release/eucalyptus.master instead. At the moment of writing readthedocs uses more conservative open-release/eucalyptus.1, but they shouldn't differ dramatically; although this certainly will change in the future, where docs are updated to Ficus and next "tree" releases.
• When creating a base directory (mkdir devstack) you might want to give it a different name, i.e. solutions

Run the bash install_stack.sh devstack and wait for it to complete - it should take more than an hour. In case of any errors, at this step, try the following, in order:

• Issue the vagrant provision command.
• Check if this is an obvious error (to you) and correct it.
• Destroy the machine (via Virtualbox UI) and try again once.
• If all else fails - panic and ask for help.

When the script completes successfully, you will have a fully functional upstream devstack, running eucalyptus.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

In order to simplify your life a bit, you might want to edit Vagrantfile to pin OPENEDX_RELEASE to the version you've used - in Vagrantfile and change this line:

rel = ENV['OPENEDX_RELEASE']

...to:

rel = "open-release/eucalyptus.master"

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

cd ~/solutions/edx-platform  # for example, in case your Devstack is built in ~/devstack, 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 ~/devstack/cs_comments_service # For example, in case your Devstack is built in ~/devstack, 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

Configuring environment

We also have to turn on some features in the /edx/app/edxapp/lms.env.json file before re-generating the database

        "API": true,
        "MARK_PROGRESS_ON_GRADING_EVENT": true,
        "SIGNAL_ON_SCORE_CHANGED": true,
        "ORGANIZATIONS_APP": true,
        "ENABLE_XBLOCK_VIEW_ENDPOINT": true,

Next, update the MODULESTORE entry in lms.auth.json and 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 items in 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 to cms.auth.json is a common caveat.

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, base VM box have some discrepancies in migrations actually applied to the DB and migrations registered with migration engine, so we'll have to fake them:

1. Fake course_groups 0002: ./manage.py lms migrate course_groups 0002 --settings=devstack --fake
2. Fake course_structures 0002: ./manage.py lms migrate course_structures 0002 --settings=devstack --fake
3. Fake teams 0002: ./manage.py lms migrate teams 0002 --settings=devstack --fake
4. 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).
5. 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 localhost:8000 in browser 1.1. 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 moment of writing 1.3.2). Upgrade to 1.5 with pip install django-debug-toolbar==1.5 + make sure we're still on Django 1.8 (pip freeze | grep Django)
2. Log in as staff
3. Navigate to dashboard 3.1. 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.