This is the main edX platform which consists of LMS and Studio.
See code.edx.org for other parts of the edX code base.
Installation - The first time
The following instructions will help you to download and setup a virtual machine with a minimal amount of steps, using Vagrant. It is recommended for a first installation, as it will save you from many of the common pitfalls of the installation process.
- Make sure you have plenty of available disk space, >5GB
- Install Git: http://git-scm.com/downloads
- Install VirtualBox: https://www.virtualbox.org/wiki/Downloads See http://docs.vagrantup.com/v2/providers/index.html for a list of supported Providers. You should use VirtualBox >= 4.2.12. (Windows: later/earlier VirtualBox versions than 4.2.12 have been reported to not work well with Vagrant. If this is still a problem, you can install 4.2.12 from http://download.virtualbox.org/virtualbox/4.2.12/).
- Install Vagrant: http://www.vagrantup.com/ (Vagrant 1.2.2 or later)
- Open a terminal
- Download the project:
git clone https://github.com/edx/edx-platform.git
- Enter the project directory:
- (Windows only) Run the commands to deal with line endings and symlinks under Windows
- Create the development environment and start it:
vagrant up will download a Linux image, then boot and ask for your
host machine's administrator password to setup file sharing between your computer and the VM.
Once file sharing is established,
install dependencies and configure the VM.
This will take a while; go grab a coffee.
When complete, you should see a "Success!" message. If not, refer to the troubleshooting section.
Your development environment is initialized only on the first bring-up.
vagrant up commands will boot your virtual machine normally.
Note: by default, the VM will get the IP
You can change this in your
Vagrantfile (the startup message will reflect your VM's actual IP).
Accessing the VM
Once the installation is finished, to log into the virtual machine:
$ vagrant ssh
Note: This won't work from Windows. Instead, install PuTTY from http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html. Then connect to 192.168.20.40, port 2222, using vagrant/vagrant as a user/password.
When you login to your VM, you are in
/opt/edx/edx-platform by default, which is shared from your host workspace.
Your host computer contains the edx-project development code and repository.
Your VM runs edx-platform code mounted from your host, so
you can develop by editing on your host.
After logging into your VM with
start the Studio and
Learning management system (LMS)
servers (run these from
Learning management system (LMS):
$ rake lms[cms.dev,0.0.0.0:8000]
$ rake cms[dev,0.0.0.0:8001]
The servers will come up to these URLs:
Your VM's port 8000 is forwarded to host port 9000
so you can also access the LMS with http://localhost:9000/.
Similarly, VM port 8001 is forwarded to host port 9001.
These are set in your
Note that when you register a new user through the web interface, by default the activiation email will be appear on your VM's terminal. Search for lines similar to:
Subject: Your account for edX Studio From: email@example.com
and find the activation URL.
See the Frequently Asked Questions for more usage tips.
Django admin & debug toolbar
You can enable admin logins and the debug_toolbar by editing
- enable ADMIN login page by setting:
- ``` 'ENABLE_DJANGO_ADMIN_SITE': True
- enable debug toolbar by uncommenting: - ``` # 'debug_toolbar.middleware.DebugToolbarMiddleware',
These are also defined in
and usually active on localhost.
To get at your VM's 127.0.0.1, explicitly forward one of VM's available localhost ports to your computer.
vagrant ssh, login with:
$ ssh -L 6080:127.0.0.1:8080 firstname.lastname@example.org
The password is vagrant.
From your VM, start the LMS as a localhost instance:
$ rake lms[cms.dev,127.0.0.1:8080]
You should see the debug toolbar now on http:/localhost:6080/. You should now also see a login on http://localhost:6080/admin/ You will need a privileged user for the admin login. You can create a CMS/LMS super-user with:
$ ./manage.py lms createsuperuser
Stopping & starting
To stop the VM (from your
$ vagrant halt
$ vagrant up
To suspend and resume tasks in progress on your VM:
$ vagrant suspend $ # and later... $ vagrant resume
Your development environment is normally created once, on first
You can continue to fetch changes in edx-platform
as you work with your VM.
To re-create your VM and create a fresh development environment:
$ vagrant destroy $ vagrant up # will make a new VM
If anything doesn't work as expected, see the troubleshooting section.
Installation - Advanced
Note: The following installation instructions are for advanced users & developers who are familiar with setting up Python, Ruby & node.js virtual environments. Even if you know what you are doing, edX has a large code base with multiple dependencies, so you might still want to use the method described above the first time, as Vagrant helps avoiding issues due to the different environments.
There is a
scripts/create-dev-env.sh that will attempt to set up a development
If you want to better understand what the script is doing, keep reading.
This code assumes that it is checked out in a directory that has three sibling
data (used for XML course data),
db (used to hold a
sqlite database), and
log (used to hold logs). If you
clone the repository into a directory called
edx inside of a directory
dev, here's an example of how the directory hierarchy should look:
* dev \ * data * db * log * edx \ README.md
You'll need to be sure that you have Python 2.7, Ruby 1.9.3, and NodeJS (latest stable) installed on your system. Some of these you can install using your system's package manager: homebrew for Mac, apt for Debian-based systems (including Ubuntu), rpm or yum for Red Hat based systems (including CentOS).
If your system's package manager gives you the wrong version of a language
runtime, then you'll need to use a versioning tool to install the correct version.
Usually, you'll need to do this for Ruby: you can use
rbenv is simpler. For Python, you can use
and for Node, you can use
Often, different projects will have conflicting dependencies: for example, two projects depending on two different, incompatible versions of a library. Clearly, you can't have both versions installed and used on your machine simultaneously. Virtual environments were created to solve this problem: by installing libraries into an isolated environment, only projects that live inside the environment will be able to see and use those libraries. Got incompatible dependencies? Use different virtual environments, and your problem is solved.
Remember, each language has a different implementation. Python has
virtualenv, Ruby has
bundler, and Node's virtual environment support
is built into
npm, its library management tool.
For each language, decide if you want to use a virtual environment, or if you
want to install all the language dependencies globally (and risk conflicts).
I suggest you start with installing things globally until and unless things
break; you can always switch over to a virtual environment later on.
The Python libraries we use are listed in
requirements.txt. The Ruby libraries
we use are listed in
Gemfile. The Node libraries we use are listed in
packages.json. Python has a library installer called
pip, Ruby has a library installer called
bundle if you're using a virtual
environment), and Node has a library installer called
Once you've got your languages and virtual environments set up, install
the libraries like so:
$ pip install -r requirements/edx/pre.txt $ pip install -r requirements/edx/base.txt $ pip install -r requirements/edx/post.txt $ bundle install $ npm install
You can also use
rake to get all of the prerequisites (or to update)
them if they've changed
$ rake install_prereqs
You'll also need to install MongoDB, since our
application uses it in addition to sqlite. You can install it through your
system package manager, and I suggest that you configure it to start
automatically when you boot up your system, so that you never have to worry
about it again. For Mac, use
brew info mongodb will give you some commands you can copy-paste.)
For Linux, you can use
or any other process management tool.
Configuring Your Project
Before you run your project, you need to create a sqlite database, create
tables in that database, and run database migrations. Fortunately,
will do all of this for you
$ ./manage.py lms syncdb --migrate $ ./manage.py cms syncdb --migrate
Run Your Project
edX has two components: Studio, the course authoring system; and the LMS (learning management system) used by students. These two systems communicate through the MongoDB database, which stores course information.
rake to execute common tasks in our
rake tasks are defined in the
rakefile, or you can run
to view a summary.
To run Studio, run:
$ rake cms
To run the LMS, run:
$ rake lms[cms.dev]
Studio runs on port 8001, while LMS runs on port 8000, so you can run both of
these commands simultaneously, using two different terminal windows. To view
127.0.0.1:8001 in your web browser; to view the LMS, visit
There's also an older version of the LMS that saves its information in XML files
data directory, instead of in Mongo. To run this older version, run:
$ rake lms
The code in this repository is licensed under version 3 of the AGPL unless otherwise noted.
LICENSE.txt for details.
High-level documentation of the code is located in the
doc subdirectory. Start
overview.md to get an introduction to the architecture of the system.
How to Contribute
Contributions are very welcome.
Please read How To Contribute for details.
Reporting Security Issues
Please do not report security issues in public. Please email email@example.com
Mailing List and IRC Channel
You can discuss this code on the edx-code Google Group or in the
edx-code IRC channel on Freenode.