Home

About

This repo holds the scripts used to set up and operate the edX platform.

• Ansible -- takes raw compute resources and configures them so they can run edX services.
• CloudFormation -- provision and set up the set of services you need to host the edX stack with Amazon Web Services. A lot of the Amazon alphabet soup is brought to the party:
  • Servers (EC2)
  • Network access control, NAT, and policy (VPC)
  • Primary Student Database in MySQL (RDS)
  • Load Balancers (ELB)
  • Memcache (ElastiCache)

Please see our Ansible coding conventions before contributing to this repo.

Where to get more info

• The Mailing list 'edx-code' on googlegroups.
• The IRC is '#edx-code' on freenode.
• The FAQ is in this wiki.

Installation

There are two types of configurations that are commonly used for edX deployments, the fullstack and the devstack

Installing edX using a pre-built Vagrant fullstack image

The fullstack configuration has the following components:

• LMS (student facing website)
• Studio (course authoring)
• Xqueue (queuing server that uses RabbitMQ for custom graders)
• Forums / elasticsearch / ruby (discussion forums)
• Demo course
• ORA - take a submission, passes it through machine learning grading, peer grading, and staff grading as appropriate
• Discern - machine-learning-based automated textual classification as an API service
• Ease - a library that allows for machine learning based classification of textual content

Install instructions

• Install VirtualBox >= 4.2.12 and Vagrant >= 1.3.1
• Run the following commands:

git clone https://github.com/edx/configuration
cd configuration
sudo pip install requirements.txt # or use a python virtualenv
cd vagrant/release/dosa/fullstack
vagrant up --no-provision

The first time you create the instance, Vagrant will download the base box, which is about 2GB. After downloading the base box, Vagrant will automatically provision your new virtual server using the Ansible scripts from this repo. If you destroy and recreate the VM, Vagrant will re-use the box it downloaded.

Installing edX using a pre-built Vagrant devstack image

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)
• Demo course

Install instructions

• Install VirtualBox >= 4.2.12 and Vagrant >= 1.3.4
• Install the vagrant-hostsupdater plugin:

    vagrant plugin install vagrant-hostsupdater

• Run the following commands

git clone https://github.com/edx/configuration
cd configuration
sudo pip install requirements.txt # or use a python virtualenv
cd vagrant/release/dosa/devstack
vagrant up --no-provision

The first time you create the instance, Vagrant will download the base box, which is about 2GB. After downloading the base box, Vagrant will automatically provision your new virtual server using the Ansible scripts from this repo. If you destroy and recreate the VM, Vagrant will re-use the box it downloaded.

For instructions on how to use the devstack see https://github.com/edx/configuration/wiki/Using-the-edX-devstack

Installing edX on a single Ubuntu 12.04 virtual machine with 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.12)''' and '''Vagrant (1.3.1 or later)'''.

• Clone the configuration repo

git clone -b release https://github.com/edx/configuration

• Install the ansible requirements

sudo pip install -r configuration/requirements.txt

• Run "vagrant up" for the "shortstack" playbook

cd configuration/vagrant/shortstack
vagrant up

• Run "vagrant up" for the "fullstack" playbook (optional)

cd configuration/vagrant/fullstack
vagrant up

• Run "vagrant up" for the "devstack" playbook (optional)

cd configuration/vagrant/devstack
vagrant up

See https://github.com/edx/configuration/blob/master/vagrant/devstack/README.rst for usage instructions.

After installation connect your web browser to the following ports:

• LMS - 80
• Studio - 18010

Installing edX on a single Ubuntu 12.04 (Precise) server

WARNING: These instructions will potentially destroy the server they are run on, you should only do them on a virtual machine.

• Launch an Ubuntu 12.04 server and login to it as a user that has full sudo privileges

• Install the following packages on the server you are provisioning:

sudo apt-get install -y python-pip git-core build-essential python-dev libxml2-dev libxslt-dev

• On the new server, clone the configuration repo:

cd /var/tmp

git clone -b release https://github.com/edx/configuration

• Install the ansible requirements

cd /var/tmp/configuration

sudo pip install -r requirements.txt

• Run the edx_sandbox.yml playbook in the configuration/playbooks directory

cd /var/tmp/configuration/playbooks

sudo ansible-playbook -c local --limit "localhost:127.0.0.1" \
./edx_sandbox.yml -i "localhost,"

After installation connect your web browser to the following ports:

• LMS - 80
• Studio - 18010

Overriding default web ports

You may want to override the default ports for Studio and lms-preview if you are setting up subdomains to connect to your sandbox. By default nginx will forward studio.* to the studio gunicorn process.

Example where preview.example.com, example.com and studio.example.com all point to the same server.

cd /var/tmp/configuration/playbooks

ansible-playbook -c local --limit "localhost:127.0.0.1" /var/tmp/configuration/playbooks/edx_sandbox.yml \
-i "localhost," -e 'cms_nginx_port=80  lms_preview_nginx_port=80  c_lms_base=example.com \
c_preview_lms_base=preview.example.com'

Other links

• Stanford notes
• AWS Installation Notes